feat(hr-handoff): successor thread title, rotation trigger, boundary and record

[bompus]

hr-handoff now says how to replace a session with a successor thread: the title, when stale guidance is worth a new session, when it is safe, and what the handoff and successor record.

Nothing in rules/ or another skill covered this. I searched rules/ and skills/ for handoff, successor, rotate and rotation. The matches were the low-quota modifier, the plan-files modifier, hr-what-next and the existing thread-move step in hr-handoff, none of which set a title, a trigger or a boundary for replacing a session. hr-agent-guidance-refresh only says a reread does not prove injected context changed. The new text is a reference file in hr-handoff, linked from SKILL.md, so it sits beside the thread-move step it extends. No host tool calls are in it, so any host can use it.

Part	What it says
Title	Keep the base title and end it with v<N>. The first thread counts as v1 and is renamed at the handoff. A trailing v<digits> is parsed and incremented. Threads are found by registry row, project and thread id, never by title.
Trigger	Replace for stale injected guidance only when the change is an always-on rule, a safety rule, the catalog entry of a skill the session uses, or a subagent definition. Skill bodies and docs need only the reread.
Boundary	Never mid-turn, mid-evaluation that fixed its guidance, or with an external action pending. Only when idle, nothing is running and the ledger is reconciled.
Record	The outgoing thread is marked settled with a pointer to the successor. The handoff names open offers by ID, and with more than one open the successor asks which a bare go means. The successor re-points registry rows, scheduled tasks, pull request watches and its messaging name, with read-backs.

Choices made in passing:

• The section does not authorize starting a thread. It defers to the house rules' § Repository work for that.
• The successor asks which offer a bare go means when several listed offers are open, matching § Offers.
• The skill's description is unchanged, so skill selection should not shift.

Checks on this head: node --test test/*.test.mjs (151 pass, 7 skipped), bun test test/ skills/ (488 pass, 8 skipped, 0 fail), npm run check:package -- --bun, pinned oxfmt check clean, pinned oxlint (one existing warning in test/install-ps1.test.mjs, not touched here), and the plain-prose checker on the new file. Not covered: host adoption, and the host-specific tool steps, which the chief-of-staff Orchestrator writes.

---

Summary by cubic

Adds successor-thread guidance to hr-handoff for replacing a session when stale injected guidance warrants it, covering the successor title, the rotation trigger, the safe boundary, and what the handoff and successor record. The new reference successor-thread.md is linked from SKILL.md and makes no host tool calls, so any host can use it.

• A successor keeps the base title and ends it with v<N>; the first thread counts as v1 and is renamed at the handoff. Threads are found by registry row, project and thread id, never by title.
• A replacement is warranted only for session-critical changes — an always-on rule, a safety rule, a skill's catalog entry, or a subagent definition. Skill bodies and docs need only a reread, and a replacement never happens mid-turn, mid-evaluation, or with an external action pending, only when the session is idle with its ledger reconciled.
• The handoff lists each open offer by its recorded offer ID, and the successor acts on one only when the latest ledger still shows it open, so a bare go selects only when one listed offer is open. The outgoing thread is marked settled with a pointer to the successor, who re-points registry rows, scheduled tasks, pull request watches and its messaging name; items it cannot bind keep the recorded reason and stay behind.

^{Written for commit eb30674. Summary will update on new commits.}

Summary by CodeRabbit

• Documentation
  • Added guidance for handing work from a current thread to a successor, including when a replacement is warranted and how to title it.
  • Clarified that handoffs should happen only when the session is idle and its work records are reconciled.
  • Added steps for transferring open offers and work items, recording handoff outcomes, and ensuring the successor reviews and updates transferred items before taking on new work.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository YAML (base), Organization UI (inherited)
• Review profile: CHILL
• Plan: Advanced
• Run ID: 64144d82-bf96-4aad-ba05-45069516de34

📥 Commits

Reviewing files that changed from the base of the PR and between a22ca9f and eb30674.

📒 Files selected for processing: 3

• CHANGELOG.md
• skills/hr-handoff/SKILL.md
• skills/hr-handoff/references/successor-thread.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 4 remain after this review.

📝 Walkthrough

The handoff instructions define when a session can be replaced and how to title a successor thread. They specify the handoff contents, work-item transfer and read-back, and conditions for settling the outgoing thread.

Changes: Successor Thread Handoff

Layer / File(s)	Summary
Replacement criteria and safe boundary skills/hr-handoff/SKILL.md, skills/hr-handoff/references/successor-thread.md	The skill instructions refer to the successor-thread guidance. The reference limits replacement to specified stale guidance and requires an idle session with no pending action and a reconciled ledger.
Successor title and handoff reconciliation skills/hr-handoff/references/successor-thread.md, CHANGELOG.md	The guidance defines successor title versioning, handoff records for threads and open offers, transferable work-item handling, and when to settle the outgoing thread. The changelog summarizes these conventions.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to eb306

The guidance governs authorized successor handoffs and preserves the existing authorization requirement. It adds idle, reconciled transfer and confirmation steps; no concrete merge risk remains beyond normal checks.

### Architecture Summary

Architecture risk: 🔵 Low · up to eb306

The change affects 2 systems.

Changed systems: skills, CHANGELOG.md

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — skills (service) was modified; 2 changed files map to changed impact.
• observed — CHANGELOG.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in CHANGELOG.md: Adds an Unreleased entry describing hr-handoff successor-thread conventions, when session replacement is permitted, and handoff updates to offers, registry rows, scheduled tasks, pull request watches, and messaging identity.
• observed — Modified behavior in skills/hr-handoff/SKILL.md: Adds a requirement to follow references/successor-thread.md when the new thread succeeds this one, covering replacement criteria, safe boundary, title, and successor record.
• observed — Modified behavior in skills/hr-handoff/references/successor-thread.md: Adds criteria for when stale injected guidance warrants replacing a session: only changes to always-on or safety rules, used skill catalog entries, or used subagent definitions qualify. Changes to skill bodies or docs are reread at a boundary and do not themselves warrant replacement.
• observed — Modified behavior in skills/hr-handoff/references/successor-thread.md: Requires replacement to occur only when the session is idle, no work or external action is pending, and the ledger is reconciled; defines a pending action as one started without a recorded result.

Pre-merge checks: 6

Passed checks: 6 passed

Check name	Status	Explanation
Description check		The description clearly explains the change, motivation, alternatives considered, activation limits, placement, testing, and known coverage gaps. It does not reproduce the template checkboxes, but it …
Title check		The title is concise, specific, and accurately summarizes the successor-thread changes, including the title, rotation trigger, boundary, and record.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Suppressions Explained		The pull request changes only CHANGELOG.md and handoff documentation. The added lines contain no lint, type-check, or formatter suppression directive, and no lint or formatter configuration entry chan…
Rule Changes Documented		The PR changes skills/hr-handoff/SKILL.md and adds skills/hr-handoff/references/successor-thread.md. CHANGELOG.md contains a matching Unreleased entry for the new hr-handoff successor-thread…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[cubic-dev-ai]

All reported issues were addressed across 3 files

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>