feat(session-flow): handoff routing signals, artifact rules, worktree caveat

[kyle-sexton]

Closes #2956

Summary

Implements the AI Hero course lane 1 wording changes for session-flow:handoff: a routing-signals table mapping situation to save-point form, the session-chain/retrospective use named first-class in "When to invoke", the general do-not-duplicate rule, the promote-content-never-file rule, and the worktree caveat in the engine doc's destination section. find-handoff's detection contract is untouched.

Fix

• skills/handoff/SKILL.md — "When to invoke": names the session-chain use first-class (the escape-and-resume cadence whose handoff files carry the session_id/previous_handoff chain /session-flow:retro walks for retrospective reconstruction) alongside the upstream boundary-crossing taxonomy (colleague, other repo or checkout, other agent, forked mid-phase side task) — the UNION the lane decided. A new "Routing signals — which form to use when" table maps: deep-window escape with chain value → full file (default); small follow-ups, no chain value → prompt-only with its documented retro-gap cost; differing next-session focus → either form plus the purpose argument; AFK-but-work-continues → the sibling continue-in-background skill (explicit user request only); machine may go away → clean-stop semantics; boundary crossing → full file plus purpose plus the Handoff origin: line. The table's AFK row absorbs the former standalone "Going AFK" paragraph (same content, one home).
• skills/handoff/SKILL.md — new "Reference other artifacts; promote durable value" section: states the do-not-duplicate rule mirroring upstream (content captured in specs, plans, ADRs, issues, commits, or diffs is referenced by path or URL, never restated — the existing "Summarize; never transcribe" per-section guidance stated as a general rule) and the promote-content-never-file rule (durable value is promoted into a committed artifact — topic contract, issue, PR body — while the handoff file stays ephemeral and uncommitted; cleanup of handoffs/ remains user-controlled removal, never silent expiry — no expiry behavior added anywhere, confirming the session-flow/handoff: hardening audit vs mattpocock/skills handoff issue corpus (#186/#306/#617/#482) #1477 finding-4 rejection).
• reference/save-point.md — "Where save-points live": adds the worktree caveat — a save-point written inside a git worktree checkout resolves its memory root within that worktree 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 /session-flow:clean-stop's preserve-before-remove step (which already inspects ignored content before removal and names "generated handoff data" explicitly — the existing cross-reference from worktree-touching tooling).
• Versioning: session-flow 0.25.0 → 0.26.0 with the matching CHANGELOG entry.

Verification

• bash scripts/validate-plugins.sh — all manifests and the catalog validated.
• npx markdownlint-cli2 on the four touched markdown files — 0 issues.
• bash scripts/check-changelog-parity.sh --check, --check-bump origin/main, --check-order — all pass (83 changelogs, newest-first, bump matched by entry).
• bash scripts/check-changed-skills.sh origin/main — PASS, 0 errors (one soft-target warning: SKILL.md 230/500 lines against the 200-line soft target; the local mawk REcompile panics are the known skill-quality: check-skill.sh fresh-eyes scanner breaks under mawk — ERE interval expressions unsupported #3005 artifact, non-failing).
• Acceptance criteria walked: routing table present with session-chain use first-class; do-not-duplicate rule stated; worktree caveat in the destination section; promote rule stated with no expiry behavior; skills/find-handoff/ and the detection-contract section of save-point.md's resume-prompt shape untouched by the diff.

Related

Refs #2899 (lane 1 decision record), docs/upstream/aihero-course.md lane 1 rows. Refs #1477 / PR #1560 (cleanup sub-item rejection this confirms). Refs #2955 / PR #3017 (purpose argument, sibling item the routing table's purpose rows build on). Refs #3005 (mawk artifact noted in Verification).

🤖 Generated with Claude Code

https://claude.ai/code/session_01QbfCrj3X9FfGL7VRZYmrn4

---

Generated by Claude Code

[claude]

Claude finished @kyle-sexton's task in 1m 47s —— View job

---

Claude finished the code review

• Load /review:code-review skill instructions
• Gather context (REVIEW.md, CLAUDE.md/AGENTS.md, diff)
• Review changed files against criteria
• Post findings

Summary

This is a docs-only PR (SKILL.md, reference doc, CHANGELOG, plugin manifest version) with no code paths, so the code-review lane's "always check" items (audit-log completeness, atomicity across multi-record writes) don't apply here — there's no state-mutating logic in the diff.

I read the full diff against origin/main plus the surrounding files for consistency:

• Routing-signals table (skills/handoff/SKILL.md#L101-110) — cross-checked against the removed "Going AFK" paragraph; content is fully absorbed with no loss, and all skill names it references (/session-flow:retro, /session-flow:continue-in-background, /session-flow:clean-stop) exist in the plugin.
• Worktree caveat (reference/save-point.md#L20-27) — the claim about clean-stop's preserve-before-remove behavior (git status --ignored, "generated handoff data" named explicitly) matches skills/clean-stop/SKILL.md lines 78-82 verbatim in substance — not a fabricated cross-reference.
• New "Reference other artifacts" section (skills/handoff/SKILL.md#L128-139) — consistent with the existing "Does not commit" bullet under "What this skill does NOT do"; no contradiction.
• Versioning — plugin.json version (0.26.0) matches the new CHANGELOG.md ## [0.26.0] entry heading.
• Long table rows (skills/handoff/SKILL.md#L106-110) initially looked like they might trip a line-length lint, but .markdownlint-cli2.jsonc explicitly disables MD013 — not a real issue.
• Confirmed skills/find-handoff/ and the detection-contract section of save-point.md are untouched by the diff, matching the PR description's claim.

No correctness, maintainability, or convention issues found. Nothing to flag inline.

Branch: claude/pocock-steering-course-00zkvd

[claude]

Claude finished @kyle-sexton's task in 39s —— View job

---

Security review — skipped (no security-relevant surface)

• Gather context (PR diff, changed files)
• Apply skip gate check
• Review changed files for security-relevant surface
• Post final findings

Per /review:security-review's skip gate, this review stops early: the diff has no security-relevant surface.

All four changed files are documentation/metadata only:

• plugins/session-flow/.claude-plugin/plugin.json — version bump 0.25.0 → 0.26.0 and description string update.
• plugins/session-flow/CHANGELOG.md — changelog entry (prose only).
• plugins/session-flow/reference/save-point.md — adds a "Worktree caveat" paragraph to the doc's "Where save-points live" section.
• plugins/session-flow/skills/handoff/SKILL.md — adds routing-signals guidance table and a "Reference other artifacts" section to the skill's markdown body.

No code, no GitHub Actions workflow files, no scripts, no auth/authz logic, no injection surfaces (command, SQL, path, template), no secret/token/credential handling, and no permission or dependency-pin changes are touched by this PR. There is no exploitable path here for this lane to report.

No findings.

[github-actions]

Last security-reviewed head: 173973dd39f090495a7e91b8ce08ffb7c3d34a9d. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

[github-actions]

Claude has reviewed this PR 2 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 76432a4f64

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 1m 31s —— View job

---

Claude finished the code review

• Load /review:code-review skill instructions
• Gather context (REVIEW.md, CLAUDE.md, diff origin/main...HEAD)
• Review changed files against criteria, including the two Codex findings from the prior commit
• Post findings

Summary

This PR is docs/metadata-only (SKILL.md, a reference doc, CHANGELOG.md, plugin.json), so REVIEW.md's "always check" items (audit-log completeness, atomicity across multi-record writes) don't apply — there's no state-mutating logic in the diff.

The latest commit (173973d, "fix(session-flow): qualify boundary-crossing route and do-not-duplicate rule") is a direct fix for the two findings Codex posted against the prior commit. I checked both:

• P1 — transfer mechanism for cross-checkout routing (skills/handoff/SKILL.md#L110): the routing-table row now states the handoff file is memory-tier and gitignored, visible only in the writing checkout, and that it "must travel out-of-band (send the file with the prompt, or promote its substance into an artifact the other side can read, per the promote rule below)" when the other side can't read that checkout. This matches the visibility contract in docs/conventions/topic-docs/README.md lines 195–199 (memory-tier rows: invisible outside the writing checkout) and closes the gap the finding raised — resolved.
• P2 — uncommitted-edit exception (skills/handoff/SKILL.md#L134-137): the do-not-duplicate rule now carries the exact exception reference/structure.md lines 222–226 requires — "Uncommitted or half-finished edits remain the exception that same file-roles section owns: they have no commit to reference, so their state — which part is implemented and working, which part is not — is described in the save-point" — restoring the required behavior the general rule had put at risk. Resolved.

No new issues introduced by the fix commit. I re-verified the rest of the diff against origin/main for consistency:

• plugin.json version (0.26.0) still matches the CHANGELOG.md ## [0.26.0] heading; diffstat (4 files, +71/-3) matches the PR description.
• Worktree caveat (reference/save-point.md) and its cross-reference to clean-stop's preserve-before-remove step are unchanged since the last review pass and remain accurate.
• skills/find-handoff/ and save-point.md's detection-contract section remain untouched by the diff, as claimed.

No further findings — nothing blocking, nothing to flag inline.

[claude]

Claude finished @kyle-sexton's task in 52s —— View job

---

Security review — skipped (no security-relevant surface)

• Load /review:security-review skill instructions
• Gather context (diff vs origin/main, changed files)
• Apply skip gate check
• Review changed files for security-relevant surface
• Post final findings

Per /review:security-review's skip gate, this review stops early: the diff has no security-relevant surface.

All four changed files are documentation/metadata only (full diff):

• plugins/session-flow/.claude-plugin/plugin.json — version bump 0.25.0 → 0.26.0 only.
• plugins/session-flow/CHANGELOG.md — changelog prose only.
• plugins/session-flow/reference/save-point.md — adds a "Worktree caveat" paragraph.
• plugins/session-flow/skills/handoff/SKILL.md — adds a routing-signals table and a "Reference other artifacts" section, and (in the latest commit 173973d) qualifies the boundary-crossing route with an out-of-band transfer note and preserves the uncommitted-edit exception in the do-not-duplicate rule.

No code, no GitHub Actions workflow files, no scripts, no auth/authz logic, no injection surfaces (command, SQL, path, template), no secret/token/credential handling, and no permission or dependency-pin changes are touched by this PR. There is no exploitable path here for this lane to report.

The two open review-comment threads on this PR (from chatgpt-codex-connector, about the boundary-crossing transfer mechanism and the uncommitted-edit exception) are documentation-clarity concerns, not security findings — the latest commit 173973d already addresses both by qualifying the corresponding routing-table row and do-not-duplicate rule. Not in scope for this security lane either way.

No findings.