session-flow/handoff: aihero course lane 1: use-case boundaries, purpose argument, expiry

[kyle-sexton]

Context

First of six vetting lanes for the AI Hero course lessons (Matt Pocock) against this marketplace's plugins; contract locked via /planning:interview in docs/topics/pocock-course-lanes/PLAN.md (branch claude/plan-mode-discussion-55kszx). His handoff is a 15-line skill writing to the OS temp dir; ours is the save-point engine with a STOP gate, 13-section structure, claim provenance, and chain continuity. Cost of skipping: his lesson's claims and our real usage stay unreconciled, and two known candidates go undecided.

Proposed work

• Run the lane interview-first (/planning:interview me), grounded by a fresh /discovery:explore of plugins/session-flow (handoff skill + save-point engine + structure doc)
• Evaluate the use-case boundary: our dominant real use is a hard session-chain handoff (dumb-zone escape, session-ID chain, whole-picture reconstruction for retrospectives; functionally a compact-replacement that regathers) vs his crossing-boundaries taxonomy (other agent, other repo, colleague, forked side task). Decide which use cases our handoff officially owns, which route elsewhere, and whether the session-chain/retrospective use deserves first-class support
• Decide the purpose-argument adoption candidate: his single argument tailors the doc to the next session's focus; ours parses only [file|prompt] [topic]
• Decide handoff-file expiry/accumulation policy: his OS-temp placement self-cleans; nothing expires our /handoffs/ files
• Decide the ephemerality philosophy row (OS temp vs memory tier) for the provenance doc

Acceptance criteria

• Adopt / reject-with-reason / track-on-event rows recorded in docs/upstream/aihero-course.md for every handoff-lesson claim
• Work items filed for each decided plugin change (changes execute outside this lane)
• Lane summary written to the lane's topic slice
• The use-case boundary decision names which uses session-flow:handoff owns and which route elsewhere

References

