docs(flush): preserve flush promotion handoff bundle as provenance

1 files changed, 209 insertions, 0 deletions

diff --git a/docs/design/2026-06-02-flush-promotion.org b/docs/design/2026-06-02-flush-promotion.org
new file mode 100644
index 0000000..d34ad89
--- /dev/null
+++ b/docs/design/2026-06-02-flush-promotion.org
@@ -0,0 +1,209 @@
+#+TITLE: Flush Promotion — Handoff Bundle (from work)
+#+AUTHOR: Craig Jennings & Claude
+#+DATE: 2026-06-02
+
+* Provenance
+
+This is the preserved handoff bundle that produced the =/flush= skill and the
+=SessionStart(clear)= resume hook. It arrived from the work project's inbox on
+2026-06-02 (validated there the same day), and was implemented in rulesets in
+commit =526df6d= (=feat(flush): add /flush skill and SessionStart(clear) resume
+hook=).
+
+Kept as design provenance — the rationale for why =/flush= exists, the decision
+to package it as a skill rather than a project-workflow doc, and the original
+=flush.org= workflow doc the skill was built from. The third bundle artifact,
+=session-clear-resume.sh=, lives on as the canonical hook at
+=hooks/session-clear-resume.sh=.
+
+What landed vs. the promotion steps below:
+- Step 1 (=/flush= skill) — done: =flush/SKILL.md=.
+- Step 2 (hook canonicalization) — done: =hooks/session-clear-resume.sh= +
+  =~/.claude/hooks/= symlink.
+- Step 3 (settings commit) — done: =.claude/settings.json= SessionStart entry,
+  plus =hooks/settings-snippet.json= updated so a fresh machine wires it on
+  =make install-hooks=.
+- Step 4 (workflow-doc template) — skipped: the skill supersedes the
+  project-workflow doc, so both halves are global with no per-project sync.
+- Step 5 (notes AVAILABLE WORKFLOWS entry) — n/a: rulesets has no such template
+  section to mirror into.
+
+* Promotion Handoff Note (work → rulesets)
+
+Promote the flush workflow + SessionStart(clear) hook into rulesets templates.
+
+VALIDATED in the work project on 2026-06-02: built the flush workflow + a
+SessionStart matcher=clear hook, then live-tested it — refreshed the
+session-context anchor in place, /clear, and the fresh session read the anchor
+and resumed the same logical session (replied 'flushed.', restated Active Goal +
+Next Step, kept working) without re-running startup. The loop works end to end.
+
+WHAT FLUSH IS: a mid-session context flush — the checkpoint half of the
+wrap/restart-rhythm. Refresh the session-context anchor in place, /clear, resume
+from the anchor. Cheaper tokens + sharper context without fragmenting the
+session into archive files. Distinct from wrap-it-up (archives to .ai/sessions/
++ commits) and startup (genuine fresh start). One logical session spans the
+/clear boundaries.
+
+TWO ARTIFACTS:
+1. flush.org — the workflow doc (pre-clear checkpoint half; post-clear half is
+   driven by the hook). Preserved below.
+2. session-clear-resume.sh — the SessionStart(clear) hook. General by design:
+   anchor present -> resume + say 'flushed.'; anchor absent -> run startup
+   (covers a stray /clear). Reaches the model only via
+   hookSpecificOutput.additionalContext. Resolves the AI_AGENT_ID-aware anchor
+   path, falling back to the singleton .ai/session-context.org. Now canonical at
+   hooks/session-clear-resume.sh.
+
+DECISION (2026-06-02, updated): package the pre-clear half as a /flush SKILL
+(~/code/rulesets/flush/SKILL.md), not just a project workflow doc. Rationale: the
+post-clear hook is already global, so making the pre-clear half a skill makes
+BOTH halves global — /flush is callable by name from any project with no
+per-project workflow-doc sync. Match the existing skill shape under
+~/code/rulesets/<name>/SKILL.md (see voice/, debug/, add-tests/). The flush.org
+doc filed here becomes the skill's reference body / the basis for SKILL.md; keep
+a project-workflow template too only if it adds value beyond the skill.
+
+AGENT-INVOCABLE + AGENT-INITIATED: the skill must be callable by the agent
+itself, and the agent — not only the user — should decide when it's time to
+flush (clean task boundary + large enough context, per the wrap/restart-rhythm).
+HARD CONSTRAINT: /clear is user-only; the agent CANNOT execute /clear. So
+"agent-initiated" means the agent runs the pre-clear checkpoint (refresh anchor +
+verify-gate) on its own judgment, then PROMPTS the user "checkpoint saved, type
+/clear to reset" — the agent proposes and does all the work; the user supplies
+the single /clear keystroke. Do NOT design anything that assumes the agent can
+self-trigger /clear.
+
+PROMOTION STEPS (do these in a rulesets session):
+1. /flush SKILL — author ~/code/rulesets/flush/SKILL.md per the DECISION +
+   AGENT-INITIATED notes above, built from flush.org. Pre-clear checkpoint (dump
+   live state -> refresh * Summary in place -> append dated flush marker to
+   * Session Log -> verify the write landed (gate) -> prompt the user to /clear).
+   Agent-callable; agent may initiate at a clean boundary.
+2. HOOK CANONICALIZATION — the hook at ~/.claude/hooks/session-clear-resume.sh
+   is currently a REAL file, not rulesets-canonical. Move it to
+   ~/code/rulesets/hooks/ and symlink ~/.claude/hooks/session-clear-resume.sh ->
+   it, matching the existing pattern (precompact-priorities.sh etc.). Otherwise
+   the settings.json reference breaks on a fresh rulesets clone.
+3. SETTINGS COMMIT — ~/code/rulesets/.claude/settings.json already has the
+   SessionStart matcher=clear -> session-clear-resume.sh entry added
+   (uncommitted, valid JSON; ~/.claude/settings.json is a symlink to it). Review
+   + commit it.
+4. WORKFLOW TEMPLATE (optional) — if a project-workflow template still adds value
+   alongside the skill, promote flush.org into the rulesets project-workflow
+   templates and adjust intra-doc links (wrap-it-up.org, startup.org) to
+   template-relative paths. Otherwise the skill supersedes it.
+5. NOTES ENTRY TEMPLATE — the work project's notes.org AVAILABLE WORKFLOWS got a
+   flush entry; mirror that into whatever template seeds AVAILABLE WORKFLOWS if
+   one exists.
+
+Source: work project session 2026-06-02 (evening). Anchor:
+work/.ai/session-context.org.
+
+* Original flush.org Workflow Doc
+
+The pre-clear checkpoint workflow as it existed in the work project, preserved as
+the basis the =/flush= skill was built from.
+
+** Summary
+
+Mid-session context flush. Refresh the session-context anchor in place, then
+=/clear=, then resume the same logical session from the anchor — cheaper tokens
+and a sharper context window without fragmenting the session into many archive
+files.
+
+Distinct from wrap-it-up (which archives to =.ai/sessions/= and commits) and from
+startup (which pulls rulesets + project, syncs templates, surfaces inbox +
+reminders for a genuine fresh start). Flush does none of that — it keeps one
+session alive across a =/clear= boundary.
+
+** When to use
+
+- Triggered by: "flush", "flush it", "let's flush", "flush the context".
+- The current task has a clean boundary and the context window is large enough
+  that a reset would sharpen the work (the wrap/restart rhythm).
+- You want to stay in the same logical session — same goal, same anchor file —
+  not start a new day or hand off.
+
+Do NOT use for:
+- End of day / done for now → wrap-it-up (archives + commits).
+- Fresh start on another machine, or after being away → startup.
+
+** How it works (two halves around /clear)
+
+=/clear= wipes the conversation, so the workflow can't run straight through it.
+It splits at the clear:
+
+- Pre-clear (this agent): refresh the anchor + verify it landed, then hand the
+  =/clear= to the user. Claude cannot run =/clear= itself — it is a user-only
+  command.
+- Post-clear (the SessionStart(clear) hook, =~/.claude/hooks/session-clear-resume.sh=):
+  the cleared session has no memory of the flush, so the hook injects "read the
+  anchor and resume" into the fresh context. After =/clear= the model loads that
+  instruction but waits for the user's next message before acting — one keystroke
+  is expected, not a bug.
+
+** Execution
+
+*** Phase 1 — Pre-clear checkpoint (this agent)
+
+1. Dump everything not yet on disk. Before touching the anchor, make sure the
+   live working state is captured: decisions reached this turn, =file:line=
+   targets, the exact next action, any finding that would be expensive to
+   reconstruct. The whole point is that nothing is lost across the clear.
+
+2. Resolve the anchor path.
+   #+begin_src bash
+   sc=$(.ai/scripts/session-context-path 2>/dev/null || echo .ai/session-context.org)
+   #+end_src
+   Create it with the skeletal structure (=#+TITLE=, =* Summary= with empty
+   subsections, =* Session Log=) if it doesn't exist yet.
+
+3. Refresh the =* Summary= in place. Write/overwrite the subsections so the
+   anchor reflects current state:
+   - Active Goal — the overall goal of the session (one or two sentences).
+   - Decisions — what's been settled so far.
+   - Data Collected / Findings — load-bearing facts, with exact identifiers.
+   - Files Modified — what changed on disk this session.
+   - Next Steps — the immediate next action, specific enough to resume blind.
+   Do NOT archive and do NOT start a new file — refresh the existing one.
+
+4. Append a flush marker to the =* Session Log=.
+   #+begin_src bash
+   date "+%Y-%m-%d %a @ %H:%M:%S %z"
+   #+end_src
+   Add =** <timestamp> — flushed= with a one-line note on what's in flight, so
+   the log stays a continuous narrative across clears.
+
+5. Verify the write landed — gate before clearing. Re-read the anchor and
+   confirm the Active Goal and Next Steps are present and current. If the write
+   didn't land, STOP and fix it — do not tell the user to =/clear=. There is no
+   recovering the conversation after =/clear=.
+
+6. Hand off the clear. Tell the user: the checkpoint is saved (name the anchor
+   path), type =/clear= now, then send any message to resume.
+
+*** Phase 2 — Post-clear resume (SessionStart(clear) hook + fresh agent)
+
+Driven by the hook, not this file — but documented here so the loop is legible:
+
+1. The user types =/clear=. =~/.claude/hooks/session-clear-resume.sh= fires and
+   injects "read the anchor, say 'flushed.', resume" into the fresh context.
+2. The user sends any message (e.g. "go", "resume").
+3. The fresh agent reads the anchor, replies =flushed.= on its own line, restates
+   the Active Goal + immediate Next Step, and continues. It does NOT run startup
+   or re-sync anything — this is a resume, not a fresh start.
+
+If the anchor is absent (a stray =/clear= with no prior flush), the hook instead
+points the fresh session at startup.
+
+** Notes
+
+- The anchor persists across as many flushes as a day needs. Only wrap-it-up
+  archives it to =.ai/sessions/= and commits — that's the single end-of-session
+  boundary.
+- The hook is global (=~/.claude/settings.json= → SessionStart matcher =clear=),
+  so it works in any project that has a session-context anchor.
+- Promotion: this workflow + the hook are candidates for the rulesets templates
+  (the wrap/restart-rhythm task predicted this). Validate here, then file to the
+  rulesets inbox.