Make the Session Handoff a Chained Issue With a handoff Label, a Hub Script, and a Skill #1470

Design and requirements only. Four surfaces: a fleet label, a hub script, a skill, and a change to a carried rule in AGENTS.md. Relates #1469, #1434, #1433, #1439.

Why

Handoff between sessions runs through a file today, HANDOFF.md and dated siblings beside it. Three failures recur. The file is not found where the next session looks for it. More than one candidate file is found and nothing says which one is current. And there is no history at all, so a later round re-runs a path an earlier round already tried and already wrote down. The value of a handoff is precisely the record of what has already been attempted, and a single overwritten file on one machine is the one shape that cannot hold it.

#1469 moved the handoff to an issue by hand, under direct instruction, and the shape works. It is discoverable from any machine, its history is permanent, and the chain is walkable. What it lacks is a mechanism. The title format, the forward link, the close, the section order, and the discovery query all live in that one issue body and in whichever session happens to have read it, which is the same fragility the file had, moved.

The purpose is to cut the context a session carries without losing what that session learned, and to let a large body of work break into rounds without every round being planned ahead.

What a Handoff Is, and Is Not

• It is session state and pointers, not the durable record. A defect becomes an issue, a rule becomes documented rule text, a lesson becomes governance prose. The handoff points at those and does not restate them, per GOVERNANCE.md "Durable Knowledge and Self-Improvement". Session Handoff, 2026-09-09: #1321 Test 3 Proved, and the Handoff Moves to Issues #1469's own account of what restating a filed decision cost is the worked example.
• It records work to do next, and it is not itself backlog work. It carries no triage label, and every backlog enumeration excludes it.
• It is not a place to ask a question. A question waiting on the maintainer is an issue carrying decision, and GOVERNANCE.md "Communicating with the User" requires the handoff to account for that queue and present it, not to hold it.

Scope

1. A handoff label

Declare one entry in repo-config/labels.json beside the existing sixteen, with a description at most 100 characters and no tab or newline, which is what labels_payload_ok in repo-config/configure.sh enforces. Apply it with repo-config/configure.sh apply, naming the target repository and its workflow model, run from a hub checkout.

Record in repo-config/README.md "Labels" that handoff is a surface marker like agents and skills, never a triage label, and that a handoff issue carries no triage label at all because it records no work of its own. Without that sentence the next reader of the taxonomy reads an unlabelled handoff issue as drift.

The label makes the chain findable by label instead of by title search, which is what lets the title carry a human subject without a parser depending on it.

This inherits #1434's rollout gap. The decision label exists on the hub and on none of the carriers, so a downstream session enumerates an empty queue and reports it healthy. A handoff label declared and not applied fails the same way, silently. The script must therefore refuse rather than degrade when the label is missing from the target repository, naming the configure.sh apply command that fixes it.

2. The chain model

• One open handoff issue per track per repository. A track is a short kebab-case slug naming a lane of work. A session that names no track uses default. Parallel lanes each name their own, so each closes its own predecessor and neither reads the other's state as current.

• The title is for humans: Session Handoff [<track>]: <subject>. Nothing parses it.

• The chain is machine-readable from a metadata block in the body, so a retitled or edited issue still chains. One HTML comment, rendered invisible, as the body's last line:

  <!-- handoff: v1 track=<slug> round=<n> previous=<issue number or none> -->
  

• Closing the loop, in this order: create the new issue, comment the forward link on the previous one, then close the previous one. Creating first means a failure at any later step leaves a discoverable new issue rather than a closed chain with no successor.

• The invariant a reader checks: exactly one open issue carrying handoff for a given track in a given repository. Zero means this is the first handoff on that track. Two or more is a defect to report, never one to resolve by picking.

• The handoff issue lives in the repository the work was in. A session that spanned repositories writes the handoff where its branch and its pull requests are, and names the other repositories in the state section.

3. scripts/handoff.py

Hub-hosted, per GOVERNANCE.md "Hub-Hosted Tooling", so it is reached from a hub checkout rather than carried. Python, standard library only, matching the other hub scripts.

Every subcommand takes a required --repo naming the target repository, with no default, for the same reason pr_review.py requires one: a number alone resolves in every repository, and a digest of the wrong one is well formed.

