codeArbiter 2.5.2: deep-review hard-gate hardening + enterprise docs

[2.5.2] — 2026-06-25

Deep-review (docs/reports/2026-06-24-root/) remediation, in two parts. The quick-kill batch is mechanical robustness, diagnosability, and hot-path hardening with no enforcement-behavior change (guard matrix, cold-install, and statusline render verified unchanged or byte-identical). The HARD-GATE batch closes real gaps in the crypto/secret commit gate and the append-only audit guards; each enforcement change shipped test-first (a RED test proving the gap, then the fix), with the full guard matrix, cold-install, migration backstop, and hook unit suites green.

Security

• Commit-time gates can no longer be bypassed by git commit <pathspec>. A git commit <path> records the worktree content of the named paths (bypassing the index), but the H-09b/H-10b crypto-secret gate and the H-14 migration gate scanned only the staged (--cached) diff — so an unstaged crypto/secret/migration change named as a pathspec committed with no recorded review. Both gates now union the worktree diff scoped to the named pathspecs (an unrelated worktree change elsewhere is not dragged in). The crypto/secret scan and the H-14 file-list read now also fail closed when git diff cannot be read (timeout/error) instead of silently passing. (appsec-001/002, reliability-003)
• Farm child commands no longer inherit dispatcher secrets. run() scrubs FARM_API_KEY and CLAUDE_CODE_OAUTH_TOKEN from the environment passed to every child (git, operator gate/setup/test, mutation) — the API key is used only by the in-process fetch. Least-privilege defense-in-depth; shrinks the blast radius of the operator-authored gate-command shell boundary (CodeQL js/shell-command-injection-from-environment #5, traced non-exploitable and dismissed).
• Two detection blind spots in the crypto/secret commit gate are closed. CRYPTO_RE did not match RC2 or Blowfish (both forbidden by security-controls.md), so a commit adding either passed the H-09b gate with no crypto-compliance review. SECRET_RE's leading word-boundary never fired when a secret keyword was the trailing segment of a compound identifier, so a hardcoded FARM_API_KEY = "..." committed clean past H-10b. Both now match. The outbound farm redactor and the commit-gate secret pattern are also pinned to a shared, CI-checked corpus (secret-detection-corpus.json) asserted against both, so they can no longer silently drift apart. (secrets-001/002, architecture-001, #132)
• The H-05 append-only audit-log guard no longer accepts an empty-old_string Edit. Because new.startswith("") is always true, an Edit with an empty old_string on overrides.log / triage.log / sprint-log.md slipped the append-only check entirely; it now blocks outright. The variable-indirection residual risk and the known truncation-spelling gaps (exec N>, >>>, process substitution) are now documented in security-controls.md so the policy matches the enforced scope. (migration-003, appsec-003, observability-005, #132)
• A session-boundary /ca:dev exit now closes the audit pair. When SessionStart clears a live dev marker (a prior session entered /ca:dev and ended without /ca:arbiter), it appends a synthetic DEV: exit line to overrides.log before removing the marker, so the audit trail no longer keeps an orphaned DEV: enter with no matching close. (observability-001, #133)

Fixed

• The task board can't be lost to a crashed write. taskwrite.py writes open-tasks.md atomically (temp file in the board's own directory + os.replace), so an interrupted write leaves the prior board intact. (migration-001)
• Farm dispatcher robustness + diagnosability. A per-command wall-clock timeout (FARM_GATE_TIMEOUT_MS, default 5m; git stays unbounded) kills a hung gate/setup/mutation child so a stuck command can no longer wedge a run and stall the final report; the worktree-cleanup finally is guarded against an early failure; plan validation emits named field errors instead of an opaque crash; a run-id correlates farm-results.jsonl lines and the report header. Response/parse shape guards turn malformed API or mutation-hook output into actionable errors instead of silent empties. (reliability-001/004, migration-004, observability-003, dx-001/002/003)
• ca-sandbox surfaces real failure causes. docker create/cp exit codes are checked and the failed-clone path captures a bounded slice of git stderr into the thrown error, so a failed sandbox build/clone no longer reports only a bare exit code. (reliability-002, observability-004)
• Task-board lib input guards. _taskboardlib.set_state/promote no longer raise or silently mutate state on an unexpected value; valid value sets are documented. (dx-004/005)
• Gate-pass markers are written atomically. migration-pass.py and security-pass.py write their pass markers through a temp file plus os.replace (shared _hooklib.write_text_atomic), so a crash mid-write can no longer leave a half-written marker that the backstop reads as an unrecognized digest and spuriously re-blocks the next commit. Fail-closed behavior is unchanged. (migration-002, #133)

Changed

• Hook hot-path and statusline render cost reduced (behavior-preserving). _hooklib caches the controls read (mtime-keyed, per ephemeral hook process) and precompiles its default path-globs at import; the statusline caches per-render state reads and its cost-ledger subsystem moved into a dedicated _ledgerlib.py. Verified: guard matrix 79/0, cold-install 134/0, and the statusline render byte-identical. (performance-001..005, architecture-005/007)
• Public-API header blocks added to _hooklib.py and _sloplib.py per the coding standard. (dx-007)
• Audit-guard path sets centralized in _hooklib (behavior-preserving). The append-only-log and ADR-decisions path patterns, previously triplicated inline across pre-write / pre-edit / pre-bash, now have a single definition (is_audit_log / AUDIT_LOG_NAMES, is_decisions_path / DECISIONS_DIR_RE), so adding an audit artifact touches one file instead of three. The detached-HEAD protected-tip check also resolves in one git show-ref spawn instead of three sequential git rev-parse calls, with the same block/allow decisions. (architecture-004, performance-006, #132, #133)

Tests

• Added integration/coverage for existing behavior with no source change: custom CI/deploy scope grammar, the H-12 governed-path reminder (incl. superseded-ADR), and validateRepoUrl scp double-colon rejection; plus a _ledgerlib suite. (coverage-003/004/005)

Documentation

• Full pre-release docs pass. Tightened the always-loaded orchestrator core (collapsed the duplicated non-negotiables, trimmed the register, made the lazy-load routers state one deterministic trigger-to-route surface) and reconciled the governance docs to the now-merged enforcement (the forbidden-crypto list, the secret-sweep pattern, and the audit-trail section that now names the automated session-cleanup DEV: exit write). Corrected stale references (/ca:arbiter no longer instructs a manual dev-exit line the hook already writes; auth-crypto-reviewer and the post-write reminder now list rc2/blowfish). The docs site gains an Enforcement & Security page and a complete Hooks reference documenting every hook (event, location, controls, and fail posture).

Released-at: 2026-06-25