agents-handoff 0.0.0-stage → 2.0.2

package/install/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "agents-handoff",
+  "version": "2.0.2",
+  "description": "Internal manifest for the in-tree installer. The published package is the repository root (agents-handoff), whose bin `agents-handoff` points here.",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "agents-handoff": "./install.mjs"
+  },
+  "main": "./install.mjs",
+  "files": [
+    "install.mjs",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node ../tools/handoff.test.mjs"
+  },
+  "keywords": [
+    "agent-handoff",
+    "installer",
+    "npx",
+    "skill"
+  ],
+  "author": "Alot1z",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Alot1z/agent-handoff.git"
+  },
+  "homepage": "https://alot1z.github.io/agent-handoff/INSTALL.html",
+  "bugs": {
+    "url": "https://github.com/Alot1z/agent-handoff/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {}
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "agents-handoff",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.2",
+  "description": "Write, verify, and hand off complete AI working sessions across any harness (Claude Code, Codex, DeepSeek Harness, plain JSONL or text logs). Cross-harness session capture with sha256 provenance and verified continuation.",
+  "type": "module",
+  "main": "tools/handoff.mjs",
+  "bin": {
+    "agents-handoff": "./install/install.mjs",
+    "agent-handoff": "./tools/handoff.mjs"
+  },
+  "files": [
+    "install/",
+    "tools/",
+    "templates/",
+    "refs/",
+    "schemas/",
+    "docs/",
+    "tests/",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE",
+    "SKILL.md",
+    "skill.json",
+    "capability-registry.json",
+    "permission-policy.json",
+    "handoff.config.schema.json",
+    "handoff.config.example.json"
+  ],
+  "scripts": {
+    "test": "node tools/handoff.test.mjs",
+    "check:docs": "node .github/scripts/check-docs.mjs",
+    "check:session-index": "node .github/scripts/build-sessions-index.mjs --check",
+    "prepublishOnly": "node tools/handoff.test.mjs && node .github/scripts/check-docs.mjs && node .github/scripts/build-sessions-index.mjs --check",
+    "verify": "node tools/handoff.mjs verify",
+    "build": "node tools/handoff.mjs build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "handoff",
+    "session",
+    "continuation",
+    "cross-harness",
+    "provenance",
+    "claude-code",
+    "codex",
+    "installer",
+    "npx",
+    "skill"
+  ],
+  "author": "Alot1z",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Alot1z/agent-handoff.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Alot1z/agent-handoff/issues"
+  },
+  "homepage": "https://alot1z.github.io/agent-handoff/",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {}
+}

package/permission-policy.json

@@ -0,0 +1,33 @@
+{
+  "schema_version": "1.0-permission-policy",
+  "approved_workspaces": [
+    ".",
+    "repo-upstream",
+    ".agent-handoff",
+    ".context"
+  ],
+  "system_read_only_roots": [
+    "C:\\Windows",
+    "C:\\Program Files",
+    "C:\\Program Files (x86)"
+  ],
+  "personal_data_roots": [
+    "C:\\Users"
+  ],
+  "denied_roots": [],
+  "grants": {
+    "DISCOVERY_ONLY": "allow",
+    "READ_ONLY": "allow",
+    "WORKSPACE_WRITE": "allow",
+    "EXTERNAL_EFFECT": "needs_auth",
+    "DESTRUCTIVE": "needs_auth",
+    "IRREVERSIBLE": "needs_auth"
+  },
+  "risk_to_level": {
+    "R0": "READ_ONLY",
+    "R1": "WORKSPACE_WRITE",
+    "R2": "EXTERNAL_EFFECT",
+    "R3": "DESTRUCTIVE",
+    "R4": "IRREVERSIBLE"
+  }
+}

package/refs/ADAPTERS.md