• docs/topics/pocock-course-lanes/PLAN.md (contract + lane definition)
• docs/upstream/mattpocock-skills.md (SSOT; handoff row) and docs/upstream/mattpocock-skills-v12-map.md
• session-flow/handoff: hardening audit vs mattpocock/skills handoff issue corpus (#186/#306/#617/#482) #1477 (prior hardening audit vs his handoff failure corpus)
• Upstream skill: mattpocock/skills skills/productivity/handoff/SKILL.md

Metadata

Field	Value
Category	unspecified
Area	session-flow
Ecosystem	unspecified

[kyle-sexton]

Pre-decided inputs from the user (2026-08-17, meta session f273fedd-1df5-5464-bb25-fc86c3dc6050) — the lane session should treat these as settled decisions, not open questions, and fold them into its register:

1. Use-case boundary: take the UNION, and ship routing signals. Our use cases (hard session-chain handoff: dumb-zone escape, session-ID chain, retrospective reconstruction) PLUS his (cross-agent, cross-repo, colleague, forked side task) are all in scope, including his purpose/prompt argument (natural-language "what the next session is for"). The deliverable is not just the merged list: it is clear signals for which form to use when (full file vs prompt-only vs purpose-tailored), so the skill is "best of both worlds" with explicit guidance. The purpose-argument design feeds this directly.

2. Placement/lifecycle (user overrode the standing recommendation). Keep .work/handoffs/ (project-local, gitignored, agent-readable; NOT OS temp, so temp-cleaner volatility does not apply — that is his skill's placement, not ours). Handoffs remain primarily ephemeral. The lane must settle: (a) a worktree caveat — a handoff written inside a worktree checkout dies if the worktree is blown away before the work merges (acceptable only when the worktree completed as a PR unit); (b) whether anything ever needs uplifting into source control — default answer is no (durable state belongs in committed contracts/issues), but define the explicit promote-on-value rule if an exception exists; (c) cleanup is user-controlled removal, never silent expiry or accidental OS cleanup — "something safe that's persistent that we have control over when it gets removed."

3. Adopt his explicit do-not-duplicate rule. Reference content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs) by path or URL instead of restating it — stated explicitly in the skill body, mirroring upstream's wording. Rationale: explicit over implicit.

Caveat for the lane session: the user issued a blanket "accept all recommendations" against a question round this meta session did not produce (their Q10-Q14 numbering). If that round came from YOUR register, close it against this comment plus their original words; do not silently auto-accept anything this comment does not cover.

---

Generated by Claude Code

[kyle-sexton]

Audit amendment A2 (user-approved 2026-08-17, recorded in docs/topics/pocock-course-lanes/PLAN.md at 1d54cd46): this lane also creates the docs/upstream/aihero-course.md skeleton — row schema and recheck-trigger form fixed at creation, inherited from docs/conventions/upstream-drift/README.md's four-part record and the SSOT attribution-table shape, with triggers phrased as divergence-at-re-fetch (never bare "when the lesson updates"). This lane's decision rows land directly in that doc; lane 6 (#2904) keeps the coverage index, term adoption, and final consolidation. This resolves the contradiction where this issue's acceptance criteria wrote rows into a doc #2904 was scoped to create.

Also relevant here: the claim-ladder's bucket-ii baseline was corrected (amendment A1) — context-guard's shipped band thresholds are declared judgment defaults with named provenance, NOT measurements; only zone readings are measured. Any empirical-claim grading in this lane cites the corrected wording.

---

Generated by Claude Code

[kyle-sexton]

Lane 1 closed (2026-08-17, commit ffb01459 on claude/plan-mode-discussion-55kszx). All four acceptance boxes ticked.

Deliverables

• docs/upstream/aihero-course.md created (skeleton per audit amendment A2: four-part row schema, divergence-at-re-fetch trigger form fixed at creation) with nine lane-1 decision rows; cross-linked from the mattpocock-skills SSOT.
• Lane summary at docs/topics/pocock-lane-1/SUMMARY.md.
• Work items filed: session-flow/handoff: adopt purpose argument across the save-point engine (aihero lane 1) #2955 (purpose argument, behavior change), session-flow/handoff: routing-signals table, do-not-duplicate rule, worktree caveat, promote-content rule (aihero lane 1) #2956 (routing-signals table, do-not-duplicate rule, worktree caveat, promote-content-never-file rule), context-guard: zone capture is statusline-teed and silent in cloud/headless sessions #2957 (context-guard zone capture is statusline-teed and silent in cloud/headless sessions).

Decision headlines (full rows in the provenance doc)

• Use-case boundary: UNION per the pre-decided input; session-chain/retro use named first-class; routing signals designed as a SKILL.md table (which form when).
• Purpose argument: ADOPT as optional trailing free text [file|prompt] [topic] [purpose...]; emphasis-only tailoring; detection contract and Original-goal immutability untouched.
• OS-temp placement and silent expiry: REJECT; accumulation by design with user-controlled removal, confirming (not reversing) the session-flow/handoff: hardening audit vs mattpocock/skills handoff issue corpus (#186/#306/#617/#482) #1477 finding-4 verdict, whose recorded rationale was fetched verbatim before deciding.
• disable-model-invocation: true: REJECT; model-invocable with trigger discipline kept (user confirmed in-lane; the cloud signal gap it exposed is context-guard: zone capture is statusline-teed and silent in cloud/headless sessions #2957).
• 15-line minimalism: REJECT with the incident-derived-engine evidence; prompt-only mode is our minimal tier. Suggested-skills and redaction: COVERED.

Parked: the non-interactive orchestrator continuation pattern to lane 2 (#2900); zone-signal availability in cloud to lane 3 (#2901) via #2957.

Next per the contract: handoff to lane 2 (/session-flow:handoff, topic pocock-lane-2), then #2900 in fresh context. No PR until all six lanes close.

---

Generated by Claude Code