46 lines
4.3 KiB
Markdown
46 lines
4.3 KiB
Markdown
# 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, the plan and its authority (clear user request, standing policy, or explicit decision), ownership, verification outcomes, review identity/findings/fingerprint, integration, blockers, and the next safe action. Retain the template's headings for helper compatibility; use short entries or “not applicable” rather than inventing ceremony for every section.
|
|
|
|
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:
|
|
|
|
```bash
|
|
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. Save the initial plan and scoped decisions before dependent mutation; batch record changes with meaningful commits instead of committing every gate. The exclusive lock serializes cooperating helper invocations; external mutation of its pathname is outside the contract. A stale digest, lock, temporary artifact with no valid record, validation failure, or filesystem error blocks dependent 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, and changed paths; retain a patch artifact when needed to distinguish concurrent or interrupted edits.
|
|
|
|
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 affected mutation and inspect the evidence. Resume automatically only when ownership is re-established, prior children are terminal, and the next action preserves all work within existing authority. Ask with evidence-backed options when recovery would discard work, change agreed behavior, accept uncertain ownership, or broaden scope.
|
|
|
|
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. Prefer the latest valid saved record only after reconciling it with Git; distinguish saved from committed checkpoints. When interrupted-write evidence conflicts, use a committed valid record as a fallback if available, then inspect and resolve uncertainty before mutation. Absence of an initial record commit alone is not an orphan or approval gate.
|
|
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 conflicting evidence remains unresolved, scope needs a new decision, child liveness cannot be proven, or recovery crosses an approval boundary. Resume routine work automatically when inspection restores the evidence within existing authority. Treat the record as a recovery map, not a transaction log.
|