@@ -0,0 +1,33 @@
+# Harness adapters — how any client feeds the handoff subsystem
+
+No harness is special-cased in code. The engine consumes ONE canonical input shape;
+every adapter below is just "get your store into that shape". Canonical = conversation-vault
+raw JSONL line:
+
+```json
+{"seq":0,"ts":"1787669764492","harness":"dsh","source":"<origin path>",
+ "session":"<id>","thread":"<project/thread>","role":"user|assistant|system|tool",
+ "kind":"<free-form: reasoning|tool_use|text>","text":"<message body>"}
+```
+
+| Harness | Store | Adapter route | Status |
+|---|---|---|---|
+| DeepSeek Harness desktop+CI | ~/.dsh/sessions/<proj>/session-*.jsonl.zstd | vault.mjs import (zstd -> canonical) then build --source canonical.jsonl | VERIFIED live (85 sessions archived 2026-08-25) |
+| Desktop client with a SQLite session store (machine-specific path) | <client data dir>/projects/*/desktop-v2.db | vault adapter (sqlite read-only, parts_json -> turns) | VERIFIED live on a client whose turns live in a sqlite table |
+| Claude Code | ~/.claude/projects/**/*.jsonl | vault adapter (native JSONL -> canonical) | VERIFIED live |
+| Codex | ~/.codex/sessions/*.jsonl | generic claude-jsonl parser | OBSERVED compatible shape |
+| CI / anything | any exported JSONL | direct: build --source file.jsonl | VERIFIED (self-test) |
+| Plain text/markdown log | any file | role-marker fallback parser (user:> / assistant:>) | VERIFIED (self-test) |
+
+!! Preferred route: archive through conversation-vault FIRST (vault.mjs), then point handoff.mjs
+at the canonical raw file — lossless capture + provenance + render in one chain.
+Direct-to-handoff also works when no vault exists.
+
+Class mapping (engine classify()):
+- role=tool or kind contains "tool"   -> TOOL
+- kind contains reason|think          -> THOUGHT  (AI-agent thoughts processing)
+- role=user                           -> USER
+- role=assistant                      -> AGENT
+- everything else                     -> OTHER (kept in raw, omitted from render)
+
+Secrets law (#211): no credentials/tokens ever written into handoffs — sources are chat stores only.

package/refs/bootstrap.md

@@ -0,0 +1,59 @@
+# Bootstrap — load a handoff into a fresh session (port of choughton/llm-handoff SHARED_REPO_INIT_PROMPT)
+
+Use this when a fresh agent session must load repository context before handling
+a `HANDOFF.md` assignment. Replaces re-explaining setup: the next agent starts
+working by *loading*, not by asking.
+
+## Bootstrap order
+
+1. Read `refs/handbook.md` (shared operating rules) — the equivalent of the source
+   HANDBOOK.
+2. Read `refs/protocol.md` (frontmatter/status/evidence/work-packet schema).
+3. Read `PROJECT_STATE.md` if present (durable project-state pointer).
+4. Read the live `HANDOFF.md`.
+5. Read the repo's `README.md` / `AGENTS.md` / architecture doc as needed.
+6. Read only the extra files the specific assignment requires.
+
+## State model
+
+Agents do not share memory:
+- `HANDOFF.md` — live routing state.
+- `PROJECT_STATE.md` — durable project state (when the repo uses one).
+- Git history — durable execution record.
+
+## Fresh-session contract
+
+A session loaded this way must:
+- Know its **role** (`refs/roles.md`) and its exact assignment (Work Packet).
+- Know the canonical **status enum** and the **five-field evidence block**
+  before it claims anything complete (`refs/protocol.md`).
+- Follow the bootstrap order before touching `HANDOFF.md`.
+
+## The operating rule
+
+Prompts are advisory; validators and the dispatcher are authoritative. If the
+prompt conflicts with parsed frontmatter, Git state, or repository instructions,
+**stop and report the conflict**.
+
+## PROJECT_STATE.md pattern (durable status pointer)
+
+Keep it short. Detailed implementation notes go in commits/handoffs/project docs.
+
+```markdown
+# Project State
+
+## Current Status
+- **Active Epic:** none / <epic>
+- **Current Blocker:** none / <blocker>
+- **Active Branch:** main
+
+## Open Followups
+- none / <item>
+
+## Completed Scope Ledger
+Append one compact line per approved epic close:
+- **<Epic Name>** - <one-line summary>. SHA `<sha>`. Verification: <checks>.
+```
+
+Two files, two jobs: `HANDOFF.md` is the live state; `PROJECT_STATE.md` is the
+durable status; Git history is the durable record of completed work.

package/refs/brief-checklist.md

@@ -0,0 +1,79 @@
+# Brief Discipline — "it's working if" (distilled from aihero.dev/skills-handoff + mattpocock/skills handoff)
+
+mattpocock's `/handoff` buys **portability, not compression**. A handoff is a
+transit file for work that must travel — a new harness, a new directory, a
+colleague, or a forked side-task. When nothing is travelling, stay in the
+session and go lighter. This checklist is the quality bar for any brief this
+skill produces.
+
+## When a handoff is warranted (the four triggers)
+
+1. Swapping harness (Claude Code → Codex → DeepSeek Harness …) — the new harness can't see the old context.
+2. Moving to a different directory/repo — a prototype is the common case.
+3. Sending the work to a colleague — they need something readable cold.
+4. **Forking a side-task mid-phase** — you keep working; a second agent takes the fork.
+
+If the same harness and same directory and you're just continuing, a compact is
+better than a handoff. Reach for this skill only when the work must travel.
+
+## What travels, what does not
+
+Carry:
+- The **live thread**: what's in flight, why, and what's next.
+- A **suggested-skills section** naming what the next agent should reach for.
+- The **next task's focus** (pass the argument: what the next session is for).
+
+Reference, never copy:
+- Specs, plans, ADRs, issues, commits, diffs → by **path or URL**, not pasted text.
+  Keeps the file small and the settled detail in ONE place (no drift).
+
+Redact:
+- API keys, passwords, PII. Nothing in a handoff is a secret.
+
+## "It's working if" — the acceptance test
+
+The handoff is good when **all** hold:
+
+- [ ] The document is a *small fraction* of the conversation, and specs/issues/diffs
+      appear as paths/URLs, not copied text.
+- [ ] You can read it **cold**, without the original session open, and know what to do next.
+- [ ] A fresh agent **starts working** instead of asking you to re-explain setup.
+- [ ] In the fork case, your original session is still sitting there untouched when you return.
+- [ ] The suggested-skills section names the skill you'd have reached for yourself.
+- [ ] Nothing in it is a key, a token, or a password.
+
+## The false-premise trap (downgrade before handoff)
+
+The next agent treats the document as a **contract** and will not re-check it —
+so a belief written as a fact becomes a false premise for everything that follows.
+Before you hand it over: **read it and downgrade anything you only assumed.**
+Unless a claim is oracle-backed, write it at its true evidence level
+(INFERRED/UNKNOWN); this is the same rule as our Doctrine #3 and the KB's
+never-silently-upgrade law.
+
+## Handing the file to the next agent
+
+Point at the **path**, never paste the summary into a shell command. A summary
+containing backticks or `$(...)` gets mangled by interpolation, and the usual
+failure is **silent truncation** — the next agent starts with a quietly
+incomplete brief. `Read this file, then continue.`
+
+## Handoff vs. durable docs
+
+Ask: *is this true next month?*
+- **CLAUDE.md / durable docs** — standing context loaded into every session. Facts that keep getting re-explained live here.
+- **Handoff** — one piece of work in flight, dead once that work lands. A half-finished task is a handoff.
+
+## handoff vs compact vs clear (the phase-boundary map)
+
+| Move | What it preserves | When |
+|---|---|---|
+| **continue** | the primary source (conversation as it happened) | first thing to rule out; no summary needed |
+| **/compact** | compresses context, keeps intent, fresh window | same harness, same dir, staying in the loop |
+| **/handoff** | a portable file: the work survives the move | work must travel / fork a side-task |
+| **/clear** | nothing — empty window | everything behind you is disposable (one-way) |
+
+All three of compact/handoff/clear turn a primary source into a summary;
+continuing is the only one that doesn't. Our engine's fileset gives you both:
+the brief is the portable summary; `timeline.jsonl` + `TOOLS.md` keep the
+fidelity so nothing is silently lost.

