Skip to main content

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:

/Users/makinja/system/tools/cc-verifier-gate.ts check --task <numeric-id>

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:

/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-<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:

7f0423c6450fea0c19b0a20a2e2c0d2a53a1346f

Base:

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:

/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:

{"outcome":"audit","blocked":false,"reason":"stale_revision","mode":"observe"}

Recorded at 2026-07-14T01:39:01.442Z in:

/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:

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:

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:

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:

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 <real-task> 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:

/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.

No comments to display

Back to top