# Operational Controls ## Locating the tools The tools live in the installed Zimster plugin, not in the user's project. Resolve the Zimster root as the parent containing the harness manifest (for Codex, `.codex-plugin/plugin.json`). Run tools with an absolute path while the working directory is the target repository. ## Durable run state An installed 0.7.2 runtime may encounter existing 0.7.0 Git-local state. Run `npm run state:migrate` once in that repository. The bounded migration preserves the checkpoint, budget, evidence, review, delegation, and dispatch stores; records observed dirty work; and writes `migration-0.7.0.json`. Missing counts, commands, failures, or approvals remain unknown or unavailable. Repeating the migration over unchanged inputs is a fixed point. ```text node /scripts/init-run.mjs \ --profile high-risk \ --harness codex \ --reason "public plugin compatibility" \ --triggers "more than one vertical slice,independent review" \ --commit-policy "commit at verified slice boundaries" ``` The command refuses to overwrite an existing run unless `--force` is explicit. Normal state is written beneath `git rev-parse --git-path zimster`. Use `--audit-path docs/.md` only for an explicit audit-mode contract. Zimster does not edit tracked `.gitignore` for normal state. The `--harness` value embeds the matching capability matrix in a machine-readable JSON block; omit it only when the harness is genuinely unverified. Standard and High-risk initialization also creates a run identity, lifecycle event stream, and machine-readable execution budget. Use `scripts/run-budget.mjs record` for measured events and `scripts/run-budget.mjs prove` to satisfy a proof-backed override. At a coherent slice boundary, create a bounded checkpoint with `scripts/phase-checkpoint.mjs create --input `. A continued physical context uses `phase-checkpoint.mjs resume`; logical ownership remains with the same root owner. Pass `--convergence-config ` to snapshot validated limits. A self-hosting candidate instead passes `--self-hosting-candidate `, `--accepted-policy-config `, and the independently known `--accepted-policy-sha256 `. Initialization rejects candidate-tree policy and records the accepted artifact identity in the bootstrap receipt. ## Delegation, routing, and convergence The normal review path is `review-control.mjs`: initialize one canonical seam, then record initial review, owner correction, same-reviewer correction recheck, and exact-head final-review events. The lifecycle is stored at `reviews/lifecycle.json` beneath the Git-local runtime. Reinitialization cannot reset an existing seam. Correction-recheck accounting uses that seam identity, not caller-provided scope, digest, attempt, reviewer, or candidate labels. If the first cycle still has load-bearing findings after its one recheck, the circuit breaker leads to owner strategy escalation. The root may explicitly admit one materially different, focused-proof-backed strategy under the same seam lineage. That replacement gets one new review, one correction, and one same-reviewer recheck. A second failed cycle becomes `BLOCKED`; it cannot be relabeled into a third cycle. This is one bounded strategy restart, not a review-budget reset. Completion requires the canonical approved final-review attempt and genuinely host-observed reviewer-result provenance; a review JSON or owner-recorded dispatch alone cannot authorize `CANDIDATE_COMPLETE`. Release authorization is a separate human boundary. A signed annotated release-evidence tag may authorize an exact-head final independent review whose record truthfully says that reviewer provenance is not host-authenticated. That release-specific result is `HUMAN_RELEASE_REVIEW_ACCEPTED`, not `CANDIDATE_COMPLETE`, and it does not rewrite runtime assurance state. Record delegation first with `delegation-record.mjs decide`. Only a selected decision may reach `model-routing.mjs propose`. Regenerate a dispatch-phase proposal and resolve it with current task, Git, configuration, harness, capability, catalog, and override evidence immediately before a v2 dispatch. The dispatch command revalidates those inputs and consumes the proposal once. It first creates an atomic proposal claim; concurrent dispatch/supersession loses that claim without spawning. After an interrupted claim, the owner runs `dispatch-record.mjs recover --proposal-id --claim-id ` to finalize an already recorded dispatch or release an uncommitted reservation. After delegated implementation, the owner records acceptance only after proof. Use `convergence.mjs decide --event --scope in-scope --sensitivity ordinary --reversible true --authorized true --deterministic true --locality local --metric ` after an ordinary deterministic failure. A `continue` record replaces repeated authorization; escalation or exhaustion stops the autonomous path. `HARD_BUDGET_EXHAUSTED`, `CIRCUIT_BREAKER`, `STRATEGY_ESCALATION_REQUIRES_OWNER`, and `BLOCKED` outrank any host goal or long-run continuation setting. ## Deterministic verification ```text npm run goal:verify npm run release:verify ``` The profile runner executes shell-free argv vectors, writes full logs and one receipt beneath the Git-local `zimster/verification` directory, stops on the first failure, and prints only a compact JSON summary. Consult existing tree-keyed evidence before repeating a broad command. A passing release profile also writes the portable release-facing `verification.json` named by `release_input` in the summary. It contains logical log IDs and hashes plus the exact `HUMAN_RELEASE_REVIEW_ACCEPTED` binding returned by the canonical release-review evaluator; it contains no machine-local log paths. Release-evidence creation and signed-tag verification re-evaluate the embedded semantic review against that same signed binding with the same evaluator. Canonical lifecycle and execution-budget mutations use the same portable owner lock. Acquisition records a PID, unique nonce, and timestamp. Live or ambiguous owners are never displaced; a demonstrably dead owner is reclaimed through an atomic quarantine claim. The small nonempty quarantine tombstone is retained so a late stale waiter cannot move a replacement live lock. Release removes the active lock only when its owner nonce still matches. Fresh incomplete metadata is given a bounded grace interval so another process cannot mistake an acquisition in progress for abandonment. ## Capability cache and postmortem ```text npm run capability:status -- --harness codex --host-version "" npm run postmortem ``` Capability status is scoped to one host. Expiry, version change, validator contradiction, a task changing that integration, or an explicit fresh-research request are the only refresh triggers. The postmortem is run-scoped and keeps incompatible token meters separate. ## Canonical command inventory ```text node /scripts/project-commands.mjs ``` The JSON output lists repository instructions, package scripts, Make/Just/Task entries, language tooling, and simple CI `run:` commands. It is an inventory, not a claim that every listed command is required. ## Complete change snapshot ```text node /scripts/change-snapshot.mjs \ --base \ --head \ --output /path/from/git-rev-parse/zimster/change-snapshot.md ``` The snapshot contains the committed branch range, staged and unstaged diffs, status, and every untracked file. Text files are embedded; large/binary files are represented by size and SHA-256. The index is unchanged. ## Reviewer checkout integrity Before a shell-capable reviewer runs its one named command: ```text node /scripts/review-integrity.mjs capture \ --base \ --head \ --review-files ,, ``` Afterward, pass the returned Git-local receipt path: ```text node /scripts/review-integrity.mjs verify \ --receipt ``` Any HEAD, index, tracked, untracked, or declared review-package mutation stops the review with `REVIEW_CHECKOUT_CHANGED`; an unchanged checkout reports `REVIEW_CHECKOUT_UNCHANGED`. These statuses never imply semantic approval. The guard reports exact affected files and never stages, repairs, resets, or discards them. Declared inputs may be absolute attachment or Git-local paths outside the worktree. ## Evidence receipts Initialize or record supplied evidence: ```text node /scripts/evidence.mjs init node /scripts/evidence.mjs record \ --kind test --scope focused --command "npm test" --exit-code 0 \ --test-discovery tests_executed --tests-passed 42 --tests-failed 0 \ --dependencies "src/cache.js,test/cache.test.js" ``` Run and record a command: ```text node /scripts/evidence.mjs run \ --kind test --scope affected --test-discovery tests_executed -- \ npm test ``` Check or find reusable proof: ```text node /scripts/evidence.mjs check --id node /scripts/evidence.mjs find \ --kind test --scope focused --command "npm test" ``` Receipts become stale when the complete working-tree fingerprint, normalized Node/npm/OS and declared host version, dependency declaration, or content fingerprints for declared input paths change. Supply the same `--host-version` when checking host-bound evidence. `--reuse` is allowed only for non-final work; final gates are rerun. New receipts may also carry `--requirement-ids`, `--establishes`, `--does-not-establish`, and `--environment-scope`. Use JSON arrays when a claim contains commas. This prevents a narrow native harness or fixture from being reported as broad compatibility proof. Receipts are `diagnostic` unless a trustworthy execution interface explicitly binds requirements and claims. `evidence record` is always manual and diagnostic; caller text such as `--source governed-run` cannot elevate it. `evidence run` records that its command was wrapper-governed, but its generic interface cannot authenticate arbitrary framework test counts or RED/GREEN meaning. Generic TDD-labelled runs therefore remain diagnostic with `tdd_compliance=unverified`. Only a future framework-specific interface that derives test identity, discovery, outcome, candidate binding, and ordered pair facts internally may establish a TDD compliance claim. Test-discovery values are `not_reached`, `zero_discovered`, `tests_executed`, and `unknown`. `unknown` and `not_reached` carry no counts; `zero_discovered` requires zero counts; `tests_executed` requires positive, internally consistent counts. An agent should supply exact counts rather than infer them from a zero exit code. ## Legacy dispatch records Dispatch v1 records created by Zimster 0.5 remain readable and updateable, but the v1 writer is closed. New dispatches require a selected delegation decision, an authoritative proposal, and a resolution linked through `--delegation-id`, `--proposal-id`, and `--resolution-id`. After the harness reports effective routing: ```text node /scripts/dispatch-record.mjs update \ --id --effective-model \ --effective-effort --agent-id ``` A fast role that actually used the parent model is marked with a warning. The v1 reader/update path remains for 0.5 compatibility. New work uses delegation, proposal, resolution, and v2 dispatch IDs described in `CONFIGURATION.md`. ## Requirement matrix and candidate completion Start from `templates/binding-requirements.json` and `templates/requirement-matrix.json`. Replace example SHAs with the exact candidate commit/tree and keep the matrix outside product history unless the project explicitly requires a committed audit artifact. ```text npm run assurance -- matrix \ --requirements \ --matrix \ --evidence npm run assurance -- complete \ --profile high-risk --owner-verified \ --load-bearing-review-obligations \ --requirements \ --matrix \ --evidence \ --reviews \ --review-package ``` The first command reports coverage and proof/claim blockers. The second also requires a clean current checkout and profile-appropriate review. Owner-inline inspection is `self_review`; Standard and High-risk need clean-context `independent_review` for the exact base/head, package ID, stable semantic-contract digest, and required lens set. The contract digest covers binding meaning, intended claims, implementation locations, and evidence scope; mutable receipt references, statuses, observations, and verification results are validated separately. High-risk obligation records bind the candidate head/tree to evidence references that match the exact requirement ID and exact established claim; Micro uses `--micro-eligibility` with all risk dimensions Low, no hard trigger or public contract, and candidate-bound deterministic proof references with the same exact requirement-and-claim linkage. Boolean eligibility or load-bearing switches are not accepted. Review unavailable produces `OWNER_VERIFIED_REVIEW_UNAVAILABLE` or another non-candidate state. Dispatch records are owner-recorded operational observations. Their agent, model, effort, and result bindings remain useful audit evidence, but they are not host-authenticated reviewer-result provenance. Until a supported host exposes a trustworthy result identity through an existing interface, Standard and High-risk completion fails closed as `OWNER_VERIFIED_REVIEW_UNAVAILABLE` even when the lifecycle, dispatch, review package, candidate, semantic contract, and review record agree exactly. ## Release controls ```text npm run version:bump -- --note "Release summary" npm run version:check npm run sync:codex:check npm run release:verify npm run postmortem ``` `version:bump` updates package/lock versions, three current primary manifests, Claude marketplace entry, changelog heading, and the generated Codex mirror. `version:check -- --tag v` additionally validates a release tag. ## Privacy All Git-local evidence, dispatch, snapshot, and run files remain on the local machine. Zimster contains no upload or telemetry mechanism. Pass `--no-receipt` or set `ZIMSTER_RECEIPTS=off` to run without recording receipt state. ## Diagnostics and failure semantics Normal progress quietly applies expected capability fallbacks. Use `npm run doctor -- --json` for the complete machine-readable matrix. Invalid packages, reviewer mutation, failed required commands, corrupted state, and unfulfilled required verification remain actionable errors. See `DIAGNOSTICS.md` for the full distinction and `SKILLS_ONLY.md` for the script-free path.