Analysis report transactions
Use --report-only when you need to record a mission analysis report while
your checkout has other, unrelated uncommitted work. Without it,
record-analysis refuses on any dirty worktree. With it, the command commits
only the report and leaves your other changes exactly as they were.
spec-kitty agent mission record-analysis --mission <handle> --input-file <report> --report-only --json
opts into a report-only transaction. The ordinary command retains its broad
dirty-worktree refusal. The report still belongs to the authoritative primary
planning checkout; invoking from a clean linked lane does not change that owner.
The opt-in transaction requires the checked-out, unprotected planning branch,
clean material inputs and report, supported index entries, and no active Git
operation. It preserves unrelated staged blobs, partial staging, working bytes,
and untracked bytes. The canonical commit router uses git commit --only;
the transaction never stashes or resets operator work.
Material inputs
The shared recording/freshness manifest covers spec, plan, status-normalized tasks, individual WP definitions, mission metadata and package manifest, configured charter authority, local declarative mission/template/doctrine overrides, charter references and authority directories, and bundled authority content digests. Missing paths are recorded so their later creation invalidates analysis. WP lane/review fields use the canonical mutable-field vocabulary and are excluded from definition hashes. Runtime events, context-state and synthesis bookkeeping are excluded. Symlinks and external mutable org roots are refused.
In the documented make sync-packs layout, a fetched pack tree is an input
whose committed authority is its tracked sibling pin, not an indexed tree.
The pin-and-fetch ADR
describes this layout. For a registry-declared, in-repository root such as
packs/internal/, the transaction exempts ignored, untracked material only when
its sibling packs/internal.source.yaml is tracked, clean and not symlinked,
its subtree equals that repo-relative resolved root, and the canonical offline
check matches both committed pin digests and refuses in-tree symlinks.
This proves local content equality to the pin, not that its remote commit exists
or contains those bytes. Index/worktree dirt and canonical-charter checks are
never relaxed; a non-ignored, status-visible untracked tree still refuses.
The sibling-root and matching-subtree rules do not generally support registry
aliases, nested subdir roots or non-mirroring upstream layouts. These remain
fail-closed; #7194 owns the binding-contract decision. It is not permission to
broaden admission or treat ignored paths as clean. A changed tree, missing or
uncommitted pin, and unrelated ignored material still refuse. Refusals can name
the pin alongside pack files; dirty_paths can include a pin that fails the
trust check even when its own Git status is clean.
The report hashes the fetched tree's material bytes, not the pin file itself. A committed pin-only bump with unchanged tree bytes therefore does not by itself invalidate an already-qualified report, and the report does not identify its authorizing pin. This is the existing manifest contract, not a new pin-provenance attestation. Existing HEAD, whole-index, working-byte and material-input rechecks still detect cooperative changes during the recording transaction.
Outcomes and recovery
The JSON response distinguishes failed_before_write, written_uncommitted,
committed_unqualified, committed, and unchanged. Identical semantic report
content, analyzer and current inputs reuse an already-qualified report without
changing its bytes or HEAD. Missing or pending receipts cannot qualify that
no-op; fresh analysis must produce and verify a new report commit instead.
A disk write alone is never success.
Pre/post checks compare HEAD, material inputs, unrelated index entries, dirty
working bytes, report bytes, commit parent and changed paths. These checks detect
cooperative-writer races; they cannot lock out arbitrary external editors. The
net is deliberately broad: because the guard snapshots the entire index and the
full working tree (including untracked files) minus the report path, any
unrelated change observed during the transaction window — not only a HEAD or
index race — flips the outcome to committed_unqualified. No unrelated work is
lost in that case; the report is simply left freshness-rejected and a rerun
re-qualifies it.
Before writing, the transaction creates a pending receipt in the local Git directory. Only successful verification qualifies that receipt. Freshness for an opt-in report requires its receipt, exact report digest and a reachable verified commit. Thus a process crash or an unrelated concurrent change cannot unlock the mission merely because the retained report exists.
Receipts are local qualification evidence, not portable attestations. Copying the report into another clone does not qualify it there. Preserve concurrent work, inspect retained commits, reconcile and commit material inputs, then rerun analysis and recording in the destination checkout. No recovery action resets concurrent work automatically. A failed written report must be reviewed and committed or removed by its owner before retrying; the dirty-report guard remains.