Governance Artifact Inventory

.decapod/governance.json is the sole tracked governance authority. It holds a compact baseline, current-PR identity and claims, cumulative checkpoints, explicit unresolved obligations, and normalized logical sections:

Health Engine claims remain in .decapod/data/decapod.db, and runtime workunit manifests in .decapod/data/workunits/. Neither is a second tracked research ledger. See the governed execution model.

Explicit PR lifecycle and publication invariant

Use decapod govern artifacts migrate to import valid legacy split files losslessly. Read operations never write. Conflicting or malformed authority fails closed instead of being silently repaired. begin-pr --id <change> --base-branch <branch> starts the explicit boundary only when discarded state is recoverable from Git. Accepted completed claims stay in Git history; explicit unresolved obligations carry forward. Resolve an obligation with resolve-obligation --id <id> --resolution <text> --proof-ref <evidence>.

Before each authored commit, finish the relevant plan, trajectory, claim, spec, and validation work; stage authored files; record a unique checkpoint; then stage the governance document and commit:

git add <authored-paths>
decapod govern artifacts checkpoint --id <unique-id> --summary "What changed and was checked" --proof-ref <evidence>
git add .decapod/governance.json
git commit -m "Describe the governed change"

Checkpoints are cumulative within the current PR. Publication and CI verify exact immutable material at every authored commit, including merges, and reject erased or rewritten checkpoints. A valid file only at the PR tip is insufficient. Pre-adoption legacy history is not retroactively represented as verified proof. A new trajectory resets only its current Jev observations; committed prior observations remain recoverable through Git.

Population order and write boundaries

Use the existing commands in dependency order:

1. Begin one stable PR identity with govern artifacts begin-pr.
2. Populate intent, todo binding, and scope with govern plan init or update.
3. Record actual current-PR claims with falsifiers and planned checks/proof hooks; do not create placeholder claims or claim support before evidence exists.
4. Perform the work and record its inspected/modified paths, checks, evidence, and unresolved assumptions with govern trajectory init and record.
5. Run decapod validate against the current completed batch.
6. Stage material, record a unique checkpoint, stage governance.json, and commit.

Persist meaningful intent, scope, evidence, and commit boundaries throughout the work instead of reconstructing them only at the end. Combine related updates at one boundary, and skip repeated unchanged content. A new claim or changed scope returns to the affected earlier step; it does not restart the PR identity.

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:

1. Master is generated by Decapod vN (pins say vN).
2. User/agent PRs with installed vN merge.
3. A new release vN+1 is cut from master (Cargo/CHANGELOG only).
4. Users install vN+1. Master pins remain vN until a user/agent PR runs validate with vN+1 and 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 initializes absent empty claims and preserves existing evidence. Inventory reports each logical section's schema and semantic currency; it does not invent claims or replace plan, trajectory, or validation work.

inventory --claims-note "..." records a current-PR checkpoint without inventing a research claim. inventory --compact performs lossless legacy normalization. Successful validation writes the logical validation section without a self-referential hash cycle. Do not use DECAPOD_VALIDATE_SKIP_GIT_GATES as an agent publication shortcut. Stage and checkpoint the final material before committing.

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.

Current-contract review and remote publication proof

When a PR changes implementation surfaces, workspace publish requires explicit reviews of the current INTERFACES, ARCHITECTURE, and SECURITY contracts. This is agent-authored review evidence, not automated proof that prose is semantically correct. An accurate unchanged spec does not need a cosmetic rewrite:

decapod govern plan review-spec \
  --path .decapod/managed/specs/INTERFACES.md \
  --disposition unchanged-with-reason \
  --reason "Inspected the changed command: existing response and error contracts remain accurate"

Repeat for ARCHITECTURE and SECURITY with findings specific to each review. Use updated for a material authored correction, or requires-decision when human judgment is needed. The command computes the spec's material hash and the current code fingerprint; callers cannot supply their own hashes. Later code or authored spec changes invalidate the review. Fingerprint refresh alone is not a review.

Ordinary review-spec cannot silently approve an unchanged pending decision. After receiving an explicit human answer, record that answer deliberately:

decapod govern plan resolve-spec-review \
  --path .decapod/managed/specs/INTERFACES.md \
  --decision-ref "review thread and human answer reference" \
  --reason "The human accepted the documented contract and its stated tradeoff"

This uses the same declared-approval authority as govern plan approve; the reference preserves provenance and is not cryptographic human authentication. The original question remains in the review record. A decision about stale code or stale spec content is rejected. Never invent a decision reference or infer approval. Existing 1.0 plans remain readable; recording reviews writes plan 1.1.

After review, refresh supported projections and run validation. The validation epoch binds the plan (including review evidence), claims, authored and generated spec content, entrypoints, and managed Dockerfile. It excludes the logical validation section itself so committing a receipt does not create a self-referential commit loop. Plan and trajectory must name the same current todo. Required logical sections must be valid, and the normalized document must match committed bytes and participate in the PR diff. Checkpoints bind every authored commit to its exact material.

Publication pushes the captured commit to the captured push URL, reads the exact remote head and base back, fetches those immutable objects, and checks their base-to-head diff. GitHub publication reuses an existing matching open PR or creates a draft, verifies repository/head/base/SHA and the complete paginated PR file list, and checks for head/base movement during readback. It does not infer success from git push or gh pr create exit status alone.

remote_verified and pr_verified are separate result fields. Non-GitHub branch publication can succeed with an explicit warning that PR proof is unavailable. Missing GitHub CLI/authentication, PR creation errors, wrong targets, truncated file lists, or remote races are hard failures. PUBLICATION_INCOMPLETE means the branch was already pushed but the PR must not be reported ready. Fix the stated condition and retry workspace publish; retries reuse matching PRs and never force-push or delete the published branch. Transport diagnostics are not echoed because they may contain credentials.

Fresh work branches

workspace ensure initializes the branch-local document from the embedded, versioned template after creating an isolated branch from the selected accepted base. Its draft plan and initial trajectory describe the current claimed task, including captured intent and scope. agent.init and validation share this initializer for manually created fresh worktree branches. They do not rewrite main/master or treat initialization as successful validation.

A stable change ID survives repeated calls, process restarts, branch renames, and rebases. New-branch evidence must agree with Git's accepted base and the inherited document must be recoverable in Git. Dirty, malformed, missing-task, and ambiguous accepted context is preserved with an actionable error. Old accepted claims, checkpoints, and receipts stay in Git history; policy and explicit unresolved obligations carry forward. Read-only status and inventory never initialize.

Container workspace paths

Container workspaces share .decapod/data and .decapod/managed/migrations with the host for coordination databases, leases, and datastore locks. The clone retains branch-local tracked governance, accepted project configuration and overrides, living specs, sessions, and awareness. Initialization happens before launch against the exact prepared base, and startup preserves that branch. An older whole-.decapod bind mount or symlink is rejected with GOVERNANCE_WORKSPACE_ALIAS; recreate the workspace with the supported layout before writing governance.

Host-root runtime lookups alias the branch's managed directory, with only managed/migrations overlaid from the shared host ledger. This preserves atomic ledger updates and prevents historical migrations from rerunning, while version counters and tracked specs remain branch-local. Existing host config and overrides are available read-only for shared-datastore policy decisions; branch files remain the input to source and document validation.