Governance Artifact Inventory
Publication-ready Decapod changes carry four repository-native governance artifacts:
| Artifact | Updated by | Classification | Purpose |
|---|---|---|---|
.decapod/governance/plan.json | Agent through decapod govern plan; approved through the governed surface | Governed execution state | Records refined intent, scope, phases, decisions, and proof hooks as the plan changes. |
.decapod/governance/claims.json | Agent or researcher through the sanctioned claims surface | Authoritative falsifiable-claims ledger | Connects a claim to its baseline, observable condition, failure mode, measurement, and proof gate. It is not proof by itself. |
.decapod/governance/trajectory.json | Agent through decapod govern trajectory | Evidentiary custody record | Records run intent, boundaries, inspected and modified files, commands, assumptions, checks, and evidence over time. |
.decapod/governance/validation.json | decapod validate | Generated validation receipt | Records the validation result for identified repository state and supports the publication gate. |
These artifacts work with todos, assignments, living specifications, evidence, receipts, projections, custody, and publication state. See the governed execution model for the full ownership and lifecycle map.
The research claims ledger is distinct from Health Engine claims in
.decapod/data/health.db. Health Engine claims record operational health and
proof events; claims.json records falsifiable, repository-owned research
claims and is part of the PR proof surface.
Coherent bundle (publication invariant)
The four files are a single publication unit. Project PRs treat them as one bundle even though agents refresh them through separate CLI surfaces.
| Layer | What it enforces |
|---|---|
Inventory (decapod govern artifacts inventory) | All four present, schema-valid, and semantically current |
Validate (GOVERNANCE_PR_UPDATES) | Feature-branch base...HEAD must include all four paths |
| Publish / CI | Same PR-level participation |
This is not per-commit publication-bundle churn (#1232 / #1233). Release-bound entrypoints and the managed Dockerfile pin prove currency at HEAD and may be inherited when the Decapod version is unchanged. Governance JSON still must move on every project PR.
Inventory evaluates and reports; it does not auto-regenerate the four files
as one command. Agents refresh each surface via govern plan, govern trajectory,
govern artifacts inventory --claims-note, and decapod validate.
Release pin flywheel
Master entrypoint/Dockerfile/manifest pins record the Decapod version that generated that master tip. A cargo-only release-plz merge does not rewrite pins. There is no Release Artifact Sync workflow and no post-release heal PR.
Flywheel:
- Master is generated by Decapod
vN(pins sayvN). - User/agent PRs with installed
vNmerge. - A new release
vN+1is cut from master (Cargo/CHANGELOG only). - Users install
vN+1. Master pins remainvNuntil a user/agent PR runs validate withvN+1and commits healed entrypoints, Dockerfile pin, and specs manifest (first PR for the new installed binary must refresh all of them).
Inventory and repair
decapod govern artifacts inventory --base-branch master
decapod govern artifacts inventory --repair
Repair creates .decapod/governance/claims.json only when it is absent. It
never overwrites project-specific claim content.
Inventory fails closed when any artifact is missing, schema-invalid, or not
semantically current. Publication and decapod validate additionally require
all four paths in the PR delta for project PRs. validation.json is the one
file produced by a successful validate: when it is the only missing path,
validate writes it and counts the working-tree file. DECAPOD_VALIDATE_SKIP_GIT_GATES
is a test/debug escape hatch, not the agent publication sequence.
An external tracker such as GitHub Issues, Jira, Linear, or Beads may remain the organizational system of record. Decapod's todo and claim state governs the accepted work at the repository execution layer.