compact-handoff

name	compact-handoff
description	Use during long tasks when evidence, state, and next actions must survive context compaction. Handles compaction judgment and handoff records only; no automatic hook behavior.
compatibility	["Python 3.11+ standard library"]

compact-handoff

compact-handoff preserves task continuity before or after context compaction. It does not trigger automatic compaction, add hooks, or create background summaries. It only defines the quality bar for a handoff that a human or future agent can safely resume.

Contents

• When To Use
• Pre-Compaction Record
• Do Not Compact When
• Resume Procedure
• Validator Rules
• Warnings

When To Use

• Context is long enough that work state may be lost.
• Another session or agent must continue the implementation.
• Test results, changed files, remaining work, forbidden surfaces, or rollback paths need to survive compaction.

Pre-Compaction Record

Write a short handoff with these fields, then validate it with scripts/compact_handoff.py <handoff-file> --json. If validation returns status=fail, fix the handoff before compacting.

[compact-handoff]
- objective: <current objective>
- completed: <completed work>
- in-progress: <current item>
- next-step: <one next action>
- files-changed: <absolute paths>
- tests-run: <commands and results>
- forbidden-surface: <paths or actions not to touch>
- rollback: <nearest rollback path>

Do Not Compact When

• A RED test is failing and the root cause is still unknown.
• A live configuration file is being edited without a rollback path.
• The next step is a user approval gate.
• Secret, token, credential, or private key text is exposed in the context.

Resume Procedure

1. Read objective, in-progress, and next-step first.
2. Inspect the real diff for files-changed and compare it with the handoff.
3. If the most recent test failed, route into systematic-debugging.
4. Claim completion only after verification-before-completion runs again.

Validator Rules

• All 8 required fields must exist.
• Secret-like values fail validation. The validator must not print raw values.
• Handoffs that touch live config such as ~/.claude/settings.json, ~/.codex/hooks.json, ~/.codex/config.toml, or ~/.agents/skills/ need a concrete rollback path.
• tests-run: not run or pending produces a warning. That warning does not block compaction, but it blocks completion claims.

Warnings

• Do not call /compact automatically.
• Do not use compact-handoff as a reason to create extra reports or plans.
• Do not use compaction to hide uncertainty.
• A handoff is a continuity artifact, not evidence that the work is complete.