package/refs/handbook.md

@@ -0,0 +1,58 @@
+# Handbook — shared operating rules for every role (port of choughton/llm-handoff HANDBOOK)
+
+Read this before acting on any `HANDOFF.md` assignment. Role prompts (`refs/roles.md`)
+add role-specific rules; this file is the shared protocol.
+
+## How the live handoff works
+
+`HANDOFF.md` is the **live state file**. Only the active dispatcher role owns it
+during its turn. Provider-native subagents, skills, or helper agents are internal
+support machinery and **must not** independently rewrite the handoff.
+
+Two layers, always:
+- **YAML frontmatter** for machine routing (authoritative).
+- **Markdown body** for human-readable context, evidence, findings, and work packets.
+
+## State model — no shared memory
+
+Agents do not share memory. Version-controlled files are the source of truth:
+
+- `HANDOFF.md` — the live routing state.
+- `PROJECT_STATE.md` — the durable project-state pointer (when the repo uses one).
+- Git history — the durable execution record.
+
+Our engine's fileset slots into this: `timeline.jsonl` is append-only turn truth,
+`HANDOFF.llm.json` is the machine-replayable payload, `manifest.json` carries the
+sha256 provenance, and `TOOLS.md` holds every tool call verbatim.
+
+## Escalation protocol
+
+Use **one** of the canonical statuses, never a synonym:
+
+- `escalate_to_user` + `next_agent: user` — human input required.
+- `blocked_missing_context` — the missing input is specific and the next human
+  question is clear.
+- `blocked_implementation_failure` — an implementation path failed structurally
+  and needs re-scoping.
+
+## When to flag uncertainty
+
+Stop and route to `planner`, `validator`, or `user` when **scope, ownership,
+routing, tests, or Git state** are ambiguous. Do not widen your role boundary to
+avoid asking. Guessing forward on ambiguous state is a protocol violation.
+
+## The operating rule
+
+**Prompts are advisory. Validators and the dispatcher are authoritative.**
+If a prompt conflicts with parsed frontmatter, Git state, or repository
+instructions, stop and report the conflict — do not silently follow the prompt.
+
+## Common failure modes (catch these; they are your reviewers' checklist)
+
+- Missing or malformed YAML frontmatter.
+- Provider names (Codex/Gemini/Claude) used as public workflow roles.
+- `scope_sha: HEAD` instead of a concrete SHA.
+- Completion claims without `## Verification Evidence`.
+- Planner assignments without a concrete Work Packet.
+- Auditor approvals that skip spec compliance (phase-1).
+- Repeated implementer/auditor bounces on the same story — signal it early.

