Stale-spec validation can intermittently leave agents without an actionable recovery path to publication

[sethpjacobs]

Summary

Decapod 0.96.4 can place an agent in an unsatisfiable publication state:

1. Workspace publication requires a material authored change under .decapod/managed/specs/*.md.
2. The generated agent contract prohibits agents from directly mutating .decapod/* and requires all access through the Decapod CLI.
3. The available specs.refresh operation only refreshes attestations and explicitly does not satisfy the material-edit gate.

In addition, an unrelated completed-but-unverified todo blocks publication from a separate todo-scoped workspace.

Environment

• Decapod: 0.96.4
• Repository custody: worktree
• Workspace: isolated, non-protected feature branch
• Platform: macOS

Reproduction

1. Create and claim a todo.
2. Create an isolated workspace with decapod workspace ensure.
3. Make and test a small application change.
4. Run decapod validate or decapod workspace publish.

Observed failures:

PROOF_HOOK_FAILED: 1 done TODO(s) are CLAIMED but not VERIFIED: code_01kz8e93mabwgb8w.

STALE_SPECS_FINGERPRINT: Significant repo surfaces changed since last specs refresh. Review and rewrite living-spec authored prose ... fingerprint/attestation refresh alone is insufficient ... then call decapod rpc --op specs.refresh.

The unverified todo belongs to unrelated prior work. The current workspace has its own claimed todo, governed plan, trajectory, passing focused tests, and clean lint results.

Contract conflict

The generated AGENTS.md states both:

• Each PR needs a material authored living-spec rewrite.
• Do not mutate .decapod/ state directly; all access must use the CLI.

No CLI operation appears to support authoring the required living-spec prose. decapod rpc --op specs.refresh is documented as insufficient for this gate. Consequently, an agent cannot reach a publishable state while obeying the generated contract.

Expected behavior

• Provide a sanctioned CLI/RPC operation for material living-spec authoring, or narrow the direct-mutation prohibition so agents may edit the authored portions of .decapod/managed/specs/*.md.
• Scope proof-hook publication checks to the current todo/workspace, or report unrelated stale todos as repository-level warnings rather than blocking an independent PR.
• If human intervention is intentionally required for living-spec prose, make that decision gate explicit before implementation and provide a deterministic handoff/recovery command.

Actual behavior

Publication is blocked with no agent-permitted recovery path. decapod govern artifacts inventory --repair does not resolve either failure, and decapod workspace publish exits after validation.

Additional note

Warnings about machine-local session storage fallback and Docker socket permissions were also present, but appear unrelated to these two publication failures.

[sethpjacobs]

Additional evidence from conference-dashboard PR #272:

• The repository explicitly ignores .decapod/governance/trajectory.json and .decapod/governance/validation.json because they are per-run receipts.
• decapod workspace publish nevertheless refused publication until both ignored files were force-added, stating that every PR must contain all four governance artifacts.
• After force-adding them, the PR gained 526 lines of generated receipt data. Removing them from the PR still allows decapod validate to pass because the ignored local files remain available on disk.
• decapod specs.refresh also produced a malformed duplicate Codebase Attestation section in managed/specs/VALIDATION.md: an extra section ended with <!-- decapod:codebase-attestation:end --> but had no matching start marker. Manually removing that duplicate, refreshing the manifest, and validating succeeds.

This demonstrates two additional contract inconsistencies:

1. The publisher requires files that the repository's Decapod-managed ignore policy classifies as current-run state.
2. Specs refresh can create malformed generated attestation markup that validation initially accepted.

Relevant downstream PR: https://github.com/LEGO/conference-dashboard/pull/272

[alexhraber]

@sethpjacobs, thanks for submitting your first issue.

I think the architectural conclusion in this issue is incorrect, but the failure mode you surfaced is useful.

Decapod is daemonless by design. Individual invocations are ephemeral, while the agent task continues and the repository preserves durable state between calls. A single prompt may invoke Decapod dozens of times as it works through the governed loop.

The important detail here is that spec refresh is already part of validation. The agent should not need to invent a separate recovery model or conclude that the contract is unsatisfiable. When validation fails because the specs are stale, the failure should tell the agent exactly what must be corrected and then allow it to continue.

In my own workflow, simply telling the agent to "execute the spec refresh" resolves the issue. This is needed, because the agent doesn't keep up with all the context. In fact, in the prior PR by @worldofgeese his specs refreshed without manual input, and over the hundreds of PR's I've made, I've only had to command the agent to refresh the specs a handful of times. The path is therefore reachable. This is not a deadlock.

What happened instead is that the agent encountered a valid validation failure, failed to act on it, and then authored the issue from that same misunderstanding. The issue describes the execution observed by the agent rather than establishing that no sanctioned recovery path exists.

So I would separate the diagnosis from the product improvement:

The diagnosis is that the contract is not unsatisfiable. The agent stopped before completing the governed workflow.

The improvement is that validation should emit a precise, actionable remediation when spec state is stale. It should tell the agent what is stale, what command or operation will repair it, and that validation should be retried afterward.

That preserves the gate while improving agent behavior.

The right fix is not to weaken publication or relax the contract. It is to make the validation failure operationally complete enough that the next action is unambiguous.

The other observations around proof scope, ignored receipts, and attestation generation may still be valid independent defects and should be reproduced separately. But they do not support the headline claim that Decapod’s agent contract is inherently unsatisfiable.

[alexhraber]

Hello @worldofgeese 👋

Since you’re evaluating Decapod as a governance layer, I’d like to establish a guiding principle for future issues and design discussions.

Governance guarantees are architectural invariants—they’re the properties Decapod exists to enforce. If an agent appears unable to satisfy one, let’s first determine whether the recovery path, diagnostics, validation feedback, or execution flow are the real issue before concluding that the guarantee itself should be relaxed.

That approach keeps us focused on improving the agent experience without compromising the governance properties organizations adopt Decapod for in the first place. In practice, many of the best improvements come from making recovery deterministic and actionable, not from weakening the underlying guarantees.

Please continue filing issues like this—they’re valuable. My only request is that we separate implementation defects and usability improvements from changes that would alter Decapod’s governance model. That distinction will help us build a stronger kernel together.

Thanks!

Very Best,
Alex H. Raber

[alexhraber]

Additional context from additional evidence reported above:

1. The repository explicitly ignores .decapod/governance/trajectory.json and .decapod/governance/validation.json because they are per-run receipts.
2. decapod workspace publish nevertheless refused publication until both ignored files were force-added, stating that every PR must contain all four governance artifacts.
3. After force-adding them, the PR gained 526 lines of generated receipt data. Removing them from the PR still allows decapod validate to pass because the ignored local files remain available on disk.
4. decapod specs.refresh also produced a malformed duplicate Codebase Attestation section in managed/specs/VALIDATION.md: an extra section ended with <!-- decapod:codebase-attestation:end --> but had no matching start marker. Manually removing that duplicate, refreshing the manifest, and validating succeeds.

1. trajectory and validation, as well as claims and plan governance files are primitives and supplementary output of the governance kernel. This is by design.
2. publication requires validation to succeed, which requires those 4 governance files to exist. This too, is by design.
3. When files are added, it is expected that lines will be added, this is evidence of the files containing data. After init and first PR, future changes will usually be 1-5 lines per file depending on the context of the change. View these 4 governance file as iterative logs per commit -- each commit will have the state of the repo at the time of the commit.
4. The reported malformed VALIDATION.md attestation should be treated as a possible agent–codebase alignment failure unless the exact code path can be reproduced deterministically. These specs are the agent’s interpretation of the repository. If the agent generated a malformed or incorrect representation once but the same repository state and command sequence do not reproduce it, the stronger signal is that the agent misunderstood the codebase or produced an unstable interpretation—not that Decapod’s governance contract is inconsistent. I’ll investigate it as an implementation defect only if the malformed output can be reproduced from the same inputs and execution path.

@sethpjacobs, please feel free to file a dedicated issue for the malformed VALIDATION.md output so we can reproduce the exact execution path and trace it to ground. I'd like to determine whether this is a deterministic generation defect or an agent-specific interpretation issue. If it is reproducible from the same repository state, inputs, and execution sequence, I'll treat it as an implementation bug and fix it independently of the broader governance discussion.

[alexhraber]

PR #1198 merged as 6f24d541 and shipped in v0.96.7.

The stale-spec path is now actionable without weakening the contract. When validation reports stale specs, it identifies the recovery path: inspect the affected living spec, run decapod rpc --op specs.refresh, rewrite authored prose when required, rerun validation, and continue toward publication. The material living-spec and proof gates remain blocking. The agent still authors the specification; Decapod validates it.

The release also includes:

• Markdown layout repair and validation for the malformed VALIDATION.md, SEMANTICS.md, and OPERATIONS.md cases reported here.
• Structural Mermaid guards for supported declarations, closed fences, and balanced delimiters.
• First-commit publication readiness for entrypoint fingerprints, managed specs, governance artifacts, and the managed Dockerfile.
• Fast-forward-only workspace promotion. Decapod never force-pushes a governed branch. A rejected push tells the agent to inspect the divergence, reconcile it, validate again, and retry. Git commands issued directly by an agent or harness remain outside Decapod’s control.
• The Clippy failure found during review was fixed before release.

This is the distinction I wanted to establish in the issue. The observed failure showed an agent stopping at a recoverable validation result. It did not show an unsatisfiable governance contract. The right fix was to make the next action explicit and keep the invariant.

One release-synchronization item remains. The v0.96.7 tag reports Cargo.toml version 0.96.7; its managed Dockerfile and four generated entrypoint headers still report 0.96.6. That artifact drift should be corrected in the release synchronization path.

I am leaving this issue open until that pin synchronization is corrected and verified.