heyspex 0.2.2 → 0.2.4

package/dist/cli-templates/customer-vault/specs/protocols/session-close-protocol.md

@@ -1,91 +1,178 @@
----
-id: HS-PROTO-session-close-protocol
-name: Session Close Protocol
-type: protocol
-status: open
-priority: 1
-owner: TODO — your name/handle
-created: '2026-05-14T22:47:28-05:00'
-updated: '2026-09-11'
-scope: session
-tags:
-  - session
-  - close-out
-  - workflow
-  - review
-triggers:
-  - close_session
-summary: |
-  Splits session close into the agent's terminal actions (submit for review, change-log row, WIP ledger, audit export, housekeeping) and the reviewer's job (walk the acceptance criteria, materialize memories, commit). The agent does not commit or push.
-related:
-  - "[[memory-protocol]]"
-  - "[[spec-hierarchy]]"
-  - "[[entity-model]]"
----
-
-# Session Close Protocol
-
-Session close splits cleanly into two responsibilities: the **agent's terminal actions** (flip status through the API, write the hand-off, leave the tree for review) and the **reviewer's job** (walk the acceptance criteria, decide accept or reject, commit). The agent does not commit and does not push; the reviewer's commit is the close action.
-
-## When to close — the agent can call last orders
-
-Closing procedures are encouraged at every wrap-up, and starting them is not the user's job alone.
-
-- **Self-initiated close-out.** When the session's work is done (deliverables complete, verification reported, no pending user ask) the agent announces in one line that it is closing out and runs the steps below without being asked.
-- **Guide the user at done-ness signals.** When the user signals completion ("that's all", "looks good", an end-of-day sign-off), offer or start close-out in the same reply.
-- **Scope guardrail.** A self-initiated close performs only what the thread type owes. It is never a license to expand the work.
-
-Call `heyspex_preflight({ intent: "close_session" })` first; it returns the procedures to consult for this session.
-
-## Thread-type close-out — what kind of session was this? (ask first)
-
-Close-out is not one-size-fits-all. Identify what the session actually did and apply only the matching path.
-
-| Thread type | How you can tell | Close-out path |
-|---|---|---|
-| **Capture-only** | Only captured ideas; no claim, no code | No close-out. Promote the capture to research or leave it pinned. |
-| **Research-only** | Saved a research doc; no claimed spec | Save the research. Research is evergreen: no submit, no status flip. |
-| **Plan / ingest-only** | Filed milestones and epics; no task execution | Run `heyspex_validate_linkage`; confirm each spec has a `summary`. No task close. |
-| **One-task execution** | Claimed and finished a single task | Steps 1–8 below for that one unit. |
-| **Multi-task / epic push** | Claimed and finished several tasks | Steps 1–8; submit each unit; one consolidated WIP ledger. |
-| **Mid-implementation rollover** | Claimed but not finished | Not a close. Record a lightweight WIP checkpoint only and leave the spec `in_progress`. |
-
-Mixed threads run the union of the matching paths, in order. Every step is safe to re-run.
-
-## Agent terminal actions (end of session)
-
-For every spec the agent completed this session:
-
-1. **Submit build-complete through the status API.** Call `heyspex_submit_for_review({ spec_id: "<id>" })` on each completed unit. Never hand-edit `status:` in frontmatter; the status API is the single source of truth and a frontmatter-only flip does not drive the progress ladder.
-2. **Report acceptance progress.** Call `heyspex_report_progress` with `acProgress` for each criterion you verified, so the acceptance checklist reflects the real state.
-3. **Append a change-log row** to the spec: `| YYYY-MM-DD | <agent + model> | <one-line summary> |`.
-4. **Record the structured handoff.** Call `heyspex_record_wip({ spec_id: "<epic-id>", specs_filed, remaining, verified, notes })` for the epic you worked. It is the machine-readable hand-off the next session's `/hs-next` surfaces.
-5. **Flush the audit export.** Call `heyspex_export_events` (or `hs export-events`) so this session's claim and status events are written to the vault.
-6. **Capture knowledge worth keeping.** Propose memory candidates (lessons, decisions, references) per [[memory-protocol]]; the reviewer decides which to materialize.
-7. **Run housekeeping.** Run `heyspex_validate_linkage` and fix anything that is already yours to fix. Then say plainly, once, what is left that only the owner can act on.
-8. **Do not `git commit` and do not `git push`**, unless this vault has opted in to agent commits. Leave the working tree dirty; the reviewer's commit is the close action.
-
-If a spec was only partly completed, leave it `in_progress` and do not submit it. Status hand-off is for work the agent considers reviewer-ready.
-
-## The close-out write-up — every named item says fixed or not fixed
-
-The steps above decide what gets recorded. This section decides how the close-out message reads. The most important fact about any item is whether the thing works now, and that fact goes first on the line, in one of four words:
-
-| Word | Means |
-|---|---|
-| **Fixed** | The problem is gone. Verified, and the line names the check that proved it. |
-| **Partly fixed** | Some of it shipped. The line says which part did and which did not. |
-| **Not fixed** | Found and recorded. Nothing works differently than before. |
-| **Not started** | Named as work, not begun. |
-
-1. The word comes first on the line.
-2. Every named item carries one.
-3. Fixed and not-fixed items go in separate groups.
-4. "Filed", "flagged", "captured", "noted" and "handled" describe a record, never an outcome. They may follow one of the four words but never replace one.
-
-## Reviewer responsibilities (human, separate pass)
-
-1. Read each review companion or change-log entry. Walk the acceptance criteria against the actual diff.
-2. Decide accept, edit or reject for every memory candidate. Materialize accepted ones as files under `specs/memory/<type>s/<slug>.md`, linked back to the parent spec.
-3. On **pass**: commit the diff, including any materialized memories and the status flip. The commit is the close action.
-4. On **reopen**: leave the spec `in_review`, document the gap, and the next agent session picks it up.
+---
+id: HS-PROTO-session-close-protocol
+name: Session Close Protocol
+type: protocol
+status: open
+priority: 1
+owner: TODO — your name/handle
+created: '2026-05-14T22:47:28-05:00'
+updated: '2026-10-16'
+scope: session
+tags:
+  - session
+  - close-out
+  - workflow
+  - review
+triggers:
+  - close_session
+summary: |
+  Splits session close into the agent's terminal actions (submit for review, change-log row, WIP ledger, audit export, housekeeping) and the reviewer's job (walk the acceptance criteria, materialize memories, commit). The agent does not commit or push.
+related:
+  - "[[memory-protocol]]"
+  - "[[spec-hierarchy]]"
+  - "[[entity-model]]"
+---
+
+# Session Close Protocol
+
+Session close splits cleanly into two responsibilities: the **agent's terminal actions** (flip status through the API, write the hand-off, leave the tree for review) and the **reviewer's job** (walk the acceptance criteria, decide accept or reject, commit). The agent does not commit and does not push; the reviewer's commit is the close action.
+
+## When to close — the agent can call last orders
+
+Closing procedures are encouraged at every wrap-up, and starting them is not the user's job alone.
+
+- **Self-initiated close-out.** When the session's work is done (deliverables complete, verification reported, no pending user ask) the agent announces in one line that it is closing out and runs the steps below without being asked.
+- **Guide the user at done-ness signals.** When the user signals completion ("that's all", "looks good", an end-of-day sign-off), offer or start close-out in the same reply.
+- **Scope guardrail.** A self-initiated close performs only what the thread type owes. It is never a license to expand the work.
+
+Call `heyspex_preflight({ intent: "close_session" })` first; it returns the procedures to consult for this session.
+
+## Thread-type close-out — what kind of session was this? (ask first)
+
+Close-out is not one-size-fits-all. Identify what the session actually did and apply only the matching path.
+
+| Thread type | How you can tell | Close-out path |
+|---|---|---|
+| **Capture-only** | Only captured ideas; no claim, no code | No close-out. Promote the capture to research or leave it pinned. |
+| **Research-only** | Saved a research doc; no claimed spec | Save the research. Research is evergreen: no submit, no status flip. |
+| **Plan / ingest-only** | Filed milestones and epics; no task execution | Run `heyspex_validate_linkage`; confirm each spec has a `summary`. No task close. |
+| **One-task execution** | Claimed and finished a single task | Steps 1–8 below for that one unit. |
+| **Multi-task / epic push** | Claimed and finished several tasks | Steps 1–8; submit each unit; one consolidated WIP ledger. |
+| **Mid-implementation rollover** | Claimed but not finished | Not a close. Record a lightweight WIP checkpoint only and leave the spec `in_progress`. |
+
+Mixed threads run the union of the matching paths, in order. Every step is safe to re-run.
+
+## Agent terminal actions (end of session)
+
+For every spec the agent completed this session:
+
+1. **Submit build-complete through the status API.** Call `heyspex_submit_for_review({ spec_id: "<id>" })` on each completed unit. Never hand-edit `status:` in frontmatter; the status API is the single source of truth and a frontmatter-only flip does not drive the progress ladder.
+2. **Report acceptance progress.** Call `heyspex_report_progress` with `acProgress` for each criterion you verified, so the acceptance checklist reflects the real state.
+3. **Append a change-log row** to the spec: `| YYYY-MM-DD | <agent + model> | <one-line summary> |`.
+4. **Record the structured handoff.** Call `heyspex_record_wip({ spec_id: "<epic-id>", specs_filed, remaining, verified, notes })` for the epic you worked. It is the machine-readable hand-off the next session's `/hs-next` surfaces.
+5. **Flush the audit export.** Call `heyspex_export_events` (or `hs export-events`) so this session's claim and status events are written to the vault.
+6. **Capture knowledge worth keeping.** Propose memory candidates (lessons, decisions, references) per [[memory-protocol]]; the reviewer decides which to materialize.
+7. **Run housekeeping.** Run `heyspex_validate_linkage` and fix anything that is already yours to fix. Then say plainly, once, what is left that only the owner can act on.
+8. **Do not `git commit` and do not `git push`**, unless this vault has opted in to agent commits. Leave the working tree dirty; the reviewer's commit is the close action.
+
+If a spec was only partly completed, leave it `in_progress` and do not submit it. Status hand-off is for work the agent considers reviewer-ready.
+
+## The close-out write-up — every named item says fixed or not fixed
+
+The steps above decide what gets recorded. This section decides how the close-out message reads. The most important fact about any item is whether the thing works now, and that fact goes first on the line, in one of four words:
+
+| Word | Means |
+|---|---|
+| **Fixed** | The problem is gone. Verified, and the line names the check that proved it. |
+| **Partly fixed** | Some of it shipped. The line says which part did and which did not. |
+| **Not fixed** | Found and recorded. Nothing works differently than before. |
+| **Not started** | Named as work, not begun. |
+
+1. The word comes first on the line.
+2. Every named item carries one.
+3. Fixed and not-fixed items go in separate groups.
+4. "Filed", "flagged", "captured", "noted" and "handled" describe a record, never an outcome. They may follow one of the four words but never replace one.
+
+## Seat variant: per-COO close-out
+
+> **Read this when the session is an unattended seat started by a launcher**, not an interactive chat. A seat is an AI project manager (a COO seat) that the SpexCode launcher starts in its own window and closes again when the seat is finished. Nobody sits in the seat to say "that's all", so the close-out has to run by itself on every way a seat can end, and the launcher has to know when it is safe to close the window. The rest of this protocol still applies; this section says **which side owns each step** when there are two sides.
+
+**The rule in one line:** whoever is still running does the close-out. A seat that reaches its own end runs it. A seat that is killed, crashes or is stopped from outside cannot, so the launcher runs it for that seat. No step is ever done by both, and the launcher closes the window only after the seat's `close` event has landed.
+
+### Who owns each step
+
+"Seat" means the seat runs the step itself at the end of its run. "Launcher" means the launcher runs it. "Reviewer" means the later human review pass. "Not owed" means no one owes it on a seat run, with the reason.
+
+| # | Close-out step | Owner | How, on a seat run |
+|---|---|---|---|
+| 1 | Declare the thread type | Seat | A seat is always an execution thread. Its declaration is the `heyspex_preflight({ intent: "close_session" })` call it makes before submitting; that call also unlocks the seat's single-use submit confirm (see below). |
+| 2 | Report acceptance progress | Seat | `heyspex_report_progress` after each criterion, during the work. The close-out treats a held claim as complete only when every criterion was reported met. |
+| 3 | Record the WIP ledger | Seat | `heyspex_record_wip` on the epic the seat worked (on the milestone for a milestone seat's final close). When the owner must act, `remaining` carries a line `owner: <what the owner must do>`. |
+| 4 | Submit or release claims | Seat | `heyspex_submit_for_review` for each held claim whose criteria are all reported met; `heyspex_release_spec` for every other claim the seat still holds. A failed submit or release is recorded and never stops the remaining steps. The seat never writes `status:`. |
+| 5 | Write the summary | Seat | Done, left, needs owner, spend and time, written to the seat's window and carried in the `close` event. |
+| 6 | Emit `final`, then `close` | Seat | `close` is always the last line of the seat's event stream and is emitted exactly once. |
+| 7 | Keep the event audit file | Launcher | The launcher appends every event the seat streams, including `final` and `close`, to the run's audit file. The seat only emits. |
+| 8 | Flush the vault audit export | Not owed | A seat does not call `heyspex_export_events`. The export is safe to repeat, and the next interactive close-out (or a scheduled export) picks the seat's events up. |
+| 9 | Wait for `close`, or declare it missing | Launcher | After the seat exits, the launcher waits a set time (60 seconds by default) for its `close`. None in time is a defect (below). |
+| 10 | Done-check | Launcher | The launcher checks the epic's real status in the vault and stores the result with the close record. A seat's own "done" is never taken on its word. |
+| 11 | State update | Launcher | The launcher records the close (kind, who closed, summary, needs-owner text, time) and prints the needs-owner text in the run terminal. |
+| 12 | Close the window | Launcher | Only after the seat has exited and its close resolved, after a short grace so the exit summary stays readable. A missing close keeps the window open. |
+| 13 | Close-out for a dying seat | Launcher | Only when the seat cannot run steps 3 to 6 itself. See "Stopped from outside" below. |
+| 14 | Change-log row and review notes | Reviewer | The seat's summary and WIP entry are the breadcrumb; the reviewer's pass turns them into the review record. |
+| 15 | Capture knowledge worth keeping | Reviewer | The reviewer pass proposes and keeps memories. A seat does not create memory files during close-out. |
+| 16 | Housekeeping owner report | Seat | The owner report is the needs-owner line in the summary. Link validation is not owed by a seat; the next interactive close runs it. |
+| 17 | Commit or push | Not owed | Never, by either side. The dirty tree is the expected hand-off. |
+
+The seat's own steps run in a fixed order: record WIP, settle claims, write the summary, emit `final`, emit `close`. Each step is safe to repeat: running the close-out again skips what already succeeded and never sends a second `close`.
+
+### How a seat ends its run
+
+- **`heyspex_session_end`** means the work is done. The seat answers it itself and runs its close-out. In a milestone seat it ends only the current epic.
+- **`signal_owner_gated({ reason, kind })`** means everything left needs the owner (`kind: owner_gated`, the default) or nothing can be built because no build machine is available (`kind: fleet_unavailable`). The seat runs the same close-out.
+
+**Submit confirm.** An unattended seat has no human to approve a submit. The seat approves exactly one submit at a time for itself, and nothing else, only when it was started by the launcher in auto permission mode and its `close_session` preflight succeeded. Filing new specs stays gated.
+
+### Paths, one per way a seat can end
+
+| How the seat ended | Who runs the close-out | `close_kind` | `closed_by` | What the owner sees |
+|---|---|---|---|---|
+| Work done | Seat | `done` | `seat` | The summary; the window closes after the grace. |
+| Needs the owner | Seat | `owner_gated` | `seat` | The reason, in the run terminal and in the WIP ledger as `owner: …`. The epic is skipped, not counted as a failure. |
+| No build machine | Seat | `fleet_unavailable` | `seat` | Same close-out; reported as fleet-unavailable, not as a failure. |
+| Model stop or API error | Seat | `incomplete` or `error` | `seat` | Unsubmitted claims are released; the WIP ledger names what is left. |
+| The seat's own budget ran out | Seat | `budget` | `seat` | The run stops for that epic (an epic budget) or for the seat (the seat budget). |
+| Ctrl+C, stop, crash, stall, or a budget stop by the launcher | Launcher | `interrupted`, `crashed` or `budget` | `launcher` | See "Stopped from outside". |
+| Seat exited with no `close` in time | Launcher | `forced` | `launcher` | A defect; the window stays open. |
+
+**Needs-the-owner and no-build-machine run the same close-out as done.** The only differences are the close kind and the needs-owner text, which must name exactly what the owner has to do.
+
+**Stopped from outside.** The seat is gone, so the launcher runs the close-out for it:
+
+1. Release the claims held by that seat only, never another session's.
+2. Record an interrupted WIP entry on the epic naming the specs touched, the claims released, and why.
+3. Append a `close` with `closed_by: launcher` and the matching kind.
+4. If the seat already sent its own `close`, add nothing.
+5. If the vault service is unreachable, record the failed releases, say so, and still exit. A stop never hangs.
+
+**The missing close.** A seat that exits without a `close` in time is a defect, never a clean close. The launcher records the defect, closes the seat itself with `close_kind: forced`, and keeps the window open so someone can see what happened. A seat that streams no typed events owes no `close`; the launcher closes it at once.
+
+### Inside a milestone seat: a sub-close per epic, one close per seat
+
+One seat can run a whole milestone, epic by epic. Close-out then runs at two levels.
+
+- **Per-epic sub-close (seat).** When an epic ends, the seat records WIP on that epic, settles that epic's claims and writes its summary. It sends no `final` and no seat `close`; it marks the end of the epic with an `epic_end` event and moves on to the next epic with fresh instructions. The window stays open.
+- **Seat close (seat, once).** When the milestone is done or the seat must stop, the seat runs the full close-out once and sends one `close`.
+- **The launcher reacts only to the seat close.** An epic sub-close never closes the window.
+
+### The `close` event
+
+`close` follows `final` as the last line of the seat's stream. Fields:
+
+- `close_kind` (required): `done` | `owner_gated` | `fleet_unavailable` | `budget` | `interrupted` | `crashed` | `incomplete` | `error` | `forced`
+- `closed_by` (required): `seat` | `launcher`
+- `scope`: `seat` | `epic` (default `seat`)
+- `claims`: `{ submitted[], released[], failed[] }`
+- `wip_recorded`: true or false
+- `steps`: each close-out step with `ok`, `skipped` or `failed`
+- `summary_struct`: `{ done[], left[], needs_owner, spend_usd, elapsed_s }`
+
+### Order note: WIP before submit
+
+A seat records WIP before it submits, so the hand-off exists even if a submit fails. An interactive session may submit first and record WIP after. Both are fine; the seat keeps WIP first.
+
+## Reviewer responsibilities (human, separate pass)
+
+1. Read each review companion or change-log entry. Walk the acceptance criteria against the actual diff.
+2. Decide accept, edit or reject for every memory candidate. Materialize accepted ones as files under `specs/memory/<type>s/<slug>.md`, linked back to the parent spec.
+3. On **pass**: commit the diff, including any materialized memories and the status flip. The commit is the close action.
+4. On **reopen**: leave the spec `in_review`, document the gap, and the next agent session picks it up.