heyspex 0.1.0 → 0.2.0

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

@@ -0,0 +1,91 @@
+---
+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.