package/refs/protocol.md

@@ -0,0 +1,117 @@
+# Handoff Protocol — live dispatch state, frontmatter, status, evidence (port of choughton/llm-handoff)
+
+> Adapted from `choughton/llm-handoff` (Apache-2.0). This fuses its file-based
+> dispatch protocol into agent-handoff's fileset. Where our engine already
+> existed (RESULT/WHAT_CHANGED..., sha256 manifests), this ADDS the live
+> routing layer: a single `HANDOFF.md` file that doubles as **the mutex and the
+> debugger** — every transition is visible as text, and a run only advances when
+> the frontmatter parses, routes, and validates.
+
+## The inversion (core doctrine)
+
+> **Prompts are advisory. Validators are authoritative.**
+
+Agents may write prose, but a run only advances when the handoff state parses,
+routes, and validates. `HANDOFF.md` is the shared state file, `git rev-parse
+HEAD` SHAs are the durable record of completed work, and when routing is
+ambiguous or unsafe the run **fails closed and pauses** instead of guessing.
+
+## Two layers of every handoff
+
+1. **YAML frontmatter** — machine routing (authoritative; the dispatcher reads
+   this, not the prose).
+2. **Markdown body** — human/agent-readable context, evidence, findings, and
+   work packets.
+
+## Required frontmatter schema
+
+Every `HANDOFF.md` write begins with YAML frontmatter. The YAML block is
+authoritative; prose is context.
+
+```yaml
+---
+next_agent: <enum>       # required: planner | backend | frontend | auditor | validator | finalizer | user
+reason: <string>         # required: quote every `reason` value
+epic_id: <string>        # optional active epic identifier
+story_id: <string>       # optional active story identifier
+story_title: <string>    # optional short active story title
+remaining_stories:       # optional remaining story IDs/titles
+  - <story id/title>
+status: <enum>           # canonical status when the handoff claims completion/blockage
+bounce_count: 0          # optional dispatcher-maintained retry count
+evidence_present: true   # optional validator hint for evidence-aware handoffs
+scope_sha: <git SHA>     # required when close_type is story|epic; concrete 7-40 hex, NEVER "HEAD"
+close_type: <enum>       # optional: story | epic
+prior_sha: <git SHA>     # optional prior verified SHA
+producer: <string>       # required: the role that wrote this handoff
+---
+```
+
+Hard rules:
+- **Quote every `reason`.**
+- **Run `git rev-parse HEAD`** for concrete SHAs; never write `scope_sha: HEAD`,
+  a branch name, or a placeholder.
+- `scope_sha` must be a 7–40 char hex SHA that `git cat-file -t` resolves.
+
+## Status enum (canonical — no synonyms)
+
+Use exactly one. Do **not** invent `done`, `approved`, or `blocked`.
+
+| Status | Meaning | Typical emitter |
+|---|---|---|
+| `ready_for_review` | Implementation complete, needs audit | backend, frontend |
+| `verified_pass` | Auditor verified assignment + quality gates | auditor |
+| `verified_fail` | Auditor found a defect; routes back to implementer | auditor |
+| `blocked_missing_context` | Cannot proceed without more info | any role |
+| `blocked_implementation_failure` | Implementation attempted but structurally failed | backend, frontend |
+| `escalate_to_user` | Human decision required | any role |
+
+Maps to our engine's RESULT values: `ready_for_review`→*needs review*, `verified_pass`→`DONE`, `verified_fail`→*returned*, `blocked_*`→`BLOCKED`, `escalate_to_user`→*needs human*. The two vocabularies coexist: the enum is the routing state, the RESULT is the completion contract.
+
+## Verification Evidence block (required for completion statuses)
+
+Required when `status` is `ready_for_review`, `verified_pass`, or `verified_fail`.
+Exact five-field shape:
+
+```markdown
+## Verification Evidence
+
+- **Commands run:** verbatim command lines
+- **Output summary:** one line per command with exit codes
+- **Commit SHA verified:** concrete 7-40 char Git SHA; never `HEAD`
+- **Files changed or reviewed:** relative paths
+- **Unresolved concerns:** list or `none`
+```
+
+**Evidence must come from the current turn.** Prior output, assumptions, and
+model confidence are not evidence. This is the same law as our
+RESULT-without-EVIDENCE-never-becomes-VERIFIED.
+
+## Work Packet (planner → backend/frontend)
+
+Planner assignments include exactly these six fields:
+
+```markdown
+## Work Packet
+
+- **Objective:** one bounded result
+- **Files in scope:** relative paths
+- **Files out of bounds:** relative paths or `none`  ← never omit, even "none"
+- **Context:** required reading or background
+- **Verification command:** exact command to run
+- **Expected next route:** role after success
+```
+
+Never use vague placeholders: `add validation`, `handle errors appropriately`,
+`write tests`, `implement later`, `as needed`. Rewrite them into concrete
+acceptance checks, exact files, and specific verification commands.
+
+## Common failure modes to catch
+
+- Missing or malformed YAML frontmatter.
+- Provider names (Codex/Gemini/Claude) used as public workflow roles — translate to the public role.
+- `scope_sha: HEAD` instead of a concrete SHA.
+- Completion claims without `## Verification Evidence`.
+- Planner assignments without a concrete work packet.
+- Auditor approvals that skip spec compliance.
+- Repeated implementer/auditor bounces on the same story.