• current [--track T] prints the open handoff issue for that track, number and URL.
• resume [--track T] [--history N] prints the current handoff body followed by a one-line index of the last N closed links in the chain, which is the read side of the repeated-work problem.
• chain [--track T] [--limit N] [--grep PATTERN] walks backwards through previous= and lists number, title, date, and state. --grep searches the bodies, which is how a session answers "has this already been tried" without reading every round.
• new [--track T] --title <subject> --body-file <path> performs the three-step chain and prints each step's result.
• link --new <n> --previous <n> finishes a chain that half-applied, so a failed run is recoverable without a second issue.
• tracks lists every open handoff with its track and age, so an abandoned lane is visible rather than silently current.
• adopt <issue> --track T puts the label and the metadata block on an existing hand-written handoff. Session Handoff, 2026-09-09: #1321 Test 3 Proved, and the Handoff Moves to Issues #1469 needs this: it predates both, and it is the chain's first link.

Behaviour that is not optional:

• Every identifier a write consumes is captured from a read in the same run. No constructed issue numbers, no reuse from a previous run.
• No output of a write is suppressed and no failure is converted into success. Each of the three steps reports its own result. A step that appears to fail is verified, never assumed harmless.
• Ambiguity is a refusal, never a pick. Two open handoffs on one track exits non-zero and names both.
• Exit codes separate the three outcomes: 0 success, 1 a refusal the caller can act on (no label in the repository, no open handoff, an ambiguous track, a body over the hard cap), 2 an execution failure. This is build_dist.py's contract and the reason a caller can tell a finding from the check not having run.
• Body size: warn above roughly 12 KB and refuse above 60 KB, under GitHub's own 65536-character limit. The cap is a backstop. What actually bounds a handoff is the per-section rules below.
• A dry-run flag that prints the calls it would make and writes nothing, because the first thing anyone will want is to see the chain step before trusting it to close an issue.

4. A session-handoff skill

Hand-authored at .agents/skills/session-handoff/SKILL.md, per the skill-lifecycle Skill, with the frontmatter's description carrying the trigger moments: about to end a session or a round of work, about to start one, asked for a handoff, asked what the previous round did, or about to re-attempt something a previous round may already have tried. It is that last case that earns the skill, since a session that does not know a chain exists will not go looking for one.

The skill owns the judgment and the script owns the mechanics. It states what belongs in each section and what does not, it routes the parked-decision-queue account to GOVERNANCE.md "Communicating with the User" as a generated include rather than a restatement, and it names the commands from a hub checkout as plain code spans rather than repo-relative links, which is what makes an installed copy usable.

The resume half states one rule that is easy to skip: re-derive live state, do not trust the handoff's copy of it. Branches, worktrees, open pull requests, and issue counts are read again from git and from GitHub at resume, and the handoff's state section is the pointer to what to read, not the answer. AGENTS.md "Session Scope" already says stale context is worse than absent, and a handoff is context by construction.

5. The handoff issue body template

A fixed section order, so a reader finds a given fact in the same place every time.

1. Next steps, in priority order. The single most valuable section, and first for that reason. Each item names what to do and what "done" looks like. At most a handful, ranked. A step blocked on something says so and names the blocker below.
2. External blockers. Anything the next session cannot resolve on its own: a maintainer decision, a third-party quota or outage, an upstream release, a credential, a reviewer bot that is not running. Each names who must act, what unblocks it, and what is safe to do meanwhile.
3. Internal dependencies. The ordering constraints among the next steps, each stated as the dependency and its reason, so a later session can re-rank when circumstances change instead of following an order it cannot audit.
4. State. Branch, worktrees and whose they are, open pull requests, what merged, whether a release was dispatched, and whether the primary checkout is clean. These are facts a resume re-derives, listed so the resume knows what to re-derive.
5. The parked decision queue. The count and the ranked list required by GOVERNANCE.md "Communicating with the User", which also requires the questions to be presented in the same act rather than only recorded.
6. What the last round did. Issues closed and filed, pull requests landed, and the peripheral issues filed along the way.
7. What not to repeat. The section the file form could never carry: paths explored that led nowhere, approaches that failed and why, problems discovered during execution, and the cost of each where it is known. An entry here is a claim about a specific attempt, not a general lesson.
8. New learnings. Only what is not already durable somewhere else, each with a pointer to where it was recorded. A lesson that belongs in governance goes to governance and appears here as one line and a link, per GOVERNANCE.md "Durable Knowledge and Self-Improvement".
9. The metadata block.

Sections 7 and 8 are what the chain exists for, and they are also the two most likely to be padded. The rule for both is that an entry earns its place by being specific enough to change a later session's behaviour.

6. Backlog exclusion

Every enumeration that ranks or counts open issues excludes handoff, because a handoff issue records no work of its own and an open one is always present by design. That is at least backlog-burndown's ranking step and any count of the open backlog. #1433 already records that handoff-reported backlog counts have been wrong, and adding a permanently-open issue class to the count without excluding it makes that worse.

7. The carried rule change

