session-flow/handoff: routing-signals table, do-not-duplicate rule, worktree caveat, promote-content rule (aihero lane 1)

[kyle-sexton]

Context

Decided in aihero-course lane 1 (#2899, decision session 2026-08-17). The use-case boundary decision took the UNION of our session-chain uses (dumb-zone escape, session-ID chain, retrospective reconstruction) and the upstream crossing-boundaries taxonomy (other agent, other repo, colleague, forked side task), with the deliverable being explicit routing signals for which form to use when. Lanes decide but never implement; this item carries the wording changes.

Proposed work

• Add a compact routing-signals table to plugins/session-flow/skills/handoff/SKILL.md mapping situation to form: deep-window escape with chain value -> full file (default); small follow-ups, no chain value -> prompt-only (with the documented retro-gap cost); next session's focus differs -> either form plus purpose argument (session-flow/handoff: adopt purpose argument across the save-point engine (aihero lane 1) #2955); AFK but work continues -> route to continue-in-background; machine may die -> route to clean-stop semantics; crossing a boundary (colleague, other repo, other agent) -> full file plus purpose plus origin line. Name the session-chain/retrospective use as a first-class owned use case in "When to invoke".
• Adopt the explicit do-not-duplicate rule in the skill body, mirroring upstream's wording: reference content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs) by path or URL instead of restating it. Ours partially covers this ("Summarize; never transcribe"); make it a general stated rule.
• Add the worktree caveat to save-point.md's destination section, cross-referenced from worktree tooling: a handoff written inside a worktree checkout lives in that worktree's memory root and dies with git worktree remove; acceptable only when the worktree completes as a merged PR unit; when pausing un-merged worktree work, write from the main checkout or rely on clean-stop's preserve-before-remove step.
• State the promote-content-never-file rule: when a handoff carries durable value, its substance is promoted into a committed artifact (topic contract, issue, PR body); the handoff file itself stays ephemeral and is never committed. Cleanup of <memory_dir>/handoffs/ remains user-controlled removal, never silent expiry (confirms the session-flow/handoff: hardening audit vs mattpocock/skills handoff issue corpus (#186/#306/#617/#482) #1477 finding-4 rejection).

Acceptance criteria

• Routing table present in SKILL.md; session-chain use named first-class
• Do-not-duplicate rule stated explicitly in the skill body
• Worktree caveat in save-point.md destination section
• Promote-content-never-file rule stated; no expiry behavior added anywhere
• find-handoff detection contract untouched

References

• session-flow/handoff: aihero course lane 1: use-case boundaries, purpose argument, expiry #2899 (lane decision record) and docs/upstream/aihero-course.md lane 1 rows
• session-flow/handoff: hardening audit vs mattpocock/skills handoff issue corpus (#186/#306/#617/#482) #1477 / PR feat(session-flow): adopt claim-provenance and constraint re-scan rules from handoff audit #1560 (prior hardening audit; cleanup sub-item rejection this confirms)
• session-flow/handoff: adopt purpose argument across the save-point engine (aihero lane 1) #2955 (purpose argument, sibling item)

Metadata

Field	Value
Category	unspecified
Area	session-flow
Ecosystem	unspecified