diff --git a/CHANGELOG.md b/CHANGELOG.md index 951ddfb8..8b7945ae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,16 @@ Notable changes to house-rules. Versions follow [semantic versioning](https://se ## Unreleased +- `hr-handoff` gains a reference for handing work to a successor thread. A successor keeps the base + title and ends it with ` v`; the first thread counts as `v1` and is renamed at the handoff, and + threads are found by registry row, project and thread id, never by title. A session is replaced + for stale injected guidance only when the change is session-critical (an always-on rule, a safety + rule, the catalog entry of a skill the session uses, a subagent definition); skill bodies and docs + need only the reread. A replacement never happens mid-turn, mid-evaluation that fixed its + guidance, or with an external action pending, and only when the session is idle with its ledger + reconciled. The handoff names each open offer by ID so a bare `go` cannot select the wrong one, + the outgoing thread is marked settled with a pointer to the successor, and the successor + re-points registry rows, scheduled tasks, pull request watches and its messaging name. - `hr-benchmarking` no longer has a 3% default band for "no clear change". There is no minimum gain size: a favorable difference counts as a gain when it is outside the variation criterion declared before the first run (the comparison's own run-to-run spread) and the outputs are identical. When the diff --git a/skills/hr-handoff/SKILL.md b/skills/hr-handoff/SKILL.md index 93eb279c..4c7cc0fa 100644 --- a/skills/hr-handoff/SKILL.md +++ b/skills/hr-handoff/SKILL.md @@ -69,6 +69,10 @@ the host binds to the outgoing thread: retire it. 5. Give each bound item a row in the receipt, with owner, state and next action. +When the new thread replaces this one as its successor, also follow +[successor-thread.md](references/successor-thread.md) for when a replacement is +warranted, its safe boundary, the title and the successor record. + At a low-quota stop, save essential state first and record partial coverage when feasible. An unfinished receipt or failing check never delays that stop. diff --git a/skills/hr-handoff/references/successor-thread.md b/skills/hr-handoff/references/successor-thread.md new file mode 100644 index 00000000..6e6f3915 --- /dev/null +++ b/skills/hr-handoff/references/successor-thread.md @@ -0,0 +1,76 @@ +# Replace a session with a successor thread + +Follow this when a handoff moves work to a fresh thread that takes over from +the current one. It decides when replacing a session is warranted, when it is +safe and what the handoff and the successor record. It does not authorize +starting a thread. The house rules' § Repository work still requires the +user's direction, a standing spin-off preference or a rule that requires the +handoff. The host's own guidance owns the tool calls that create, rename and +rebind a thread. + +## When stale guidance warrants a new session + +Replace a session because its injected guidance went stale only when the change +is session-critical: + +- an always-on rule, or a safety rule +- the catalog entry (name and description) of a skill the session uses +- a subagent definition the session uses + +A change to a skill body or a doc does not warrant a new session. The session +rereads it with `hr-agent-guidance-refresh` at its next boundary, and the body +is read when the skill runs. That skill notes that a reread does not prove the +injected context changed, so use the list above, not the reread, to decide +whether a replacement is needed. + +## Boundary + +Never replace a session mid-turn, in the middle of an evaluation that fixed its +guidance, or while an external action is pending. An action is pending when it +has started without a recorded result. Replace it only when the session is +idle, nothing is running and the ledger is reconciled under the house rules' +§ Finishing work. + +## Successor title + +A successor keeps the base title and ends it with ` v`. The first thread +counts as `v1` and is renamed at the handoff. + +1. If the title ends in ` v` followed by digits, the base is the title without + that ending and N is that number. Otherwise the base is the whole title and + N is 1. +2. Rename the outgoing thread to ` v` when its title does not already + end that way. +3. Give the successor ` v`, writing N+1 as a plain number without + leading zeros. + +A title is a label for people. Never look a thread up by its title. Use the +registry row, the project and the thread id. + +## What the handoff records + +- The outgoing thread's id and the successor's id, so each points to the other. +- Each open offer by the offer ID the ledger recorded for it, with its + question, options and recommendation. The house rules' § Offers records an ID + for every offer, including a text-only one that never displayed it. The + successor treats an offer as open only if the handoff lists it and the latest + ledger or source record still shows it open. An offer answered, completed, + deferred or superseded since the handoff was written authorizes nothing. A + bare code or `go` in the successor selects an offer only when one listed offer + is open. With several, it asks which one, as § Offers requires. +- The inventory and read-backs from the skill's thread-move step. The + receiving thread re-points to itself each item the host lets it bind: + registry rows, scheduled tasks, pull request watches and the messaging name + the work was known by. For an item it cannot bind, the handoff keeps the + recorded reason it stays with the outgoing thread. Where the host does not let + the successor take over the name, the handoff says which name the successor + registers and who needs to be told. + +## Successor record + +- Mark the outgoing thread settled and record a pointer to the successor where + the host keeps such notes. Do this last, after the successor confirms it has + read the handoff. +- The successor starts by reading the handoff in full. It re-points each item + it can bind, with a read-back, and records every result in the receipt, + including the items that stay behind. Only then does it take new work.