Summary
When a repository was initialized with an older Decapod release and agents run a newer Decapod binary, validation can hard-fail before the repository has an easy repair path.
Observed while moving this repository to Decapod 0.82.1:
decapod validate reported entrypoint_metadata_missing for AGENTS.md, CLAUDE.md, CODEX.md, and GEMINI.md.- It reported missing generated-data whitelist rules for
.decapod/managed/ and .decapod/governance/.
- It reported missing managed project specs and a missing governed plan artifact.
- The recovery required discovering and running
decapod init --force --all --proof, manually handling the archived entrypoints, initializing and approving a plan, refreshing specs, and rerunning validation.
The current behavior makes an old-to-new environment migration look like a repository failure and leaves agents to infer that re-init is the repair path. A forced re-init can also overwrite project entrypoints, so it is not an ideal generic recommendation.
Proposed improvement
Provide an explicit, safe, idempotent repair command such as decapod env refresh or decapod init --repair that:
- Detects release drift and prints the exact migration being applied.
- Updates entrypoint release and fingerprint metadata without losing project-specific instructions.
- Migrates generated-spec and managed-spec layout plus the required
.gitignore allowlist.
- Creates or upgrades required governance JSON artifacts and spec manifests.
- Preserves backups when a file truly must be replaced, with a clear merge/removal follow-up.
- Runs the relevant validation gates and reports any remaining human action.
Validation should offer this repair path before hard-failing on remediable environment drift, while still keeping the final validation gate authoritative.
Acceptance criteria
- A repository initialized by an older supported Decapod release can be upgraded with one documented command.
- Custom AGENTS.md rules are preserved or surfaced for an explicit merge.
- The command is deterministic and safe to rerun.
- The command leaves the repository in a state where
decapod validate can run normally, with only genuine project-specific failures remaining.
Summary
When a repository was initialized with an older Decapod release and agents run a newer Decapod binary, validation can hard-fail before the repository has an easy repair path.
Observed while moving this repository to Decapod 0.82.1:
decapod validatereportedentrypoint_metadata_missingfor AGENTS.md, CLAUDE.md, CODEX.md, and GEMINI.md..decapod/managed/and.decapod/governance/.decapod init --force --all --proof, manually handling the archived entrypoints, initializing and approving a plan, refreshing specs, and rerunning validation.The current behavior makes an old-to-new environment migration look like a repository failure and leaves agents to infer that re-init is the repair path. A forced re-init can also overwrite project entrypoints, so it is not an ideal generic recommendation.
Proposed improvement
Provide an explicit, safe, idempotent repair command such as
decapod env refreshordecapod init --repairthat:.gitignoreallowlist.Validation should offer this repair path before hard-failing on remediable environment drift, while still keeping the final validation gate authoritative.
Acceptance criteria
decapod validatecan run normally, with only genuine project-specific failures remaining.