harness-tools/skills/develop/develop-workflow/references/evidence-and-recovery.md

Evidence and recovery

Checkpoint records

Keep one concise Markdown record in the repository's established plan location; otherwise use docs/plans/<feature-branch-slug>.md. Require a unique path before creation. Store status/current phase, request/scope, Git identity, acceptance criteria, exact approved plan and gate decisions, assignment ownership, verification outcomes, review identities/findings/fingerprint, integration, blockers, and the next safe action.

Keep transcripts, leases, heartbeats, notification receipts, full command output, and model-authored execution graphs out of the record. Link durable artifacts or commits instead. Update only at meaningful boundaries; task tools hold high-frequency progress.

Prepare the complete candidate outside the record's same-directory temporary namespace and run:

node skills/develop/develop-workflow/scripts/checkpoint-record.mjs \
  <record.md> --input <candidate.md> --expected-sha256 <current-digest>

Omit --expected-sha256 only for first creation; require an absent target. Commit the initial record and every approved gate before dependent product mutation. A stale digest, lock, temporary artifact with no valid record, validation failure, or filesystem error blocks progress. Preserve artifacts for inspection; never hand-delete recovery evidence to make a command pass.

Assignment evidence

Before every mutating assignment, record:

• display name, profile, stable child/session IDs when exposed;
• deadline and exclusive owned paths;
• branch, HEAD, clean/dirty status, changed paths, and patch artifact.

After delivery, capture the same Git evidence and inspect the patch. Treat the entire ambiguous profile/run as a mutator when stable identity is unavailable. Reject unexpected commits and paths outside ownership.

On an ownership or Git invariant failure, freeze mutation and present evidence-backed choices: inspect, accept and replan, restore with a non-destructive patch, or abort. Obtain a user decision before proceeding.

On deadline expiry or missing delivery, request stop through the available control surface and prove the process/session terminal before reassignment. A completed UI indicator is not output or liveness proof. Keep the workflow blocked for human termination/takeover when liveness remains unknown.

Fresh-session recovery

Reconstruct observed reality before trusting prose:

1. Read repository instructions; inspect worktrees, branches, refs, status, commits, and diff.
2. Discover candidate records from observed branches/worktrees and repository conventions.
3. Treat a workflow branch/worktree without a record as an orphan. Preserve it; inspect branch, base, reflog, status, commits, and diff; ask whether to adopt it with a record, quarantine it, or remove it after separate cleanup approval.
4. Compare the record's base, branch, and checkpoint with Git evidence.
5. Preserve atomic-update temporary files. Use the last committed valid record until recovery is approved.
6. Rebuild task state from completed evidence and the recorded next action.
7. Freeze interrupted mutation until its diff is inspected and prior child liveness is terminal.
8. Resume from the last proven checkpoint.

Ask when evidence conflicts, scope may have changed, child liveness is unknown, or recovery needs risk. Treat the record as a recovery map, not a transaction log.