fix: make stale-spec validation errors actionable for agents

.decapod/README.md

@@ -1,6 +1,6 @@
 # .decapod - Decapod Control Plane
 
-Decapod is a repo-native governance kernel for AI coding agents. It turns human intent into bounded, durable, and proof-backed agent work. Agents invoke it at decision, validation, recovery, and publication boundaries; it does not perform the agent's work.
+Decapod is a repo-native governance kernel for AI coding agents. It turns human intent into bounded, durable, and proof-backed agent work. Its layer is explicit: models produce intelligence, agents perform work, repositories preserve state, and Decapod governs the transition from intent to proof. Reliability is designed, not hoped for. Agents invoke it at decision, validation, recovery, and publication boundaries; it does not perform the agent's work.
 
 GitHub: https://github.com/DecapodLabs/decapod
 Canonical Contract: `assets/constitution.json` section `core/DECAPOD`

.decapod/governance/claims.json

@@ -11,7 +11,7 @@
     "status": "active",
     "created_at": "2026-07-22",
     "updated_at": "2026-08-04",
-    "change_policy": "Claims are changed only through an issue-scoped review that preserves the baseline, Decapod condition, failure modes, measurements, proof gate, open questions, and evidence status. Governance artifact generation and publication inventory are tracked under issue #1025; the v0.85.0 cloud auto-login work for #1077 remains bounded to Decapod-owned backend composition, machine-local session reuse/refresh, repository identity, and CI surfaces while Propodus retains hosted authorization and persistence policy. One-time human GitHub approval, live protected todo behavior, and cross-system acceptance remain explicitly unproven follow-ups. The #1100/#1101/#1102 session lifecycle proof now covers local-session-first custody, machine-session reuse/refresh, pending-flow deduplication, one-time exchange persistence, and secret-free failure handling; deployment-provided live proof remains a protected follow-up. Hermes governance integrity and readiness substrate: issues #1094, #1096, #1059, #1055, and #1072. Propodus integration #766: bind cloud client repository scope to verified GitHub identity and prove the typed fake-service contract. Issue #1105: canonical Propodus cloud setup through decapod init; recovery guidance, machine-local custody, and compatibility behavior are covered by the implementation and focused tests. Issue #1105 publication proof: PR #1115 includes canonical init setup, machine-local custody behavior, redacted recovery guidance, and focused tests. Issue #1110 local datastore architecture: canonical .decapod/data/decapod.db now stores subsystem state in namespaced tables; this PR adds migration and proof coverage while preserving JSONL compatibility and deferring dactyl integration. Issue #1109 receipt-freshness follow-up: the v0.89.2 catch-up preserves the falsifiable claims ledger while rebinding trajectory and validation receipts to the current commit lifecycle; the pre-commit git SHA equality is not treated as a valid invariant because the commit does not yet exist at validation time. Single canonical decapod.db migration hardening for #1118; preserves legacy archives and supports Propodus #56/#58 table contract while keeping dactyl integration out of scope. Houseboat 2 (#852 / PR #1133): exclusive claim leases, path/scope/category overlap rejection, reclaim on expiry/staleness, todo renew and todo fleet projection. Progress slice; not a closure claim. Regenerated release-bound entrypoint fingerprints and specs manifest for Decapod 0.89.4 (Houseboat 2 PR #1133). Houseboat wave 2 (#852/#857/#860 / follow-on to #1133): lease generations, lifecycle (claimed/extended/yielded/reclaimed), intent anchors, yield command, proof-gated exclusive done, capacity/expiry-risk fleet projection, stalled/abandoned trajectory motion. Houseboat wave 3 (#852/#857/#860): typed dependency readiness now gates TODO claim/completion and drives work-claim/fleet proof-blocker projections; trajectory merge, journals, budgets, and semantic overlap remain explicitly unresolved. PR #1144 repairs authority resolution, canonical event observation, and clean spec-drift reporting for #1138, #1139, and #1140. PR #1150: fleet coherence README, validation vocabulary, workspace contracts, JSONL seal, source/test boundary PR-1150 fleet coherence and contract repairs PR #1152: SQLite schema consolidation #1126–#1131 (unified events, agents, node_edges, task_tags, patterns→meta) and product README polish; behavior-preserving with forward migration schema_fold.v001. CI fix on PR #1152: collapsible-if clippy, unified events reads for traces/map/lcm/knowledge, restore validation_epoch object shape. Houseboat wave 4 (#852): lease-aware handoff with generation advance and intent preservation. Issue #1154: validate hard-fails stale entrypoint markers and managed Dockerfile release pins; fingerprints are computed from the evaluating binary to avoid hand-maintained SHA footguns. PR #1160 / issue #1159: bind project proof commands to a single repository-local authority (.decapod/config.toml); fail closed on dual live registries with .decapod/proofs.toml; store-root resolution, accurate provenance, validate/runtime agreement. Solve GitHub Issue #1134: add step to check for git diff/drift after running decapod validate in ci.yml and decapod-validate.yml to ensure PR contains up-to-date entrypoints/specs. Issue #1183: living specs are evidence material; fingerprint-only refresh is insufficient for PR promotion. Issue #1183: living specs are evidence material for proof completion; fingerprint-only refresh is insufficient. PR for #1171+#1172: Darwin Nix packaging proof (remove host /usr/bin/ld fuse-ld), aarch64-darwin CI on macos-latest, checks.rust-toolchain lockstep with rust-overlay, docs for proven systems and overlay refresh. No flake.lock auto-mutation. Fix post-release drift since #1170/v0.95.4: heal 0.96.2 pins on master; sync in release-plz job; master push heal; no re-init inventing drift. CI post-merge fingerprint policy: DECAPOD_VALIDATE_SKIP_FINGERPRINT_GATES for push/release heal; PR-only entrypoint drift gate; release-artifact-sync opens chore/release-bound-sync PR under master ruleset (PR required + signatures) instead of direct master push (run 30870806233). Documentation positioning and reliability-layer messaging update; no runtime behavior or architecture changes."
+    "change_policy": "Claims are changed only through an issue-scoped review that preserves the baseline, Decapod condition, failure modes, measurements, proof gate, open questions, and evidence status. Governance artifact generation and publication inventory are tracked under issue #1025; the v0.85.0 cloud auto-login work for #1077 remains bounded to Decapod-owned backend composition, machine-local session reuse/refresh, repository identity, and CI surfaces while Propodus retains hosted authorization and persistence policy. One-time human GitHub approval, live protected todo behavior, and cross-system acceptance remain explicitly unproven follow-ups. The #1100/#1101/#1102 session lifecycle proof now covers local-session-first custody, machine-session reuse/refresh, pending-flow deduplication, one-time exchange persistence, and secret-free failure handling; deployment-provided live proof remains a protected follow-up. Hermes governance integrity and readiness substrate: issues #1094, #1096, #1059, #1055, and #1072. Propodus integration #766: bind cloud client repository scope to verified GitHub identity and prove the typed fake-service contract. Issue #1105: canonical Propodus cloud setup through decapod init; recovery guidance, machine-local custody, and compatibility behavior are covered by the implementation and focused tests. Issue #1105 publication proof: PR #1115 includes canonical init setup, machine-local custody behavior, redacted recovery guidance, and focused tests. Issue #1110 local datastore architecture: canonical .decapod/data/decapod.db now stores subsystem state in namespaced tables; this PR adds migration and proof coverage while preserving JSONL compatibility and deferring dactyl integration. Issue #1109 receipt-freshness follow-up: the v0.89.2 catch-up preserves the falsifiable claims ledger while rebinding trajectory and validation receipts to the current commit lifecycle; the pre-commit git SHA equality is not treated as a valid invariant because the commit does not yet exist at validation time. Single canonical decapod.db migration hardening for #1118; preserves legacy archives and supports Propodus #56/#58 table contract while keeping dactyl integration out of scope. Houseboat 2 (#852 / PR #1133): exclusive claim leases, path/scope/category overlap rejection, reclaim on expiry/staleness, todo renew and todo fleet projection. Progress slice; not a closure claim. Regenerated release-bound entrypoint fingerprints and specs manifest for Decapod 0.89.4 (Houseboat 2 PR #1133). Houseboat wave 2 (#852/#857/#860 / follow-on to #1133): lease generations, lifecycle (claimed/extended/yielded/reclaimed), intent anchors, yield command, proof-gated exclusive done, capacity/expiry-risk fleet projection, stalled/abandoned trajectory motion. Houseboat wave 3 (#852/#857/#860): typed dependency readiness now gates TODO claim/completion and drives work-claim/fleet proof-blocker projections; trajectory merge, journals, budgets, and semantic overlap remain explicitly unresolved. PR #1144 repairs authority resolution, canonical event observation, and clean spec-drift reporting for #1138, #1139, and #1140. PR #1150: fleet coherence README, validation vocabulary, workspace contracts, JSONL seal, source/test boundary PR-1150 fleet coherence and contract repairs PR #1152: SQLite schema consolidation #1126–#1131 (unified events, agents, node_edges, task_tags, patterns→meta) and product README polish; behavior-preserving with forward migration schema_fold.v001. CI fix on PR #1152: collapsible-if clippy, unified events reads for traces/map/lcm/knowledge, restore validation_epoch object shape. Houseboat wave 4 (#852): lease-aware handoff with generation advance and intent preservation. Issue #1154: validate hard-fails stale entrypoint markers and managed Dockerfile release pins; fingerprints are computed from the evaluating binary to avoid hand-maintained SHA footguns. PR #1160 / issue #1159: bind project proof commands to a single repository-local authority (.decapod/config.toml); fail closed on dual live registries with .decapod/proofs.toml; store-root resolution, accurate provenance, validate/runtime agreement. Solve GitHub Issue #1134: add step to check for git diff/drift after running decapod validate in ci.yml and decapod-validate.yml to ensure PR contains up-to-date entrypoints/specs. Issue #1183: living specs are evidence material; fingerprint-only refresh is insufficient for PR promotion. Issue #1183: living specs are evidence material for proof completion; fingerprint-only refresh is insufficient. PR for #1171+#1172: Darwin Nix packaging proof (remove host /usr/bin/ld fuse-ld), aarch64-darwin CI on macos-latest, checks.rust-toolchain lockstep with rust-overlay, docs for proven systems and overlay refresh. No flake.lock auto-mutation. Fix post-release drift since #1170/v0.95.4: heal 0.96.2 pins on master; sync in release-plz job; master push heal; no re-init inventing drift. CI post-merge fingerprint policy: DECAPOD_VALIDATE_SKIP_FINGERPRINT_GATES for push/release heal; PR-only entrypoint drift gate; release-artifact-sync opens chore/release-bound-sync PR under master ruleset (PR required + signatures) instead of direct master push (run 30870806233). Documentation positioning and reliability-layer messaging update; no runtime behavior or architecture changes. Issue #1179 / PR #1198: stale-spec validation errors now provide decapod rpc --op specs.refresh recovery guidance; runtime behavior is limited to diagnostics and existing invariants remain unchanged."
   },
   "scope": {
     "product": "decapod",

.decapod/governance/plan.json

@@ -1,16 +1,15 @@
 {
   "schema_version": "1.0.0",
-  "title": "Clarify Decapod product positioning and governed execution model",
-  "intent": "Teach Decapod's architectural layer before listing capabilities: models produce intelligence, agents perform work, repositories preserve state, and Decapod governs the transition from intent to proof. Center reliability as designed, not hoped for, while positioning Decapod as the repo-native governance kernel for bounded, convergent, proof-backed agent work without runtime or architecture changes.",
+  "title": "Finish PR #1198 stale-spec recovery diagnostics",
+  "intent": "Make OUT_OF_SYNC_SPECS and STALE_SPECS_FINGERPRINT validation errors actionable so agents can run decapod rpc --op specs.refresh and retry validation, without changing governance invariants.",
   "state": "APPROVED",
   "todo_ids": [
-    "docs_01kza3j6mf354j1p"
+    "bugs_01kz9vb1kjsyq30b"
   ],
   "proof_hooks": [
-    "ontology and reliability positioning is visible in README and mdBook introduction",
-    "mdbook build and mdbook test docs/book",
     "cargo test --test doc_alignment",
-    "decapod validate --refresh-specs (bounded)",
+    "cargo test --lib",
+    "decapod validate --refresh-specs",
     "git diff --check"
   ],
   "unknowns": [],
@@ -21,10 +20,11 @@
   "constraints": {
     "forbidden_paths": [
       "src/main.rs",
-      "tests"
+      "docs",
+      "README.md"
     ],
     "file_touch_budget": null
   },
   "phases": [],
-  "updated_at": "1785974137Z"
+  "updated_at": "1785977148Z"
 }