# Central Exact-Revision Verifier Ready Gate — Architecture and Operations (MC #105594) # Central Exact-Revision Verifier `ready` Gate Runbook — MC #105594 WP1 Status: publish-ready local draft for MC #105598 Scope: WP1 central `ready` transition only Current rollout: observe-only; enforcement disabled; no allowlist/canary approval ## 1. Authoritative evidence base This runbook is grounded only in these accepted inputs: - Plan: `/Users/makinja/system/specs/central-verifier-enforcement-105594-plan.md` - Accepted-byte manifest: `/Users/makinja/system/evidence/105594/ACCEPTED-BYTES-WP1.md` - Install/observe evidence: `/Users/makinja/system/evidence/105594/WP1-INSTALL-OBSERVE-EVIDENCE.md` - Independent Proveo PASS report: `/Users/makinja/system/evidence/105594/proveo-wp1-7f0423c6/REPORT.md` - Installed adapter source: `/Users/makinja/system/lib/cc-verifier-transition-gate.js` ## 2. Scope and coverage truth WP1 installs an authoritative central adapter for `tools/mc.js ready` only. It is additive to the existing legacy `ready` gates and is placed immediately before the authoritative `ready_for_review` status transaction, after earlier legacy validation. Covered by WP1: - Central `ready` transition adapter. - Exact task/revision verifier check through the trusted local verifier gate. - Central bounded audit record for `ready` outcomes. - Observe-mode behavior where findings audit but do not block. Not covered by WP1: - `done` integration. - Trusted session registration writer/reader. - Merge entry points. - Deploy entry points. - Any universal transition coverage claim. Coverage status for merge/deploy remains `not_observable`. WP1 must not be described as covering merge, deploy, or `done`. ## 3. Architecture The installed WP1 adapter is `/Users/makinja/system/lib/cc-verifier-transition-gate.js`. `tools/mc.js ready` calls the canonical exported `checkTransitionGate({ taskId, transition: 'ready' })` after unchanged legacy gates and immediately before the central status write. The adapter invokes the existing trusted verifier gate: ```text /Users/makinja/system/tools/cc-verifier-gate.ts check --task ``` Invocation properties: - Executed via `execFileSync` using `process.execPath`. - `shell:false`. - Fixed script path: `/Users/makinja/system/tools/cc-verifier-gate.ts`. - Fixed child `PATH`: `/usr/bin:/bin`. - Fixed child `HOME`: `/Users/makinja`. - No caller-supplied executable path, audit path, config path, timeout, output bound, evidence path, or verdict command. - No `CC_VERIFIER_*` values forwarded from the parent environment. - Timeout: `5000` ms. - Max output: `16384` bytes. - Stdin ignored; stdout/stderr bounded by child-process settings. The exact-revision semantics are delegated to unchanged `tools/cc-verifier-gate.ts`, which validates task/repository/revision/verdict/attestation according to the accepted plan. The central adapter only accepts the controlled verifier result and converts it into transition behavior. ## 4. Trust boundary The trust boundary is honest same-OS-user local protection. It is not cryptographic isolation from the account owner. The design protects central transition behavior against accidental caller drift, stale session hooks, caller-controlled paths, malformed task IDs, malformed verifier output, and infrastructure failures. It does not claim protection against a local account owner with authority to modify the installed system files, databases, state, or runtime. Session-local Claude hooks remain advisory/early-feedback only. The authoritative WP1 check is the central `ready` adapter in `tools/mc.js`. ## 5. Task identity and malformed-ID rejection The transition task identity must come from the explicit `ready` target and must be a safe positive numeric MC task ID. Accepted identity shape: - Decimal digits only. - `Number.isSafeInteger`. - Greater than zero. Rejected before actor resolution, task lookup, verifier call, token consumption, audit mutation, or DB mutation: - Empty value. - Zero or negative numbers. - Floats. - Scientific notation such as `1e3`. - Suffix/prefix text such as `1abc`. - Unsafe integers such as `9007199254740992`. - Whitespace-mutated explicit tokens such as ` 1`. Prompt/free-text IDs, stale markers, cwd guesses, titles, and unsafe integers cannot bind transition identity. ## 6. Exit and blocking semantics Only an intentional verifier gate exit code `2` can block, and only when the output is structurally valid for the same task and enforcing rollout mode. A blocking result requires all of the following: - Gate process exits `2`. - JSON parses successfully. - `finding.task_id` equals the explicit transition task ID. - `finding.ok === false`. - `decision.action === 'block'`. - `decision.enforced === true`. - `decision.mode` is `pilot-enforce` or `enforce-new`. Everything else fails open to unchanged legacy gates and is never represented as verifier PASS: - Exit `1` or any non-`0`/`2` exit. - Missing script or executable startup failure. - Timeout. - Signal. - Output larger than the bound. - Invalid JSON. - Mismatched task ID. - Exit `2` with invalid/mismatched/non-enforcing output. - Malformed decision shape. - Audit write failure. Observe mode cannot block. In observe, verifier findings are audited as `audit` or related metadata and the legacy transition path continues. ## 7. Audit schema, privacy, and confinement Canonical audit path: ```text /Users/makinja/system/state/cc-verifier-transition-gate-audit.jsonl ``` Each audit line is bounded JSONL metadata. The adapter records: - Timestamp `ts`. - Component: `cc-verifier-transition-gate`. - Transition, currently `ready`. - Task ID. - Outcome: `allow`, `audit`, `block`, or `infra_fail_open`. - Gate mode. - Reason code. - Bounded session provenance: safe `CLAUDE_SESSION_ID` or `pid-` fallback. Privacy exclusions: audit records must not store argv dumps, environment dumps, prompts, transcripts, tokens, cookies, credentials, arbitrary exception text, browser storage, or unrelated system contents. Confinement protections: - Audit root is fixed to `/Users/makinja/system/state`. - Target path must resolve inside the trusted root. - Root and parent ancestors must already exist and must not be symlinks. - Existing audit leaf must not be a symlink. - Leaf is opened append/create/write with `O_NOFOLLOW` when available. - File mode is `0600`. - Audit line bound is `2048` bytes. - Audit failure does not change the transition decision. ## 8. Force/actor token behavior and mutation order WP1 does not introduce a new unaudited bypass. Accepted behavior from the Proveo PASS report: - Force and actor effects are queued before the central verifier decision. - A valid central block leaves task status/history/outbox/evidence-ledger/token/bypass/verdict state unchanged. - Plain `--force`, authorized force token, actor warn override, and actor token paths do not bypass a valid central block. - Conditional compare-and-set prevents token reuse/races: if force/actor tokens change between validation and transaction, `ready` aborts with exit `2` before the authoritative ready write. - On allowed transition, deferred token consumption and bypass/verdict audits are written only after the ready transaction succeeds. Block-path rule: a valid central block must not mutate task status, history, outbox, evidence ledger, token state, bypass audit, or verdict audit. ## 9. Installed accepted bytes and validation evidence Accepted candidate: ```text 7f0423c6450fea0c19b0a20a2e2c0d2a53a1346f ``` Base: ```text 2a3c1e01e06b3f682c83b80d3f55d29ff0e5bef8 ``` Independent validation: - Validator: Angie Jones / Proveo, MC #105597. - Verdict: PASS, exact-SHA-bound. - Report: `/Users/makinja/system/evidence/105594/proveo-wp1-7f0423c6/REPORT.md`. - Report SHA-256: `b79fa8e0b6d1d3dffcc320d5e6a8d26cc27f26f92979e6511b0fa8120bcfb598`. Accepted installed file hashes: | Path | SHA-256 | |---|---| | `/Users/makinja/system/lib/cc-verifier-transition-gate.js` | `238f3cab5e13fa45bdc23bb94ee640ba5f9bad3e15269ed1db1dc255a14332a4` | | `/Users/makinja/system/tools/mc.js` | `d1b92b85b68b219e66d7765662e472755029ed3014f7787b24e63835ce02bc5d` | | `/Users/makinja/system/tests/cc-verifier-transition-gate.test.js` | `202ed37adc79a8a098b0cbef0282d43d90a8f9f438bb4f8b2a42dee0564775e5` | Pre-install backup: ```text /Users/makinja/system/evidence/105594/preinstall-backup-20260714T013841Z ``` Backup contents recorded: - `tools-mc.js` SHA-256: `897bbf36527402a50c9620af316e3c7ed5e1700a472023105ae7cc43dd11df7b`. - `lib/cc-verifier-transition-gate.js`: absent before install. - `tests/cc-verifier-transition-gate.test.js`: absent before install. Post-install checks recorded in the accepted install evidence: - Node syntax checks: PASS for all three installed files. - Focused central transition suite: `21/21 PASS`. - Existing verifier gate suite: `57/57 PASS`. - `git diff --check` on installed target paths: PASS. - `tools/cc-verifier-gate.ts` was not changed. - Rollout remained `mode:"observe"`, `enforcement:"disabled"`, `gate_rollout_mode:"observe"`. Observe-only audit result: ```json {"outcome":"audit","blocked":false,"reason":"stale_revision","mode":"observe"} ``` Recorded at `2026-07-14T01:39:01.442Z` in: ```text /Users/makinja/system/state/cc-verifier-transition-gate-audit.jsonl ``` That observe probe did not attempt or mutate a real MC transition. ## 10. Current rollout and phase gate Current rollout state: - Observe mode only. - Enforcement disabled. - No allowlist/canary approval. - No `pilot-enforce` canary is approved. - Global `enforce-new` is disabled. Next phase gate: 1. This documentation must exist. 2. Explicit CEO approval is required before one newly created `pilot-enforce` canary may be configured. 3. The canary must be a newly created canary MC, not a historical task. 4. Global `enforce-new` requires a separate plan and separate approval. Install does not equal canary. Install does not equal enforcement. Observe audit does not equal blocking coverage. ## 11. Operator checks: safe/read-only commands These commands are read-only checks against installed files and evidence. They do not run a real MC transition. Verify installed hashes: ```bash shasum -a 256 \ /Users/makinja/system/lib/cc-verifier-transition-gate.js \ /Users/makinja/system/tools/mc.js \ /Users/makinja/system/tests/cc-verifier-transition-gate.test.js ``` Expected hashes are listed in section 9. Check syntax only: ```bash node --check /Users/makinja/system/lib/cc-verifier-transition-gate.js node --check /Users/makinja/system/tools/mc.js node --check /Users/makinja/system/tests/cc-verifier-transition-gate.test.js ``` Inspect rollout/audit evidence without mutating transitions: ```bash tail -n 20 /Users/makinja/system/state/cc-verifier-transition-gate-audit.jsonl ``` Run focused test files only if disposable fixtures remain acceptable for the session: ```bash cd /Users/makinja/system node --test tests/cc-verifier-transition-gate.test.js node --test tests/cc-verifier-gate.test.js ``` Do not use `mc.js ready ` as an operator check unless an explicitly approved disposable canary has been created for that purpose. ## 12. Troubleshooting without mutating real MC tasks If a `ready` transition unexpectedly does not block: 1. Confirm rollout mode is still observe. Observe findings cannot block. 2. Inspect the central audit JSONL for `outcome`, `reason`, and `gate_mode`. 3. Confirm the task ID was a strict safe numeric ID. 4. Confirm any block was exit `2` with same-task enforcing JSON; otherwise the adapter must fail open. 5. Confirm the legacy gates still ran and produced their normal behavior. If audit shows `infra_fail_open`: - Treat it as infrastructure warning metadata only. - Do not call it verifier PASS. - Check for missing script, timeout, malformed/oversized output, invalid decision shape, or audit path safety issues. - Continue to rely on unchanged legacy gates until the infrastructure issue is resolved and validated. If audit writes stop: - Check that `/Users/makinja/system/state` exists, is a real directory, and is not a symlink. - Check that `/Users/makinja/system/state/cc-verifier-transition-gate-audit.jsonl` is not a symlink. - Do not redirect audits to arbitrary paths. For transition behavior tests, use only disposable databases/temp roots or the existing focused test suite. Do not mutate production MC tasks during troubleshooting. ## 13. Rollback instructions Rollback requires explicit approval. Do not perform rollback merely by reading this runbook. Approved rollback target behavior: - Keep rollout observe. - Keep allowlist empty. - Preserve historical audits. - Restore legacy MC behavior by restoring the backed-up `tools/mc.js`. - Remove the two previously absent new files only if rollback is explicitly approved. Backup path: ```text /Users/makinja/system/evidence/105594/preinstall-backup-20260714T013841Z ``` Rollback file actions after explicit approval: 1. Restore backed-up `tools/mc.js` from the backup path. 2. Remove `/Users/makinja/system/lib/cc-verifier-transition-gate.js` only if adapter removal is part of the approved rollback. 3. Remove `/Users/makinja/system/tests/cc-verifier-transition-gate.test.js` only if test-file removal is part of the approved rollback. 4. Do not delete `/Users/makinja/system/state/cc-verifier-transition-gate-audit.jsonl`. 5. Do not enable canary or global enforcement as part of rollback. Post-rollback verification should use read-only hash/syntax checks and should not run a real transition. ## 14. Explicit non-actions This runbook does not approve or perform any of the following: - Publishing to BookStack. - Editing rollout configuration. - Enabling `pilot-enforce`. - Enabling `enforce-new`. - Creating or running a real canary transition. - Running `mc.js ready` against a real production MC task. - Sending Slack. - Restarting processes. - Claiming `done`, merge, or deploy coverage.