---
id: hatch3r-handoff-readiness
type: rule
description: Handoff readiness checklist — pre-write validation before persisting a canonical handoff document.
scope: conditional
globs: .hatch3r/handoffs/active/**/*.md
precedence: high
tags: [orchestration, maintenance]
quality_charter: agents/shared/quality-charter.md
cache_friendly: true
---
# Handoff Readiness Checklist

Before writing a handoff to `.hatch3r/handoffs/active/`, verify each criterion. Refuse the write if any **Required** criterion fails; warn on **Recommended** failures.

## Required (fail = refuse write)

| # | Criterion | Rationale |
|---|-----------|-----------|
| 1 | Body ≤ 51,200 bytes (50 KB) | Token bloat — full transcripts and unbounded sessions degrade resume reliability |
| 2 | Body contains no full message transcript | Token bloat — structured fields only |
| 3 | All 8 required sections present (Problem, Decisions, Work Done, Work Remaining, Blockers, Next Steps, Build & Test Status, File Manifest) | Resume needs structured state |
| 4 | git_ref matches current HEAD (branch@sha7) | Staleness signal integrity |
| 5 | Frontmatter validates against schema | Loader interop |
| 6 | Injection-pattern scan clean (P-LEARN-01..05) | ASI06 memory poisoning prevention |
| 7 | Integrity hash computed (sha256:<hex>) | Tamper detection |

## Recommended (fail = warn)

| # | Criterion | Rationale |
|---|-----------|-----------|
| 8 | `summary` populated, ≤ 200 chars | Loader briefing budget |
| 9 | `target_agent` is explicit (not `any`) | Avoids handoff loops (industry anti-pattern) |
| 10 | `Build & Test Status` table populated with at least one row | Resume reliability — knowing whether tests passed at handoff time |

## Enforcement

The `hatch3r-handoff-preparer` agent applies this checklist before invoking `writeHandoff` in `src/content/handoffs/index.ts`. The `validateHandoffContent` function in `src/content/handoffs/validation.ts` runs criteria 1-7 as `errors[]` and 8-10 as `warnings[]`.

## Retro-Discredit Rule (D13 — handoff self-assessment trust gate)

Handoff confidence and completeness are self-rated by the preparing agent. When the resuming agent (or human) detects that the prior handoff overstated completeness — work flagged Done but reverted, tests claimed passing but failing on resume, blockers omitted — the resumer MUST:

1. Append a `retro_discredit:` block to the handoff manifest (`.hatch3r/handoffs/active/<id>.md` frontmatter) with: `discredited_by: <resumer-id-or-human>`, `discredited_on: <ISO-8601>`, `discredit_reason: <one-sentence cause>`, `prior_confidence: <high|medium|low>`, `effective_confidence: <high|medium|low>` (downgraded post-discredit).
2. Append a single line to `.hatch3r/handoffs/discredit-log.jsonl` (append-only, atomic append per `src/merge/safeWrite.ts`) with `{ts, handoff_id, discredited_by, prior_confidence, effective_confidence, reason}`.
3. The `hatch3r-handoff-preparer` and `hatch3r-handoff-loader` agents consult the discredit-log on next write/read — if a handoff's preparer has a discredit ratio above 25% across the last 10 handoffs, downgrade the new handoff's preparer-rated confidence one band before accepting.

Effect: self-assessed confidence becomes a track-record signal rather than a single-shot self-claim. Closes D13 SA13.4 F2 retro path (resumer undoes prior work but the handoff's confidence rating persists unchallenged).

## Cross-references

- Body sections schema: `.hatch3r/handoffs/README.md`
- Iteration Summary recap contract (Work Done ← recap outcome + files facet; Work Remaining ← `Not done:` line, absent ⇒ `None — full scope completed`; Blockers ← `Blockers:` line, absent ⇒ `None`): `rules/hatch3r-iteration-summary.md`
- Injection-pattern catalog: `agents/shared/injection-patterns.md` Section B
- Quality charter (confidence levels): `agents/shared/quality-charter.md`