AGENTS.md "Session Scope" currently reads "Hand off in a file, never in context", with a 2 KB cap on a scratch file. That is replaced by the issue rule. The file form is not kept as a fallback: two documented mechanisms means a later session has to work out which one holds the truth, and the fallback is the one that rots.

Three consequences that must be handled in the same change rather than discovered afterwards:

• The section is verbatim fidelity per spec/section-model.md, so this is carried content reaching every fleet repository, and it needs the whole-unit review pass that scripts/canonical_review.py records.
• GOVERNANCE.md "Communicating with the User" sizes the parked-queue account to "the size rule that AGENTS.md 'Session Scope' sets for it". Replacing the 2 KB cap changes what that sentence points at, so the replacement still has to set a size rule for that sentence to name.
• The scratch file does not disappear from the fleet. backlog-burndown keeps working notes out of the tree for an in-flight run, and that stays true. What changes is that the handoff itself is no longer one of those notes.

Rules That Bind This Task

• Creating, commenting on, and closing an issue are outward-facing writes. Invoking the skill is the authorization for the chain it performs, and nothing else in the run is authorized by it.
• Every identifier passed to a write is captured from a read in the same run, and no write's output is suppressed or forced to success, per GOVERNANCE.md "Repository Boundaries and Write Safety".
• A handoff quotes no data observed in the maintainer's environment beyond what the work itself produced, per GOVERNANCE.md "Representative Data in Agent-Authored Text". An absolute home path is the routine case here, since a handoff naturally wants to name a worktree.
• The skill follows skill-lifecycle: both distribution trees regenerated by scripts/build_dist.py in the same commit, --check clean, AGENTS.md "Where the Rules Live" recording the new skill in its closing paragraphs as new content rather than a table row, and scripts/skills_install.py re-run per machine after merge.
• The script follows the fleet Python profile for the hub scripts/ tree, standard library only, with a test beside the others under scripts/tests/.

Risks

• gh-write-guard may refuse the script's calls. Session Handoff, 2026-09-09: #1321 Test 3 Proved, and the Handoff Moves to Issues #1469 records that the auto-mode classifier refuses gh pr comment and gh repo create outright. If it also refuses gh issue close or gh issue comment, the chain cannot complete unattended, and the design needs to know that before the skill claims it can. Measure it before building, with a positive control through the path, since a refusal and a silent no-op look identical from outside.
• An abandoned track leaves an open handoff that reads as current forever. tracks surfaces age, which makes it visible but does not resolve it. Whether an abandoned chain gets an explicit close path is worth settling during implementation.
• The template invites padding. Session Handoff, 2026-09-09: #1321 Test 3 Proved, and the Handoff Moves to Issues #1469's body runs to roughly 15 KB, over seven times the cap it replaces, and most of that length sits in exactly the two sections this design values most. The per-section rules are the control, and they are prose, so they will need a round or two of use before they hold.

Acceptance

• repo-config/configure.sh check passes on the hub with handoff declared, and repo-config/README.md "Labels" states that it is a surface marker and that a handoff issue carries no triage label.
• A real end-to-end run on this repository creates a new handoff issue, comments the forward link on Session Handoff, 2026-09-09: #1321 Test 3 Proved, and the Handoff Moves to Issues #1469, and closes Session Handoff, 2026-09-09: #1321 Test 3 Proved, and the Handoff Moves to Issues #1469, with each step's output shown. adopt puts the label and the metadata block on Session Handoff, 2026-09-09: #1321 Test 3 Proved, and the Handoff Moves to Issues #1469 first, since it predates both.
• handoff.py current on a repository with no handoff issue exits with the refusal code and names the reason, distinguishably from an execution failure.
• handoff.py current on a track with two open handoffs refuses and names both, and does not pick.
• chain --grep finds a string that appears only in a closed handoff two links back, which is the repeated-work failure this whole change exists to fix, demonstrated rather than asserted.
• python3 scripts/build_dist.py --check exits 0 and the canonical review pass is recorded for every new level-two section, including the rewritten AGENTS.md "Session Scope".
• AGENTS.md "Session Scope" no longer names a scratch file, still sets a size rule for GOVERNANCE.md "Communicating with the User" to point at, and that sentence still resolves.

Out of Scope

• Migrating the historical file handoffs into the chain. They are local-only and Session Handoff, 2026-09-09: #1321 Test 3 Proved, and the Handoff Moves to Issues #1469 already records where they are.
• A fleet-wide handoff label rollout to the carriers, which is Name the Label a Repository Reserves for Parked Decisions Where a Carrier Can Read It #1434's problem and is fixed once for every label rather than once per label.
• Any automation that writes a handoff without a session asking for one.