feat(skills): add develop workflow

2026-09-04 10:47:04 -04:00
parent a794a1e10a
commit 8c44c07c6a
9 changed files with 1074 additions and 1 deletions
@@ -0,0 +1,45 @@
+# 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:
+
+```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. 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.