About retrospecting
Retrospecting is the third of Vinaya's four stages. It answers one question: what shipped, and why. Its output is a closed task, a closed tranche, a closed Goal, and the record they leave on the forge. See the Overview for how the four stages fit together.
It is archiving only. It closes records; it does not judge or change the work. Merging is not part of it: landing a change is the Principal's act and happens before retrospecting starts.
| What closes | Who closes it | What is recorded |
|---|---|---|
| A task | The Archivist, on the merged pull request | A provenance block, the Issue closed, missing facts flagged as dangling |
| A tranche | The Tranche Archivist, or the vinaya archive tranche command | A retrospective; the Milestone closed when nothing holds it open |
| A Milestone | Closes when its declared tranches are complete | The Goal's disposition |
| Drift | Ring 2 audits | Pushes to finished branches, direct pushes to main |
How it works
Most of retrospecting runs by itself, from a generated workflow, on events and on a schedule. The judgement work is a dispatched role turn that re-confirms what the automation did rather than repeating it.
- 1
A pull request merges to main
The post-merge job runs
vinaya archive -. It posts the provenance comment, then closes the task Issue and confirms it is closed. It then runs- merge- sha=<sha> vinaya archive tranche <slug> -, which archives the tranche if this was its last open task.- yes - 2
A task Issue closes without a merge
The issue-closed job runs
vinaya archive tranche <slug> -, so a dropped or replaced task can still finish its tranche.- yes - 3
Every day at 02:00 UTC
The daily drift job runs
vinaya audit -, then- only=dead- branches vinaya archive tranches -to catch any finished tranche the events missed.- yes - 4
Any push to main
The direct-push job runs
vinaya audit -and fails when the push skipped the pull-request path.- only=direct- push - - sha=<sha> - 5
The Principal asks for the Tranche Archivist
"Run the Tranche Archivist for tranche <name>." The turn verifies the forge, writes the retrospective on the pinned lessons Issue, closes the Milestone and posts tranche provenance.
The judgement half of a task close (docs coherence, the docs index, the token ledger, lessons notes) is a dispatched Archivist turn.
Who does what
| Role | Does | Never does | Human or agent |
|---|---|---|---|
| Archivist | Closes out one merged task: Issue closed, provenance posted, docs coherence and token rows confirmed, cleanups flagged | Write status, author a provenance field, reopen or re-argue the work, merge, perform cleanups | Either |
| Tranche Archivist | Closes out a finished tranche on the Principal's explicit declaration: forge verified, retrospective, Milestone closed, pending ratifications surfaced, tranche provenance | Write code, decide what is next, ratify, invent observations, edit the plan, delete anything, run undispatched | Either |
| Principal | Declares a tranche done; ratifies pending Type 1 decisions; acts on flagged cleanups | — | Person |
Work passes between roles in this order:
- The Reviewer and Security hand their verdicts to the Archivist.
- The Archivist hands the Tranche Archivist the merged pull requests with their provenance comments, the lessons-Issue notes and the follow-up Issues.
- The Tranche Archivist hands the Planner the closed Milestone and the retrospective.
See Roles for every role and hand-off.
Ring 2 gates
Retrospecting is Ring 2: checks that run after merge, on the forge, whatever wrote the change. Ring 2 cannot undo a merge. It turns drift into findings in the record.
| Mechanism | When | What it does |
|---|---|---|
| Post-merge task archive | On every merge | Posts provenance, checks for dangling records, closes the task Issue |
| Tranche self-archive | When a task Issue closes, merged or not | Closes the tranche when its last task is done |
| Daily drift check | Daily | Reports pushes to branches whose work is already finished; never fails red |
| Daily tranche catch-up | Daily | Archives completed tranches the events missed |
| Direct-main-push detection | On every push to the default branch | Fails when a push skipped the pull-request path |
Task close
The Archivist on every merge: provenance, dangling facts, Issue closed
Tranche and Milestone close
The tranche archive, the Tranche Archivist and when a Milestone closes
Ring 2 audits
Each job's trigger, report and failure behaviour
Configuration
| Key | Effect |
|---|---|
rings. | false makes vinaya archive (task close) and the dead-branch audit skip. It does not skip archive tranche, archive tranches or direct-main-push detection. Default true. |
principals | A Tokens: line counts only from a comment an allowlisted principal wrote. |
managed | The workflow . is generated by vinaya init and regenerated by vinaya upgrade. |
What gets logged
| Act | Log events |
|---|---|
| Archivist and Tranche Archivist turns | dispatch, role_attempt, usage |
Each vinaya archive and audit run | One operation · completed |
See Events for every field.