#+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.

* Refinement — notes.org-before-anchor on resume (work handoff, 2026-06-02 21:06)

A follow-up handoff from work, implemented the same evening. On a flush resume,
read notes.org key sections BEFORE the session-context anchor.

Motivating failure (work project, 2026-06-02): right after a flush resume, the
agent went to start a dashboard chore and concluded the dashboard repo wasn't
cloned — hunting =~/code= with shallow finds — when notes.org's code-locations
section documented the exact path. The resume had the anchor but not notes.org,
so it lacked the standing context and floundered. The anchor carries
session-specific state; notes.org carries the project's standing knowledge
(code-repo paths, conventions, key contacts) a resumed session needs to act
correctly.

Changes landed:
- =hooks/session-clear-resume.sh= — anchor-present branch now injects "read
  .ai/notes.org key sections (Project-Specific Context, Active Reminders,
  Pending Decisions; skip About This File), then the anchor." Runtime-guarded on
  notes.org presence: absent → resume from the anchor alone.
- =flush/SKILL.md= — Phase 2 (post-clear resume) documents the same read order
  so the skill text and the hook agree.

A small ordering/scope addition, not a redesign.