package/refs/roles.md

@@ -0,0 +1,75 @@
+# Roles — the dispatch ladder (port of choughton/llm-handoff role prompts)
+
+The public `next_agent` enum is: `planner | backend | frontend | auditor |
+validator | finalizer | user`. Provider names (Codex/Gemini/Claude) are only
+*adapter examples* — an agent filling a role is addressed by its public role,
+never by a model/harness name.
+
+Every role follows the same bootstrap before acting (see `refs/bootstrap.md`)
+and holds the shared rules of `refs/handbook.md`.
+
+## planner — sequence the work, never implement
+
+- Translate project goals into **bounded assignments** with concrete Work Packets
+  (see `refs/protocol.md`).
+- Decide the next role. Route backends/data to `backend`, UI to `frontend`,
+  completed work needing review to `auditor`, ambiguous/wrong state to `validator`,
+  human input to `user`, and `finalizer` only for an approved epic close.
+- Never `git push`. Never write `scope_sha: HEAD`.
+- **Work Packet discipline:** every line must be a concrete acceptance check,
+  an exact file, or a specific verification command. Vague placeholders are a defect.
+
+## backend — own server/data/CLI/integration work
+
+- Owns backend code, data contracts, persistence, CLI glue, tests, integration wiring.
+- Does NOT own frontend-only work, planning, audit verdicts, or finalizer state.
+- On a misroute, rewrite the handoff and route to `planner`/`validator`/`user`
+  instead of expanding scope. Do not modify `PROJECT_STATE.md` unless assigned.
+- On completion: route to `auditor`, `status: ready_for_review`, and include the
+  `## Verification Evidence` block with a concrete `scope_sha`.
+
+## frontend — own UI/browser work
+
+- Mirrors `backend` but for UI/browser/app-code. Same roles, evidence, and
+  completion contract.
+
+## auditor — review, enforce invariants, never silently fix
+
+- Two-phase audit:
+  1. **Phase 1 — spec compliance:** verify the producer did *exactly* the
+     assigned work. Catch missing scope, scope creep, unrequested extras, wrong
+     files. **If phase 1 fails, stop** — emit `status: verified_fail`, route
+     back to the implementer or `planner`, and give NO code-quality feedback for
+     work that does not match the assignment.
+  2. **Phase 2 — code quality** (only after phase 1 passes): correctness,
+     maintainability, tests, safety, repository fit.
+- Story-level success → `planner`/next implementer; epic-level success → `finalizer`.
+- Never claim `verified_pass` without the `## Verification Evidence` block.
+
+## validator — repair and gate (the authoritative check)
+
+- A support role that inspects `HANDOFF.md` and reports whether the loop can
+  continue **safely**. Does not edit the handoff, re-route, implement, commit, or push.
+- Runs the 12-point check — see `refs/validator.md`.
+- Outcome: `VALID: YES | NO | WARNINGS-ONLY`. Only a FAIL makes `VALID: NO`;
+  the loop must not advance on `NO`.
+
+## finalizer — close an approved epic
+
+- Clears an approved epic-level close (`close_type: epic` only), updates the
+  durable `PROJECT_STATE.md` when the repo uses one, rewrites the handoff to route
+  the next cycle to `planner` or `user`, and reports a machine-readable result.
+- `next_agent: finalizer` must never persist after finalization.
+- Does not scope the next epic; does not push unless the repo authorizes that role.
+
+## user — the human gate
+
+- Used when a human decision, credentials, or an unsafe ambiguity is required.
+- The router's escape hatch: when route evidence is insufficient, set
+  `next_agent: user` and ask ONE concrete question in the body.
+
+## Role boundary doctrine
+
+Never widen your role boundary to avoid asking. If scope, ownership, routing,
+tests, or Git state is ambiguous, route to `planner`, `validator`, or `user`. Do
+not guess forward — that is the fail-closed rule made concrete.

package/refs/validator.md

@@ -0,0 +1,73 @@
+# Validator Gate — the authoritative check (port of choughton/llm-handoff handoff-validator)
+
+The validator is the **authoritative** half of "prompts are advisory, validators
+are authoritative." It inspects the live `HANDOFF.md` routing state and reports
+whether the loop can continue safely. It does **not** modify the handoff,
+re-route the work, implement code, commit, or push.
+
+## Routing contract (how ambiguity resolves)
+
+| Situation | next_agent |
+|---|---|
+| Backend/data/CLI/integration implementation | `backend` |
+| UI/frontend implementation | `frontend` |
+| Planning, scope decomposition, next-story assignment | `planner` |
+| Completed implementation needing review | `auditor` |
+| Approved final scope, `close_type: epic` only | `finalizer` |
+| Broken/malformed/internally-inconsistent handoff state | `validator` |
+| Missing human decision, missing credentials, unsafe ambiguity | `user` |
+
+If the handoff names a provider (Codex/Gemini/Claude), translate it to the public
+role it is serving in this repo. When route evidence is insufficient, set
+`next_agent: user` and ask one concrete question — **never guess.**
+
+## The 12-point check
+
+Ordered. Each item is `PASS | WARN | FAIL` with a one-line detail:
+
+1. YAML frontmatter exists at the top of `HANDOFF.md`.
+2. Frontmatter parses as YAML.
+3. `next_agent` is one of the public enum.
+4. `reason` is present, non-empty, and quoted when it contains punctuation.
+5. `close_type`, when present, is `story` or `epic`.
+6. `scope_sha` is present when `close_type` is set.
+7. `scope_sha` and `prior_sha`, when present, are 7–40 char hex and resolve via
+   `git cat-file -t <sha>`.
+8. `finalizer` routing is used only with `close_type: epic`.
+9. `status`, when present, is a canonical enum value.
+10. Completion statuses include the `## Verification Evidence` block.
+11. The body has enough detail to act on: files, checks, findings, ACs.
+12. Current git state is compatible with the handoff claim — report dirty state
+    as WARN unless the repo requires clean state.
+
+## Output shape (Machine-Readable Result)
+
+Return exactly:
+
+```text
+VALID: YES | NO | WARNINGS-ONLY
+CHECKS:
+  FRONTMATTER:    PASS | WARN | FAIL - <detail>
+  SHA-PRESENT:    PASS | WARN | FAIL - <detail>
+  SHA-FRESH:      PASS | WARN | FAIL - <detail>
+  ROUTING:        PASS | WARN | FAIL - <detail>
+  CONTENT:        PASS | WARN | FAIL - <detail>
+  GIT-STATE:      PASS | WARN | FAIL - <detail>
+SUMMARY: <one sentence>
+BLOCKERS: <numbered list if VALID=NO, otherwise "none">
+```
+
+Only a FAIL makes `VALID: NO`. WARN-only results use `VALID: WARNINGS-ONLY`.
+A handoff that is `NO` or `WARNINGS-ONLY` must **not** advance the run — fail
+closed, never guess forward.
+
+## Router summary (when this role is exercised as a router)
+
+The router variant *does* rewrite the handoff to make routing deterministic.
+After writing, it returns:
+
+```text
+ROUTING UPDATED: YES
+NEXT_AGENT: <role>
+REASON: <one sentence>
+```