@lannguyensi/harness 0.44.0 → 0.45.0

package/CHANGELOG.md

@@ -7,6 +7,1219 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.45.0] - 2026-08-19
+
+### Internal
+
+- The 4 grandfathered reverse-import exemptions (duration, extract,
+  expand-home, ledger-record) recorded as known debt in 0.44.0 are closed:
+  the utils moved to `src/io/` and the dependency-cruiser exemptions are
+  deleted (slice 4 of the structural-concentration work, task 61a37b25).
+  `src/io` stays deliberately unconstrained; a follow-up considers an
+  io-no-upward-imports rule.
+- `src/policy-packs/builtin/understanding-before-execution-runtime.ts`
+  (formerly a single monolith) is now a 9-line re-export shim over 7
+  concern-scoped siblings under `understanding-before-execution/`
+  (`ledger.ts`, `markers.ts`, `persisted-reports.ts`, `lifecycle.ts`,
+  `task-markers.ts`, `post-tool-use-boundary.ts`, `active-claim.ts`),
+  composed by `index.ts` (slice 2 of the structural-concentration work,
+  task `348a4d42`). Pure move: every existing import of the old path
+  (hook-pre-tool-use.ts, hook-codex-pre-tool-use.ts,
+  cli/approve/understanding.ts, tests, etc.) keeps working unchanged.
+  `safeJsonParse` (module-private in the monolith) is now exported from
+  `persisted-reports.ts` so `markers.ts` can import it cross-file, but is
+  deliberately NOT re-exported from the shim's public surface (pinned by
+  `tests/policy-packs/ube-export-surface.test.ts`); a follow-up considers
+  moving it into `src/io/`.
+- `approval_lifecycle.expire_on_bash_match`'s shipped `SOLO_TEMPLATE` /
+  `TEAM_TEMPLATE` / `FULL_TEMPLATE` regexes stay `^`-anchored
+  (`^gh pr (merge|close)\b`, `^git push origin (master|main)\b`) — no
+  functional change from the last release (task `fb80b5bb`). A same-task
+  first attempt widened both patterns to `\b`-scoped/un-anchored to close
+  a measured fail-open gap (a boundary command behind `cd <dir> &&`, an
+  env-var prefix, a subshell, or an inserted flag never expired the
+  marker); a follow-up review measured that widening end-to-end against
+  the real PostToolUse hook and found it made things worse: the
+  `harness approve understanding <<'RPT' ... RPT` flow became
+  self-revoking (a report body that legitimately quotes a boundary
+  command as part of the plan expired its own freshly-written marker,
+  an operator-only recovery), plus at least 8 everyday false positives
+  observed during the round-2 review probe (corpus not retained;
+  `grep`/`echo`/commit-message text) and at least 20 residual fail-open
+  forms still observed uncaught in that same probe. A scoped
+  `isEscapeCommand` exemption for the
+  approve-heredoc was considered and rejected: it would import a
+  documented divergence class (4 prior halts) into a new consumer.
+  Reverted `src/cli/init/profiles.ts`, `src/cli/init/templates.ts`,
+  `docs/examples/full-manifest.yaml`, and regenerated
+  `docs/examples/full-manifest.expected.yaml` (verified byte-for-byte
+  against the real `describe()` output) back to the shipped patterns.
+  New docs: "expire_on_bash_match: start-anchored, with a documented
+  fail-open limitation" in
+  `docs/policy-packs/understanding-before-execution.md`, naming the full
+  set of known fail-open forms (including `git push --force/-u origin
+  main`, `git push origin HEAD:main`, `git -c x=y push`, `gh --repo o/r
+  pr merge`, whitespace variants), the safety-net role of `max_age`
+  (`1h` SOLO / `4h` TEAM+FULL), and a separate known gap: the interactive
+  custom profile (`harness init --interactive`, `composeCustom()` in
+  `src/cli/init/composer.ts`) sets `expire_on_tool_match` and `max_age`
+  but never sets `expire_on_bash_match` at all — tracked as a follow-up
+  (task `90eae119-cb77-4941-975c-7d2930e685d8`), not fixed here. Updated
+  `tests/cli/init-full-template-pins.test.ts`:
+  restored the "expire_on_bash_match is a separate anchored family,
+  untouched" guard's original `^`-anchored assertions and added a
+  trailing-`\b` structural check that the pre-fb80b5bb version of this
+  test never had (a round-2 mutation probe proved its absence would go
+  undetected); added an "anchored-pattern behavior" describe block
+  pinning positive matches, the documented known-miss forms, and
+  negative false-positive-avoidance forms (including the approve-heredoc
+  shape) against the actual shipped regexes; hoisted the `bashMatchers`
+  helper (duplicated across two describe blocks during this task's first
+  attempt on this branch — master carried only one definition) to module
+  scope. Mutation-verified: removing the `^` anchor from a pattern turns
+  both the structural guard and the false-positive-avoidance pins red;
+  removing only the trailing `\b` turns solely the new end-anchor check
+  red — both restored to green afterward. Round 2b: the "separate
+  anchored family, untouched" guard gained a whole-value
+  `toEqual([...])` pin over the two literals (the pre-existing
+  per-pattern shape checks stayed green under a widening such as
+  `(master|main)` -> `(master|main|develop)`); the known-miss `it.each`
+  array gained the 4 forms the docs already named but the array did not
+  yet pin (`git -c user.name=x push origin main`, `git push origin
+  HEAD:main`, `gh --repo owner/repo pr merge 42`, doubled whitespace);
+  and `tests/cli/init-composer.test.ts` gained a pin for the
+  interactive-composer gap named above (task
+  `90eae119-cb77-4941-975c-7d2930e685d8`).
+
+### Added
+
+- `generateSettingsWithWarnings` (`src/cli/apply/generate-settings.ts`)
+  gains `projectSigningKeyEnv`, projecting the harness's own approval-
+  signing key path (`<generatedDir>/.approval-signing.key`,
+  `signingKeyPathFor`) as the `SOLUTION_VERDICT_SIGNING_KEY` env on the
+  `tools.mcp[grounding-mcp]` entry, exactly mirroring the existing
+  `EVIDENCE_LEDGER_DB` / `projectGroundingEnv` projection (task
+  `03a917fd`/H1, agent-grounding `9b6c4beb` comment 2, Option 2): only
+  the fully-resolved, absolute key PATH is projected, never the key
+  bytes; an operator-declared `env.SOLUTION_VERDICT_SIGNING_KEY` on the
+  entry wins; no projection fires without a grounding-mcp entry or
+  without the new `GenerateSettingsExtras.generatedDir` passed in
+  (there is no safe default to guess). Wiring the real, resolved
+  `generatedDir` through `harness apply`'s and `harness init`'s call
+  sites (task `03a917fd`/H1b) is now live: `generate-opencode-config.ts`'s
+  `generateOpencodeConfig` gained the matching `generatedDir` extra and
+  `apply.ts`'s `buildExpectedFiles` threads its own resolved
+  `generatedDir` into both that call and its `generateSettingsWithWarnings`
+  call; `init/interactive.ts`'s `loadDesiredMcpServers` — the function
+  that feeds the REAL `claude mcp` CLI registration (`ensureMcpServers`)
+  — now also projects `SOLUTION_VERDICT_SIGNING_KEY`, mirroring
+  `EVIDENCE_LEDGER_DB` there; `adopt/derive.ts`'s `manifestMcpProjection`
+  gained the matching manifest-side mirror so an apply→adopt cycle does
+  not report phantom drift on grounding-mcp for this key either. One
+  caveat carried over from `EVIDENCE_LEDGER_DB`/T-002: settings.json's
+  `mcpServers` block (and therefore `apply.ts`'s
+  `generateSettingsWithWarnings` call specifically) is dead at runtime —
+  Claude Code's real MCP registration goes exclusively through the
+  `claude mcp` CLI path in `interactive.ts`, so the settings.json branch's
+  `generatedDir` threading is wired for symmetry/future-proofing but has
+  no independently observable effect today.
+- Review round H1 fix-round (task `03a917fd`): `generate-settings.ts`
+  gains `buildDesiredMcpServers(manifest, {homeDir, generatedDir})`, a
+  single choke-point wrapper around `buildMcpServers` ->
+  `projectGroundingEnv` -> `projectSigningKeyEnv`. Every producer of the
+  Claude-Code-shaped MCP server-spec map — `harness apply`'s
+  settings.json generation, `init --interactive`'s `claude mcp` CLI
+  wiring, `harness doctor`'s registration-health check, and the opencode
+  config generator — now calls this one function instead of hand-rolling
+  the same three-call sequence, closing the gap where doctor's "not
+  registered, run this `claude mcp add-json ...`" hint for grounding-mcp
+  silently omitted `SOLUTION_VERDICT_SIGNING_KEY` (3 of the 4 producers
+  called `projectSigningKeyEnv`, doctor did not). `projectSigningKeyEnv`
+  also normalizes a relative or literal-tilde `generatedDir`
+  (`expandHome` + `path.resolve`, mirroring `groundingLedgerEnvValue`'s
+  idiom for `EVIDENCE_LEDGER_DB`) into an absolute path instead of
+  silently under-projecting. `docs/ARCHITECTURE.md`'s `grounding:`
+  wiring-status note and `GenerateSettingsResult.mcpServers`'s doc
+  comment now name both projections.
+- `harness doctor` gains an on-demand toolchain-parity section (task
+  `13919613`, commit `16d47941`), the doctor companion to `harness session-start
+  toolchain-parity`: reuses that command's Collector/Comparator core
+  (`collectLocalSnapshot`, `compareToPeer`, `parseSnapshotJson`,
+  `formatSnapshotAge`, the real collectors) verbatim — no comparison
+  logic is duplicated — to compare the current live toolchain against
+  whatever peer snapshots already exist in `machine_state_dir`, without
+  ever writing a snapshot file or a ledger fact. Present only when
+  `toolchain_parity.enabled: true` (omitted otherwise), following the
+  same optional-section convention as `npmGlobalBin`/the claude-code MCP
+  registration check. `--shallow` skips the live collection (no
+  `node`/`npm` spawn), mirroring those same checks. Drift always rolls
+  into `warningCount`, never `errorCount` — advisory only, not a gate,
+  same contract as the SessionStart producer. Documented in
+  `docs/CLI.md`.
+- `harness session-start toolchain-parity` hardening round (task
+  `c1b5ade5`, follow-up to the initial 690fba7c drop): (1) a lossy
+  `sanitizeProfileName` advisory — a configured `profile` that is not
+  filename-safe now logs a warning, plus a stronger WARNING when the
+  sanitized filename collides with an existing snapshot for a DIFFERENT
+  profile (this run's write is about to overwrite it); (2) defensive
+  try/catch around the `resolveSession` and `writeLedger` call sites — a
+  throw/rejection from either now degrades to a note + exit 0 instead of
+  an unhandled throw/rejection, same as every other failure path in this
+  producer (deliberately NOT applied to `collectLocalSnapshot`, which the
+  hermetic-spawn-guard contract requires to propagate uncaught); (3) a
+  new optional `toolchain_parity.stale_after_days` manifest knob
+  (`src/schema/toolchain-parity.ts`, default off) — a peer snapshot older
+  than the threshold gets an extra advisory note without being counted
+  as drift. Advisory character is unchanged throughout: every PRODUCTION
+  path exits 0 (an injected collector that throws propagates by the
+  hermetic-spawn-guard contract, corrected wording — see Round 2b below),
+  and `ok`/drift comparator semantics are untouched. Also
+  corrects the `toolchain-parity` hook's `budget_ms: 10000` comment in
+  `src/cli/init/templates.ts`, which previously described only the
+  parallel node/npm collection and missed that the ledger write runs
+  SEQUENTIALLY after with its own ~5s default timeout floor (worst case
+  ~9s, not the "comfortable" sub-5s headroom the old comment claimed).
+  **Round 2 (review fix-round, same task):** (a) the collision-warning
+  note and the stale-peer note both interpolated an untrusted,
+  cross-machine-synced `profile` field into the stderr stream
+  unsanitized — a crafted profile string (embedded newline plus
+  note-prefix-shaped text) could forge a standalone parity line;
+  both sites now wrap the value in `sanitizeProfileName(...)`, same as
+  the pre-existing filename-label site (the two "ok against"/"drift:N
+  against" sibling notes stay unsanitized — a known, separate gap,
+  scoped out of this round); (b) the collision check was one-sided — it
+  only ran on the lossy machine's own run, so a filename-safe machine
+  silently overwrote a lossy peer's snapshot with no signal and that
+  peer silently dropping out of `peersCompared`; the existing-file read
+  now runs on every invocation, and only the "not filename-safe" note
+  stays scoped to the lossy case; (c) a session resolver that throws
+  while the stdin event DID carry a `session_id` used to still report
+  `sessionSource: "stdin"` even though `sessionId` had actually fallen
+  back to `"default"` — misrepresenting the ledger fact's provenance and
+  suppressing the AC5 "resolved to default" warning; a `resolverThrew`
+  flag now short-circuits `sessionSource` to `"default"` whenever the
+  catch fires; (d) `stale_after_days` gained `.finite()` — `.positive()`
+  alone accepted `Infinity` (reachable via YAML `.inf`), silently turning
+  the staleness check into a permanent no-op. The try/catch this round
+  removes was around `resolveManifestLedgerWriter`: unlike the two
+  real I/O/spawn-adjacent seams it sat next to (`resolveSession`,
+  `writeLedger`), that call has no throw path at all — it is a pure
+  function over an already-validated `manifest` (a plain array `.find`
+  plus a string split underneath) — so the catch was dead, untested code
+  (round-1 review finding) and is removed rather than built out into a
+  fake seam; the two genuine I/O sites stay caught.
+  **Round 2b (second review fix-round, same task, `c1b5ade5`):** R2's
+  review, re-run against the R2 fix, proved the log-injection class was
+  still open across roughly ten call sites in three vector families — R2
+  had sanitized only the collision-warning and stale-peer notes, leaving
+  every other note() call reachable by untrusted content: the "ok
+  against"/"drift:N against" notes (raw `comparison.peerProfile`, never
+  wrapped by R2 at all), every individual drift message from
+  `compareToPeer` (untrusted `peer.node`/`owKitVersion`/npm/mcp names,
+  reproduced against a real forged `parity:unparseable-peer:INJECTED` tag),
+  and two of the three peer-file-read notes (the corrupt-file and
+  unreadable-file lines used a raw `fileName`, while only the third,
+  `peerLabel`, was sanitized). Fix: moved the CR/LF strip to the shared
+  `note()` closure itself — `msg.replace(/[\r\n]/g, " ")`, once, before
+  every stderr write — closing the whole class at its one choke point
+  instead of requiring every present and future call site to remember its
+  own sanitization. With injection protection centralized in `note()`, the
+  three R2-added `sanitizeProfileName(...)` display wraps (collision note,
+  unparseable-peer `peerLabel`, stale-peer note) are reverted back to the
+  raw field: `sanitizeProfileName` is a FILENAME escaper (documented at
+  its definition) that also lossily mangles a legitimate non-ASCII profile
+  name, so reusing it for display was both redundant once `note()`
+  protects the line and a correctness regression — the stale-peer note's
+  sanitized spelling could differ from the same peer's raw spelling on the
+  "ok against" line two lines above it, within the SAME run. `note()`
+  itself is now the only site responsible for log-injection safety; the
+  filename path (`ownFileName`/`writeOwnSnapshot`) is unaffected and still
+  goes through `sanitizeProfileName`. Also, three unrelated LOW findings
+  from the same review pass: (a) the collision-warning note now appends a
+  one-line remediation hint ("...set a distinct `toolchain_parity.profile`
+  on one of the machines"); (b) the collision pre-read's previously-bare
+  `catch {}` is narrowed to re-note any error whose `code` is not `ENOENT`
+  (a genuinely missing file is still silent — EACCES/EISDIR/etc. is now a
+  one-line note that the collision check silently did not run, rather than
+  vanishing into the same branch as "no existing file"); (c) the ledger
+  write's `result.reason ?? "unknown error"` fallback is kept, with a
+  comment explaining why (`AddLedgerFactResult`'s `!ok` arm types `reason`
+  as non-optional, so the fallback is unreachable through any type-checked
+  caller — but unlike the pure `resolveManifestLedgerWriter` call the R2
+  catch-removal above targeted, `writeLedger` is an injectable *public*
+  seam a JS-level or otherwise untyped caller can reach with a malformed
+  return value at runtime, so this one stays). New/updated tests: a
+  note()-level pin (an arbitrary thrown message with an embedded newline
+  produces no second stderr line), dedicated regressions for the three
+  reviewer-reproduced vectors (hostile `peer.profile`, hostile `peer.node`
+  in a drift message, hostile peer filename with an embedded newline —
+  each asserted against the exact greppable prefix it tried to forge), a
+  negative control pinning that the collision check does NOT fire when a
+  machine's own profile matches its own existing snapshot (guards a
+  "warn-always" mutation), an EISDIR case for the narrowed catch, and a
+  label-coherence test showing one peer's name renders identically on the
+  "ok against" and stale-peer lines in the same run.
+
+### Security
+
+- No functional change: the known fail-open limitation of
+  `approval_lifecycle.expire_on_bash_match` is now documented — see the
+  Internal entry above (task `fb80b5bb`) and
+  `docs/policy-packs/understanding-before-execution.md`.
+- **SECURITY: `harness session-start toolchain-parity`'s stderr log-injection
+  class is closed, across every call site, not just the two R2 patched**
+  (task `c1b5ade5` R2b). The machine-state directory is populated
+  cross-machine by `agent-memory-sync`, so a peer's snapshot content
+  (`profile`, `node`, `owKitVersion`, npm/mcp package names) and even a
+  peer's raw filename are all attacker-influenced input; a crafted value
+  containing an embedded newline plus note-prefix-shaped text could forge
+  a standalone, fully fake `harness session-start toolchain-parity: ...`
+  line in stderr — including the exact greppable
+  `parity:unparseable-peer:<label>` / `toolchain-parity:ok` /
+  `toolchain-parity:drift:<n>` tags an operator or `harness audit` would
+  grep for. R2 (same task, prior round) sanitized only 2 of the roughly 10
+  reachable sites (the collision-warning and stale-peer notes); this round
+  closes the rest — the "ok against"/"drift:N against" notes, every
+  individual `compareToPeer` drift message, and the two previously-raw
+  peer-file-read notes — by stripping CR/LF once, in the shared `note()`
+  closure all of these funnel through, rather than continuing to require a
+  wrap at each call site. The pre-existing 876/878-area peer-unreadable and
+  peer-corrupt notes (raw `fileName`) are covered by this same fix; there
+  is no remaining open site in this class and no follow-up is needed.
+- **The `solution-acceptance` policy pack's verdict marker is now HMAC-signed, reusing the SAME `signMarker` / `verifyMarkerSignature` primitive the understanding-gate approval marker (and its branch-protection twin) shipped in v0.41.0 (task `f9485cc7`) — this is the "solution-acceptance's verdict marker remains unsigned" residual that entry's own follow-up note tracked separately** (task `c7c3f606`, pattern + exemplar). `evaluateGate` (`src/policy-packs/builtin/solution-acceptance-runtime.ts`) now verifies the verdict's signature BEFORE trusting `ready`/`head` at all: the signed payload mirrors the approval marker's `(approvedAt, approvedBy, reportContentHash)` shape onto the verdict's own fields — `timestamp` plays `approvedAt`, `source` plays `approvedBy`, and a sha256 content hash of `head`/`ready`/`confidence`/`blockers` plays `reportContentHash` — so tampering ANY of those fields post-signing invalidates the signature, not just editing `signature` itself. `harness pack hook solution-acceptance` REJECTS a verdict with a missing or invalid signature: `allowed:false`, same as no verdict at all, but with a distinct `forged/unsigned solution-acceptance verdict rejected` reason (new `GateResult.forged` field) so an operator/auditor can tell an active forgery attempt (or a not-yet-signing producer) apart from the routine "no verdict yet" / "not ready yet" cases. **Back-compat is strict, no migration window**, the SAME trade-off f9485cc7 made: a verdict with no `signature` field is rejected exactly like a forgery.
+  - **Honest residual (read before assuming more than it delivers): this is CONSUMER-SIDE ONLY.** Unlike the understanding-gate marker, harness does not WRITE the solution-acceptance verdict — the producer is `@lannguyensi/grounding-mcp`, a separate package/repo. This task shipped the pattern + exemplar (`signVerdict` / `verifyVerdictSignature`, exported from `solution-acceptance-runtime.ts`, are the reusable pair a producer-side change mirrors) but **no currently-released grounding-mcp version signs its output**. Concretely, until a matching producer release ships (a tracked cross-repo follow-up): every verdict this consumer reads is "unsigned" and the completion-gate denies it UNIVERSALLY, even a perfectly legitimate `ready:true` verdict at the correct HEAD; re-running `solution_evaluate` does not recover from this (the new verdict is unsigned too); `harness pause`, or temporarily disabling the pack, is the operator's interim recourse. grounding-mcp's own `solution_gate` does not yet enforce this signature either — only this harness consumer does, until the producer-side change closes that asymmetry. `docs/policy-packs/solution-acceptance.md` "Marker signing" spells this out in full. The persisted-report approval path (task `7402301d`) and the write-guard's glob-every-segment / interpreter-runtime-path-construction residual are UNCHANGED by this task and remain separately tracked.
+  - New tests: `tests/policy-packs/solution-acceptance-runtime.test.ts` (sign/verify round-trip, forged/unsigned rejection distinct from no-marker, hand-written-marker-without-key forgery regression, one-tampered-signature-byte regression, tampering `ready` without touching `signature`, cross-id signature-replay rejection, signing-key-I/O-failure-not-classified-as-forged, and the golden-fixture tests updated to assert the real UNSIGNED 0.3.2/0.5.0 producer markers are now rejected while a locally-signed copy of the same content still gates correctly) and `tests/cli/pack-hook-solution-acceptance.test.ts` (the same forgery/tamper regressions exercised through the real hook entrypoint).
+- **The `solution-acceptance` policy pack's verdict marker is now HMAC-signed, reusing the SAME `signMarker` / `verifyMarkerSignature` primitive the understanding-gate approval marker (and its branch-protection twin) shipped in v0.41.0 (task `f9485cc7`) — this is the "solution-acceptance's verdict marker remains unsigned" residual that entry's own follow-up note tracked separately** (task `c7c3f606`, pattern + exemplar). `evaluateGate` (`src/policy-packs/builtin/solution-acceptance-runtime.ts`) now verifies the verdict's signature BEFORE trusting `ready`/`head` at all: the signed payload mirrors the approval marker's `(approvedAt, approvedBy, reportContentHash)` shape onto the verdict's own fields — `timestamp` plays `approvedAt`, `source` plays `approvedBy`, and a sha256 content hash of `head`/`ready`/`confidence`/`blockers` plays `reportContentHash` — so tampering ANY of those fields post-signing invalidates the signature, not just editing `signature` itself. `harness pack hook solution-acceptance` REJECTS a verdict with a missing or invalid signature: `allowed:false`, same as no verdict at all, but with a distinct `forged/unsigned solution-acceptance verdict rejected` reason (new `GateResult.forged` field) so an operator/auditor can tell an active forgery attempt (or a not-yet-signing producer) apart from the routine "no verdict yet" / "not ready yet" cases. **Back-compat is strict, no migration window**, the SAME strict no-grace-period POLICY f9485cc7 made: a verdict with no `signature` field is rejected exactly like a forgery. (The RECOVERY shape differs, though — see the honest-residual bullet below.)
+  - **Fix-round-2 (review R1 HIGH): cross-id replay via a verbatim file copy is now closed.** `verifyVerdictSignature` previously derived the HMAC markerId from `verdict.id` — a field read back out of the marker BODY, which an attacker controls simply by copying a validly-signed verdict file onto a DIFFERENT id's marker path (the body's `id` travels with the copy, unchanged). `evaluateGate` never compared `verdict.id` against the id it was actually checking, so a verbatim copy of one task's ready verdict onto a second task's path passed verification and ALLOWED the second task to complete. `verifyVerdictSignature` now takes the CALLER's id explicitly and derives the markerId from it, matching the load-bearing invariant `approval-signing.ts` already documents ("verification always recomputes the HMAC using the id the caller is checking, NOT one read back out of the marker body"); `evaluateGate` additionally rejects outright when `verdict.id !== id` (belt-and-braces — the signed payload does not cover `id` itself, so this catches a post-signing edit to that one field that the markerId fix alone would not).
+  - **Fix-round-2 (review R1 LOW): the hook's STDERR diagnostic now consumes `GateResult.forged`.** `harness pack hook solution-acceptance` appends a short `[audit: forged/unsigned verdict marker rejected]` tag to its operator-facing diagnostic line specifically when `forged: true`, mirroring the `markerForgedNote` audit-tag pattern already used by `hook-pre-tool-use.ts` / `hook-branch-protection.ts` — previously `GateResult.forged` was computed but never read by any production code path.
+  - **Fix-round-2 (review R1 LOW): a verdict missing `timestamp` or `source` is no longer misclassified as forged.** Those two fields map onto `verifyMarkerSignature`'s `approvedAt` / `approvedBy`; a blank one is a legitimately malformed marker (e.g. a producer bug), not necessarily an active forgery attempt. `evaluateGate` now carves the `"missing approvedAt"` / `"missing approvedBy"` verification reasons out of the generic forged bucket — fail-closed (`allowed: false`) either way, but `forged: false`, the same shape as the existing signing-key-unavailable carve-out.
+  - **Fix-round-2b (review R2 MED, audit-fidelity): the missing-timestamp/missing-source carve-out above is now scoped to verdicts with NO signature at all.** As shipped, the carve-out fired on the verification REASON string alone, regardless of whether the verdict actually carried `alg`/`signature` fields — so a forger who mutated an otherwise VALIDLY-SIGNED verdict to blank its `timestamp` (or `source`) suppressed the `forged: true` audit tag entirely: `verifyMarkerSignature` checks `approvedAt`/`approvedBy` for blankness BEFORE ever comparing the signature, so the blanked-but-signed marker hit the same `"missing approvedAt"` reason as a genuinely never-signed one and inherited its `forged: false` classification. The block itself still held either way (`allowed: false` throughout — this was never a bypass), but the audit trail lied about what happened. `evaluateGate` now additionally requires `verdict.signature === undefined && verdict.alg === undefined` before granting the carve-out; a verdict that carries `alg`/`signature` but still hits the blank-field reason falls through to the generic `forged: true` bucket instead, since a signed field reading blank only happens via post-signing tampering. The genuinely-unsigned case (no `alg`/`signature` fields, blank `timestamp`/`source`) keeps its `forged: false` classification unchanged — that one remains a defensible "unsigned legacy marker" read, not an attack signal.
+  - **Honest residual (read before assuming more than it delivers): this is CONSUMER-SIDE ONLY.** Unlike the understanding-gate marker, harness does not WRITE the solution-acceptance verdict — the producer is `@lannguyensi/grounding-mcp`, a separate package/repo. This task shipped the pattern + exemplar (`signVerdict` / `verifyVerdictSignature`, exported from `solution-acceptance-runtime.ts`, are the reusable pair a producer-side change mirrors) but **no currently-released grounding-mcp version signs its output**. Concretely, until a matching producer release ships (a tracked cross-repo follow-up): every verdict this consumer reads is "unsigned" and the completion-gate denies it UNIVERSALLY, even a perfectly legitimate `ready:true` verdict at the correct HEAD; re-running `solution_evaluate` does not recover from this (the new verdict is unsigned too); `harness pause`, or temporarily disabling the pack, is the operator's interim recourse. grounding-mcp's own `solution_gate` does not yet enforce this signature either — only this harness consumer does, until the producer-side change closes that asymmetry. `docs/policy-packs/solution-acceptance.md` "Marker signing" spells this out in full. **Unlike f9485cc7's residual, there is no operator-side command that resolves this one**: f9485cc7's producer and consumer live in this one repo, so a denied operator has a local one-command fix (`harness approve understanding` / `harness approve branch-protection`); here the producer is a separate package on its own release cadence, so nothing an operator runs today makes a verdict pass until that producer release ships. The persisted-report approval path (task `7402301d`) and the write-guard's glob-every-segment / interpreter-runtime-path-construction residual are UNCHANGED by this task and remain separately tracked.
+  - New tests: `tests/policy-packs/solution-acceptance-runtime.test.ts` (sign/verify round-trip, forged/unsigned rejection distinct from no-marker, hand-written-marker-without-key forgery regression, one-tampered-signature-byte regression, tampering `ready` without touching `signature`, relabeled-body signature-replay rejection, a VERBATIM file-copy cross-id replay regression, an isolated `verdict.id !== id` pin independent of the markerId fix, a sanitize-collision regression (`"a:b"` vs `"a_b"` colliding on one file path), the two missing-timestamp/missing-source not-forged carve-outs (now exercised via a genuinely UNSIGNED marker), signing-key-I/O-failure-not-classified-as-forged, the golden-fixture tests updated to assert the real UNSIGNED 0.3.2/0.5.0 producer markers are now rejected while a locally-signed copy of the same content still gates correctly, and — fix-round-2b — a SIGNED-verdict-with-blanked-timestamp/source regression pinning `forged: true` (audit finding A8) plus a minimal-hand-written-marker negative control pinning `forged: false` (audit finding A7)) and `tests/cli/pack-hook-solution-acceptance.test.ts` (the same forgery/tamper/cross-id-replay regressions and the forged-audit-tag diagnostic, exercised through the real hook entrypoint, plus — fix-round-2b — the SIGNED-and-blanked-timestamp forged-tag regression, the `verdict.id !== id` cross-id-mismatch-with-a-still-valid-signature regression, and forged-tag negative controls on the not-ready and stale-head denial paths).
+- **SECURITY (LOW): `isEscapeCommand`'s top-level `command.trim()`
+  (`src/cli/pack/approve-escape.ts`) stripped a TRAILING report-heredoc line
+  made only of a non-bash-blank whitespace codepoint (e.g. NBSP, U+2028)
+  before the 623640a5 `after.every(/^[ \t]*$/)` post-terminator check ever
+  saw it, making that check unreachable through the public API for exactly
+  the shape it exists to reject** (task `508a2d81`, a residual the
+  623640a5 fold self-disclosed). PATH-stub verified against real bash: such
+  a line is not inert — bash attempts to execute it as a real command.
+  Fix: the top-level trim now strips only TAB, SPACE, LF, and CR from the
+  string's boundaries (never the full JS `\s`/Unicode-whitespace class), so
+  every other `\s` codepoint survives to the after-check.
+- **SECURITY: the agent-facing deny envelope of the built-in `gate-prod-destructive`
+  Risk Gate policy named the session-wide kill switch (`harness pause --for
+  <duration>` / `harness resume`) as a way to unblock a denied critical
+  production mutation** (task `70781cf6`). `ux.run` is the exact "what to do
+  next" text the blocked agent reads (`renderAgentFacing`,
+  `src/runtime/intercept.ts`); handing that same agent a recipe for silencing
+  every gate in the session is a full bypass instruction addressed to the
+  party who was just blocked, not to the operator who alone can act on it.
+  Removed the kill-switch line from `gate-prod-destructive`'s `ux.run` in both
+  `src/cli/init/templates.ts` (`FULL_TEMPLATE`) and
+  `docs/examples/full-manifest.yaml`; the two remaining `run:` entries (choose
+  a non-destructive alternative, or ask the operator for a deliberate `harness
+  approve risk --force` override) stay unchanged and fully actionable. The
+  operator-facing recovery path is not lost: `harness pause`'s own refusal
+  message already explains the correct route (a terminal genuinely outside the
+  agent session). While auditing every other shipped `ux.run` line for the
+  same class of leak, the `deny-kill-switch-bypass` and
+  `deny-pause-sentinel-forgery` policies' `run:` text also named `pause`/
+  `resume` as something the operator could be asked to do; reworded both to
+  point back at the commands already named in their `cannot`/`required` text
+  instead of repeating the verbs in the actionable `run:` list.
+  `deny-session-env-strip`'s `run:` line did not name either verb and is
+  unchanged. Fix round 1 (Finding 3, reviewer-flagged): reworded
+  `deny-pause-sentinel-forgery`'s `run:` line again — its first rewording's
+  "Ask the OPERATOR to do that themselves" had an ambiguous antecedent (the
+  nearest noun phrase was the just-forbidden sentinel write, not the
+  operator's actual recovery action); it now points explicitly at "the
+  operator-only command named under Required" instead, without
+  reintroducing `pause`/`resume` into the `run:` text itself.
+
+  New/updated tests: `tests/cli/init-no-agent-facing-pause-hint.test.ts` is
+  a repo-wide guard over every agent-facing `ux.run` line the init/describe
+  surface can emit: `manifest.policies[].ux.run` AND
+  `manifest.policy_packs[].config.ux.run` (understanding-before-execution,
+  branch-protection, post-merge-gate) across `FULL_TEMPLATE`,
+  `SOLO_TEMPLATE`, `TEAM_TEMPLATE`, and `docs/examples/full-manifest.yaml`,
+  plus the Custom composer (`composeCustom()` in
+  `src/cli/init/composer.ts`, `harness init --interactive`'s Custom
+  profile) with every composable pack and policy selected. Fix round 1
+  (Finding 1, reviewer-flagged as a MEDIUM coverage gap) added the
+  `policy_packs`/composer coverage and the `harness gate disable`/`harness
+  gate enable` sibling-verb check — the original guard only walked
+  `manifest.policies[].ux.run`, so a kill-switch hint reworded into a
+  policy pack's `ux.run` (or into the Custom composer's own copy) would
+  have passed both this guard and the pre-existing parity tests
+  unnoticed. Each scanned source also now asserts it found at least one
+  `ux.run` line (Finding 2): before the round-1 fix, `SOLO_TEMPLATE` has
+  zero top-level `policies:` entries, so that arm silently scanned zero
+  lines under the original narrower guard and could not have caught
+  anything. A "see also" citation to
+  `docs/okf/pause-vs-gate-kill-switch.md` stays allow-listed as
+  non-actionable, and a dedicated assertion pins that
+  `gate-prod-destructive`'s `ux.run` has exactly its two legitimate
+  entries left. Regenerated `docs/examples/full-manifest.expected.yaml`
+  (the `harness describe` golden fixture) to match. Coverage note
+  (Finding 4, reviewer-flagged as inaccurate): the existing
+  `tests/cli/init-full-template-parity.test.ts` is the test that
+  deep-equality-checks `FULL_TEMPLATE` against
+  `docs/examples/full-manifest.yaml` (including each policy_pack's
+  `config`, so its `ux.run` too); `tests/cli/init-templates-ux-parity.test.ts`
+  is a separate drift guard that instead pins `FULL_TEMPLATE` /
+  `SOLO_TEMPLATE` / `TEAM_TEMPLATE` / the Custom composer's policy_pack
+  `ux` against the canonical `defaultUx()` functions in
+  `src/policy-packs/builtin/*.ts`, not against `full-manifest.yaml`.
+
+- **SECURITY: `harness apply`'s generated Claude Code `settings.json` hook
+  `timeout` was emitted in the manifest's `budget_ms` unit unconverted, so
+  every Claude-hook kill-timer was 1000x too large** (task `7bf47554`).
+  Claude Code's settings.json hook `timeout` is documented in SECONDS
+  ("Seconds before canceling",
+  https://code.claude.com/docs/en/hooks); the manifest's `budget_ms` is
+  milliseconds. `toSettingsCommand` (`src/cli/apply/generate-settings.ts`)
+  emitted `timeout: h.budget_ms` with no unit conversion, so a template
+  budget of 1000-2000ms silently became a Claude Code timeout of
+  1000-2000 SECONDS (16-33 minutes) instead of 1-2 seconds, meaning
+  hard-blocking enforcement hooks (e.g. `harness policy intercept`) could
+  hang for tens of minutes before Claude Code cancelled them, rather than
+  failing fast. The sibling Codex projection
+  (`src/cli/apply/generate-codex-config.ts`) already converted correctly
+  (`Math.ceil(budget_ms / 1000)` with a policy-intercept floor); the
+  Claude Code projection now shares that exact formula via a single
+  extracted helper, `hookTimeoutSeconds` (`generate-settings.ts`), so the
+  two runtime projections cannot diverge on this again. `harness adopt`'s
+  reverse projection (`src/cli/adopt/index.ts`'s `buildHookEntry`), which
+  read a live settings.json `timeout` back into the manifest's
+  `budget_ms`, is fixed symmetrically (`* 1000`) so the adopt<->apply
+  round-trip stays lossless; `timeout` remains deliberately excluded from
+  the adopt drift key, so the ms/seconds rounding asymmetry a non-1000-
+  multiple `budget_ms` introduces (e.g. 1500ms -> 2s -> 2000ms) does not
+  register as phantom drift or duplicate-adopt a hook. New/updated tests:
+  `tests/cli/apply/generate-settings.test.ts` pins the corrected
+  conversion (including the 2s/1s floors) and asserts both runtime
+  projections emit the identical seconds value for the same hook;
+  `tests/cli/adopt.test.ts` adds an explicit apply-then-adopt round-trip
+  test for the 1500ms rounding-asymmetry case, asserting zero drift.
+
+  **Fix round 2, same task: the corrected 1-2s outer timeout above was
+  ITSELF a fail-open regression, not purely a safety fix.** Review found
+  that `harness policy intercept`'s blocking, ledger-consulting hooks —
+  every `requires:`-based policy (the require-*-evidence / risk-gate
+  policies) AND, via the engine's unconditional per-decision audit write
+  (`intercept()`'s `options.ledger.record(...)` call, run for every
+  matched policy including the pure pattern-deny `operator_only` kill
+  switches), every other blocking `harness policy intercept` hook too —
+  can legitimately need up to the grounding-mcp server's own
+  `health.timeout_ms` (5000ms by default) for a single ledger query, plus
+  a further deny-degraded audit-write retry bounded by
+  `auditRetryTimeoutMs` (`src/cli/policy/intercept.ts`), for a measured
+  worst case of ~10.8-13.75s. The now-CORRECT 1-2s Claude Code outer
+  timeout sits well UNDER that: on a merely slow or hung ledger (not a
+  clean, fast failure), Claude Code kills the `harness policy intercept`
+  subprocess before its `deny`/`deny-degraded` JSON reaches stdout, and a
+  killed PreToolUse hook is treated as ALLOW — silently turning a
+  correctly-computed fail-closed verdict into an unintended fail-open one.
+  The same shape applies to the three builtin policy-pack blockers
+  (`branch-protection`, `understanding-before-execution`,
+  `post-merge-gate`), whose own ledger probes are bounded by the identical
+  `health.timeout_ms` with effectively zero margin against their own
+  budget_ms=5000 outer timeout. Fixed by raising every blocking (`blocking:
+  "hard"`), ledger-consulting hook's `budget_ms` to 15000 (a 15s outer
+  timeout) in `src/cli/init/templates.ts` (FULL_TEMPLATE's eleven
+  `harness policy intercept` hooks, uniformly — deliberately including the
+  three pattern-deny kill-switch hooks, both because their audit write
+  waits on the same ledger round-trip and because `generate-settings.ts`'s
+  `buildGroups` dedupes same-matcher hooks by `(command, timeout)`, so a
+  non-uniform budget would split one Claude Code invocation per Bash call
+  into several redundant ones), `docs/examples/full-manifest.yaml` /
+  `.expected.yaml` (the one hook there that actually routes through
+  `harness policy intercept`), and the three builtin policy packs
+  (`src/policy-packs/builtin/branch-protection.ts`,
+  `understanding-before-execution.ts` — both the Claude and Codex
+  variants — `post-merge-gate.ts`). 15000ms clears the measured
+  ~10.8-13.75s worst case with margin. Trade-off, stated plainly: a gated
+  action can now visibly freeze for up to ~15s when the evidence ledger is
+  down or hanging, instead of failing fast (and silently open) at 1-2s —
+  this IS the intended fail-closed posture the Risk Gate's
+  `degraded_fail_posture: preserve_enforcement` default (task `f1aea826`)
+  already commits to; the pre-existing 1-2s budget just never gave that
+  posture enough time to actually land. New test:
+  `tests/runtime/hook-budget-ledger-margin.test.ts` pins, against the real
+  shipped `FULL_TEMPLATE` and the real policy-pack `resolve()` output
+  (not a hardcoded hook-name list), that every blocking ledger-consulting
+  hook's outer timeout clears `health.timeout_ms` plus the deny-degraded
+  audit-retry margin — a lightweight stand-in for the fuller drift-guard
+  task `d20a7e0c` is tracking.
+
+  **Fix round 2 continued, same task: the raise above was itself
+  incomplete.** Review found two more `harness init` surfaces still
+  shipping the identical blocking `harness policy intercept` hooks at
+  their pre-fix 1000-2000ms budgets — the same fail-open gap, reachable
+  through a different init path than `--template full`: the
+  `harness init --interactive` Custom composer's `HOOK_FOR_POLICY` table
+  (`src/cli/init/composer.ts`, five hook rows backing its six reference
+  policies) and the `team` profile template's `require-review-evidence`
+  hook (`src/cli/init/profiles.ts`'s `TEAM_TEMPLATE`). Raised both to the
+  same uniform 15000ms. The `solo` profile template ships no blocking
+  `harness policy intercept` hook at all (no agent-tasks-coupled or
+  Bash-triggered evidence policy in that profile), so there is nothing to
+  raise there; a new negative-control test pins that this is by design,
+  not an oversight. With this, the "every blocking ledger-consulting
+  hook" framing above is now accurate across every manifest-emitting
+  `harness init` surface, not only `FULL_TEMPLATE`. Also strengthened
+  `tests/runtime/hook-budget-ledger-margin.test.ts`: it now asserts the
+  same margin invariant against the Custom composer's full policy
+  selection and `TEAM_TEMPLATE` too (mutation-probe confirmed: reverting
+  either surface's budget back to its pre-fix value turns exactly that
+  surface's new assertion red, while every other assertion — including
+  the other surface's — stays green), asserts the `SOLO_TEMPLATE`
+  negative control, and adds a hard 15000ms floor assertion alongside the
+  existing formula-derived margin check. The formula alone
+  (`health.timeout_ms` + 2x `auditRetryTimeoutMs`, ~8s for the shipped
+  5000ms grounding-mcp timeout) understates the measured ~10.8-13.75s
+  subprocess wall-time worst case, so a partial regression into
+  [8000ms, 13000ms) would still pass a formula-only check; the new hard
+  floor (pinned to the same ~10.8-13.75s measurement this task's budget
+  note above and `src/cli/init/templates.ts` both cite) closes that gap,
+  with its own control test pinning the discrimination at a 10000ms
+  probe value.
+
+- **SECURITY: `harness validate` / `harness doctor` now ENFORCE the
+  hook-budget-vs-ledger-timeout margin task `7bf47554` above only pinned
+  by hand against the shipped defaults** (task `d20a7e0c`). Everything
+  `7bf47554` fixed was a one-time, hardcoded raise of specific budgets on
+  specific manifest-emitting surfaces (`FULL_TEMPLATE`, the Custom
+  composer, `TEAM_TEMPLATE`, three builtin policy packs); nothing stopped
+  an aged manifest, a hand-authored `harness.yaml`, or a manifest that
+  simply raises `tools.mcp.grounding-mcp.health.timeout_ms` from silently
+  regressing back into the fail-open gap — a merely SLOW (not even
+  hard-down) evidence ledger getting a blocking `harness policy
+  intercept` / policy-pack hook killed by the runtime's outer hook
+  timeout before its fail-closed `deny`/`deny-degraded` JSON reaches
+  stdout, which both Claude Code and Codex then read as an unintended
+  ALLOW.
+
+  Two fixes:
+
+  1. **Corrected margin formula.** `7bf47554`'s own hardcoded 15000ms
+     floor existed because its formula (`health.timeout_ms` +
+     2x`auditRetryTimeoutMs`, ~7500ms at the shipped 5000ms default)
+     UNDERSTATED the measured ~10.8-13.75s real-world worst case. Re-
+     deriving from `realLedgerClient`'s actual two round-trip shapes
+     (`src/cli/policy/intercept.ts`) explains the gap and closes it
+     properly: `query()` can cost up to **2x** `health.timeout_ms` (a
+     slow-but-alive server can independently near-max BOTH the
+     `initialize` handshake and the following `ledger_summary` call
+     before the second one finally times out — not just 1x), and the
+     deny-degraded audit retry can cost up to **3x**
+     `auditRetryTimeoutMs` (the fresh retry session's own `initialize`,
+     the first `ledger_add` attempt, and — only when that attempt is
+     rejected outright by an older/incompatible grounding-mcp rather
+     than timing out — the legacy `type: "fact"` fallback `ledger_add`).
+     The corrected formula, `requiredHookBudgetMs(T) = 2T +
+     3*auditRetryTimeoutMs(T)` (new export, `src/cli/policy/
+     intercept.ts`), evaluates to 13750ms at the shipped 5000ms default —
+     within `7bf47554`'s own cited ~10.8-13.75s measurement range, unlike
+     the ~7500ms the old formula gave. Both round-trip shapes are
+     measured independently against the REAL `realLedgerClient` /
+     `recordPolicyDecisionOnSession` (not just asserted) in
+     `tests/e2e/policy-intercept.test.ts`'s new "hook-budget-ledger-margin
+     derivation" suite, via a fake grounding-mcp subprocess that can
+     independently delay `initialize`, `ledger_summary`, and
+     `ledger_add`, and can force the legacy fact-type fallback.
+
+  2. **Durable, generic validate/doctor guard.** New
+     `checkHookBudgetLedgerMargin` (`src/cli/validate/checks.ts`, wired
+     into both `harness validate` and `harness doctor`) checks the
+     corrected formula against an ARBITRARY manifest's OWN
+     `tools.mcp[grounding-mcp].health.timeout_ms` — not the shipped
+     5000ms default — and against every ENABLED `policy_packs[]` entry's
+     resolved hooks via the shared `resolveBuiltin` registry lookup, for
+     every runtime `harness apply` can target, instead of
+     `7bf47554`'s test hand-importing three specific pack modules. A pack
+     whose blocker gates on a filesystem verdict marker rather than a
+     live ledger round-trip (`solution-acceptance` /
+     `solution-acceptance-writeguard`) is correctly excluded — flagging
+     it would be a false positive. An under-budgeted hook is reported as
+     an `error` naming both the hook's own `budget_ms` and the ledger's
+     `health.timeout_ms` (plus the derived requirement), so e.g. an
+     operator who raises `health.timeout_ms` without raising a
+     pack-shipped hook's fixed `budget_ms` in lockstep is now caught at
+     lint time instead of silently reopening the gap. Also fixes the
+     matcher this check (and, incidentally,
+     `tests/runtime/hook-budget-ledger-margin.test.ts`'s own
+     `blockingInterceptHooks`) uses to recognise a `harness policy
+     intercept` hook: the new `isPolicyInterceptCommand`
+     (`src/cli/policy/intercept.ts`) matches the subcommand tokens
+     regardless of a leading interpreter/env-var prefix (`node
+     /path/to/dist/cli/index.js policy intercept`, `npx harness policy
+     intercept`, `FOO=bar harness policy intercept`) or a trailing flag
+     (`harness policy intercept --hook <name>`), instead of the verbatim
+     `command.trim() === "harness policy intercept"` compare every other
+     call site in this codebase still (deliberately, out of this task's
+     scope) uses — an operator-authored `manifest.hooks[]` entry is under
+     no obligation to spell the command exactly the way harness's own
+     generators do, and under-recognition here is a false NEGATIVE on a
+     security check. Fix round 1 (review 2026-08-09) additionally widens
+     `isPolicyInterceptCommand`'s TRAILING boundary to also accept a
+     semicolon or quote character glued directly onto the subcommand word
+     with no whitespace (`harness policy intercept; echo done`, `sh -c
+     "harness policy intercept"`), which the whitespace-or-end-only
+     boundary shipped in this task's first commit missed; a trailing `)`,
+     `|`, `&`, or backtick immediately abutting the word remains a known,
+     deliberately-unclosed gap (documented in the function's own doc
+     comment) rather than a runtime bypass — a missed match here only
+     means the hook is not classified as ledger-consulting for THIS
+     check, never a change to what the hook actually does at runtime.
+
+  **Fix round 1 (review 2026-08-09): two corrections to this task's own
+  first commit, made in the name of not overclaiming what the guard
+  above actually guarantees.**
+
+  - **The `2T + 3R` formula's "worst case" claim is scoped to the
+    pure-timeout hang shape, not every degradation shape.** The formula
+    (and the diagnostic message above) previously read as an unqualified
+    worst-case bound. It is not one: `query()`'s `2T` half assumes the
+    pooled `LedgerSession`'s session-wide `timedOut` latch trips (making
+    the FIRST `record()` attempt instant, per `realLedgerClient`'s own
+    doc comment) — true only when `query()` degrades via an actual
+    timeout. A `query()` that instead degrades via a NON-timeout path
+    (`ledger_summary` returning a genuine JSON-RPC error, an unparseable
+    payload, or a payload missing the `entries` shape —
+    `LedgerSession.querySummary`'s non-timeout `degraded` branches,
+    `src/policies/ledger-client.ts`) never sets that latch, so the first
+    `record()` attempt afterwards is a REAL round-trip too — up to
+    another `2T` (the `type: "policy_decision"` attempt plus a possible
+    legacy `type: "fact"` fallback) BEFORE the `3R` retry sequence even
+    starts. Worst case on this "error-then-hang" shape is therefore up to
+    `4T + 3R` — 23750ms at the shipped `T=5000` default, against this
+    guard's `13750ms` floor. The formula is DELIBERATELY NOT raised to
+    `4T + 3R`: doing so would fail `checkHookBudgetLedgerMargin` against
+    the shipped, reviewer-confirmed-clean fresh-init budget of `15000ms`
+    (task `7bf47554`/#414, out of this task's scope) at the same
+    `T=5000` default, since `15000 < 23750`. Instead, `requiredHookBudgetMs`'s
+    doc comment (`src/cli/policy/intercept.ts`) and the
+    `checkHookBudgetLedgerMargin` diagnostic message now both name this
+    residual explicitly as a KNOWN, un-closed gap rather than implying a
+    guarantee neither actually gives — the guard backs delivery of the
+    fail-closed verdict on the pure-timeout hang shape only. This
+    residual is NOT confined to one runtime projection: Claude Code and
+    Codex both convert `budget_ms` into the outer hook-kill seconds via
+    the identical `hookTimeoutSeconds` helper
+    (`src/cli/apply/generate-settings.ts`, shared by
+    `generate-codex-config.ts`) since task `7bf47554`/#414, so a manifest
+    at the shipped defaults is equally exposed on both — checked against
+    both generators' current source for this note, not assumed.
+
+  - **The diagnostic message no longer attributes a `3× deny-degraded
+    audit-retry budget` to hooks that never run one.** The four
+    ledger-consulting pack blockers (`branch-protection`,
+    `understanding-before-execution`'s `pre-tool-use` /
+    `codex-pre-tool-use`, `post-merge-gate`) only ever call
+    `queryLedgerByTag` (open session, one `querySummary`, dispose) — they
+    never call `ledger_add`, so they have no deny-degraded audit-retry
+    step of their own; their real worst case is bounded at up to
+    `2×timeout_ms` for the query alone, not `2T + 3R`. The shared
+    `${required}ms` floor is kept identical across direct
+    `harness policy intercept` hooks and these pack blockers on purpose
+    (a deliberately conservative carryover, not a separately-derived and
+    separately-tested per-kind bound), but the message text explaining
+    WHY now differs per hook kind instead of asserting a retry sequence
+    that does not exist for the pack blockers. `post-merge-gate`
+    specifically already fails OPEN (allow) on a degraded or unreachable
+    ledger by its own design (`src/cli/pack/hook-post-merge-gate.ts`'s
+    "Fail posture: OPEN" note, and its own `budget_ms: 15000` comment in
+    `src/policy-packs/builtin/post-merge-gate.ts` already said as much)
+    — a hook killed by the outer timeout there reaches the same allow
+    outcome its own degraded-handling would already choose, so this
+    check is kept for it only to stop a merely-slow-but-alive ledger from
+    needlessly stalling the gate, not because a fail-closed verdict is at
+    risk. `src/cli/validate/checks.ts` now tags each collected hook with
+    its ledger-traffic shape (`isPolicyInterceptHook`,
+    `isFailOpenOnDegraded`) to pick the right explanatory text; the
+    numeric threshold, hook selection, and severity are all unchanged.
+
+  `tests/runtime/hook-budget-ledger-margin.test.ts`'s original
+  hand-imported per-surface assertions are updated to source their margin
+  bound from the corrected formula (previously understated) and gain a
+  new describe block running the generic `checkHookBudgetLedgerMargin`
+  guard against the very same shipped manifests, closing the loop the
+  file's own comment named as future work. New/updated tests:
+  `tests/cli/validate.test.ts` (fixture pairs for AC1/AC2 plus the
+  matcher-fix, pack-genericity, and negative-control cases, plus fix
+  round 1's semicolon-chained and quote-wrapped matcher cases),
+  `tests/cli/doctor.test.ts` (doctor-surface parity + `format()`
+  rendering), `tests/runtime/hook-budget-ledger-margin.test.ts`,
+  `tests/e2e/policy-intercept.test.ts`.
+
+- **SECURITY: the operator-approval escape matcher (`isEscapeCommand`,
+  `src/cli/pack/approve-escape.ts`) used JS's generic `\s` whitespace
+  class where bash's actual lexical blank set was meant, letting a
+  non-bash-blank codepoint move a report heredoc's real delimiter word
+  (as bash reads it) away from the word the matcher extracts** (task
+  `623640a5`). Ground-truthed against GNU bash with a PATH-stub harness:
+  of the 25 codepoints JS's `\s` class matches, only TAB and SPACE are
+  bash lexical blanks; the other 23 (NBSP U+00A0, LF, CR, VT, FF, and 18
+  further Unicode space-separator/line-separator/BOM codepoints) glue
+  onto the adjacent token instead of being stripped as an insignificant
+  separator. Measured exploit shape (the 2026-08-04 halt that opened this
+  task): a non-breaking space right after a report heredoc's `<<'X'`
+  intro closing quote was accepted by the matcher's `\s*$` as
+  insignificant trailing whitespace, so the matcher extracted delimiter
+  `X`; bash instead glues the NBSP onto the quoted word, so its real
+  delimiter is `X`+NBSP, and the body line `X`+NBSP (matching the
+  matcher's delimiter, not bash's) closes the heredoc one line early:
+  the following body line then runs as a real top-level command
+  (`git push origin master` in the measured repro) instead of staying
+  inert report text. Fix: every regex in the module that means "a
+  separator bash will actually treat as blank here" (the heredoc-intro
+  trailing/leading whitespace, the `harness`/`approve` separator, the
+  heredoc command-part whitelist, the command-part right-trim, and the
+  post-terminator blank-line check) now uses `[ \t]`, never `\s`.
+  Behavior change operators should know about: a `harness approve`
+  heredoc carrying a non-bash-blank codepoint in one of those positions
+  used to be accepted as a clean escape and routed to the normal
+  interactive ASK permission prompt; it is now DENIED outright (fails
+  closed to the ordinary understanding-gate block), since ASK implied a
+  false equivalence to the safe heredoc shape. The PreToolUse
+  discoverability hint (`approveEscapeHint`,
+  `src/cli/pack/hook-pre-tool-use.ts`) now also names the offending
+  codepoint (e.g. "contains U+00A0 ... where an ordinary space or tab was
+  expected") when a blocked command carries one, so an agent that emitted
+  invisible whitespace gets a reason instead of silently retrying the
+  same bytes. New regression tests: `tests/cli/pack-approve-escape.test.ts`
+  (the full 25/23 codepoint enumeration measured against the live JS `\s`
+  class, the NBSP incident itself, and a mechanical guard, module source
+  with comments/strings stripped, asserting no future regex in the
+  module can reintroduce a bare `\s` token, mutation-verified to actually
+  redden); `tests/cli/pack-hook-pre-tool-use.test.ts` (the hint still
+  surfaces for the newly-blocked shapes, now naming the codepoint; a
+  negative control confirms an ordinary metacharacter block names no
+  codepoint).
+
+- **SECURITY: `harness doctor` now detects template-policy drift, an
+  installed manifest that lacks a shipped `operator_only` kill-switch
+  security policy** (task `adf037c1`). Measured 2026-08-06: a 0.44.0
+  machine whose `~/.harness/harness.yaml` predated the kill-switch
+  defenses (`deny-kill-switch-bypass`, `deny-session-env-strip`,
+  `deny-pause-sentinel-forgery`) had the documented `harness pause`
+  bypass live as ALLOW, with nothing surfacing the gap: `harness apply`
+  never retroactively adds newly-shipped default policies to an
+  already-materialized manifest, so security policies introduced after
+  install reach only fresh installs. Doctor's new "Template drift
+  (shipped security policies)" section compares the installed manifest
+  against `shippedOperatorOnlyPolicyNames()` (the `operator_only` set
+  parsed from `FULL_TEMPLATE` itself, kept honest by the full-template
+  parity test), so it can never drift from what `harness init --template
+  full` writes and automatically extends when a new operator_only policy
+  is added. Each missing policy is an ERROR (doctor exits non-zero, the
+  standard CI/dogfood signal), naming the policy and the rehydration
+  path. A same-named-but-DOWNGRADED policy (present but no longer
+  `operator_only: true`, e.g. the historical `requires.ledger_tag` shape
+  a ledger write can satisfy, or `enforcement: warn`) is flagged as a
+  distinct error too: name-presence alone would pass a bypassable
+  kill-switch as no-drift, the exact aged-manifest class this check
+  targets. A stale/typo'd `doctor.ignore_template_drift` entry matching
+  no shipped name is surfaced as a warning so a policy rename cannot
+  silently strand an opt-out. Scope is the `operator_only` security floor regardless of profile
+  (a solo/team install missing kill-switch protection is flagged too;
+  that is the security core, per operator decision 2026-08-08), and it
+  does NOT nag about full-only convenience policies a smaller profile
+  never carried. Deliberate opt-out: `doctor.ignore_template_drift:
+  [<policy-name>, ...]` in the manifest, a NEW minimal `doctor:` schema
+  section that silences only the doctor report line and changes no
+  enforcement. This is deliberately NOT a `policies[].enabled: false`
+  flag: the runtime policy engine has no such concept, so an operator
+  setting it would believe a policy disabled while it still fired (a
+  footgun the CLI help + docs already implied but no code backed). The
+  original AC's two-severity split (operator_only error vs cosmetic
+  warning) was consciously narrowed to a single operator_only error tier
+  per the same operator scope decision, since cosmetic policies are no
+  longer compared. Shared `checkTemplatePolicyDrift` in
+  `src/cli/validate/checks.ts` (doctor-only surface today; validate is
+  about internal consistency, not external-reference comparison, so it is
+  intentionally not wired to fail `harness validate`/`apply`).
+  docs/okf/pause-vs-gate-kill-switch.md documents the drift check and the
+  opt-out; fixtures cover missing/present/opt-out/partial, and a parity
+  test pins the shipped set so a template rename reddens rather than
+  silently shrinking the check.
+
+- **SECURITY: read-only Bash classifier no longer treats mutating
+  argument forms of allowlisted git subcommands as read-only** (task
+  `9d1fff1b`). `GIT_READ_ONLY_SUBS` (`src/runtime/read-only-bash.ts`)
+  was a bare-form allowlist of subcommand NAMES; measured against real
+  git 2.50.1, six argument forms of those names mutate while classifying
+  read-only: `git branch -D <b>` (deletes a branch), `git tag <name>`
+  (creates a tag), `git remote set-url` (rewrites config), `git fetch
+  <url> <refspec>` (writes an arbitrary local ref), `git diff
+  --output=<path>` (creates/overwrites a file; `log`/`show` accept the
+  same option), and `git reflog expire`/`delete` (destroys reflog
+  entries). All four consumers of the classifier — the risk-classifier
+  read-only severity floor, both PreToolUse understanding-gate hooks, and
+  the solution-acceptance write-guard — funnel through the same
+  `classifyTokens`, so all four are corrected by the single fix and none
+  needed a consumer-side change (measured: the full pack + risk-classifier
+  suites, 602 tests, unchanged). The `bin === "git"` branch now applies a
+  per-subcommand POSITIVE argument-form check (`isReadOnlyGitInvocation`):
+  branch/tag are read-only only with no non-flag operand (every mutation
+  needs the branch/tag name; branch also denies the glued no-operand
+  writes like `--set-upstream-to=`); remote only for the `show`/`get-url`
+  verbs or bare `-v`; fetch only for bare or a single remote/URL (a
+  second positional refspec blocks — the escalation to an arbitrary
+  local ref); reflog only for bare/`show`/flag forms (expire/delete/drop
+  are always the first arg); everything after a bare `--` is folded into
+  the positional view. Two write/exec vectors reach git's SHARED option
+  parser and transport layer and are therefore forfeited GLOBALLY, above
+  the per-subcommand switch, for every allowlisted git subcommand (review
+  round 1, measured against git 2.50.1): `--output=<path>` creates a file
+  at option-parse time — measured writing on `rev-list`/`shortlog`/`blame`
+  as well as diff/log/show — and `--upload-pack=`/`--exec=`/`--receive-pack=`
+  plus `ext::`/`fd::` positional transports run an operator-named binary
+  locally (measured `git fetch --upload-pack=<script> <repo>` executing
+  the script). The choice is positive-shape, not a write-flag
+  denylist, so a git argument this floor has not reasoned about
+  over-blocks (annoying) instead of laundering a write (unsafe) — the
+  same fail-closed stance as the existing `npm audit` guard, and
+  deliberately NOT the enumerate-every-exception shape whose repeated
+  failure halted the neighbouring task 5b5d1022. Literal verb/flag
+  comparisons use the repo's raw-or-decoded form (task fdee7d0f) so a
+  quoted spelling (`git remote se"t-url"`) fails the positive match and
+  blocks rather than slipping through. Explicitly out of scope (separate
+  tasks): global-option / path-qualified git (`git -C <d>`, 5b5d1022),
+  GNU long-option abbreviations (dd055c1d), and env-var exec equivalents.
+  negative tests pin the mutating forms (reproduced against git 2.50.1),
+  positive controls pin the bare forms plus the read corpus (`rev-parse
+  --git-dir`, `ls-files -c`, `log -c HEAD`, `show -c HEAD`, `diff --stat`,
+  `status --short`, and single-positional `fetch`/`ls-remote` from a URL);
+  a mutation probe confirms reverting to the bare-name allowlist reddens
+  the negative suite, and a per-arm probe confirms each raw-or-decoded
+  decode arm is load-bearing (deleting it reddens a quoted no-positional
+  write form). The over-blocked read forms (`git tag -l 'v*'`,
+  `git branch --contains HEAD`, separated fetch flag values, ...) are the
+  accepted conservative cost, documented in `docs/risk-gate.md`.
+
+- **SECURITY: block/require_approval policies now fail CLOSED when their
+  evidence source is degraded, instead of silently mapping to the
+  never-blocking `warn-degraded`** (task `f1aea826`). Measured 2026-08-06 on
+  0.44.0 (isolated probe home, `git push` event without its preflight tag):
+  a healthy ledger denied, every broken-ledger shape (ENOTDIR, corrupt file,
+  directory) denied, but `--ledger-timeout` at 1/25/50/100 ms flipped the
+  same event to **ALLOW**, because the timeout path mapped to
+  `warn-degraded`, which `isBlockingDecision` never treats as blocking.
+  `evaluateOnePolicy`'s degraded family (ledger timeout/spawn failure,
+  unresolved template variables, invalid `within`, thrown evaluator,
+  schema-invariant branch) now routes through a tier-aware
+  `degradedOutcome`: `warn` policies keep the non-blocking `warn-degraded`
+  (availability first, unchanged), `block`/`require_approval` policies
+  produce the NEW blocking `deny-degraded` outcome. The `deny-degraded`
+  envelope deliberately bypasses the policy's `ux:` surface and names the
+  degraded cause (sanitised: the transport reason embeds subprocess
+  output, so the envelope interpolation is bounded to 200 chars with
+  control characters stripped) plus an operator-facing recovery path, so
+  nobody debugs a phantom missing tag on an unreadable ledger. The
+  fail_open opt-out is deliberately ABSENT from that agent-facing text
+  (review finding: a deny that includes its own disable recipe is not a
+  gate, and nothing prevents the blocked agent from editing the
+  manifest); it is named on the operator surfaces instead: the verbose
+  stderr diagnostic, docs/risk-gate.md, and the OKF fail-posture matrix.
+  **ACCEPTED SEMANTIC CHANGE
+  an upgrading operator should know about:** a degraded ledger (including
+  "grounding-mcp not declared in manifest" under block-tier policies) now
+  DENIES where it silently allowed; the explicit manifest opt-out
+  `risk.degraded_fail_posture: fail_open` (schema default
+  `preserve_enforcement`, `src/schema/risk.ts`) restores the pre-0.45
+  availability-first mapping for every tier, and the operator-only
+  `harness pause` kill switch remains the deadlock escape (it is honoured
+  BEFORE manifest load); the shipped init template documents the knob as
+  a COMMENTED-OUT line on purpose (the schema is strict, so an emitted
+  key would make the manifest unreadable by a pre-0.45 binary, and a
+  manifest load failure is allow at the hook layer: on a mixed-version
+  fleet that would turn a downgrade into a silent full fail-open). Audit
+  completeness rides along, best-effort and precisely bounded: the pooled
+  ledger session's timeout latch previously guaranteed that exactly the
+  degraded deny lost its own audit row (every post-timeout call on that
+  session short-circuits), so `realLedgerClient.record` now retries once
+  per invocation over a fresh session, RESERVED for `deny-degraded` rows
+  (an allow/warn row failing first cannot consume it) and capped at
+  max(250ms, timeoutMs/4) per call — two calls, so the added stall is at
+  most half a timeout once the ledger timeout is >=1s, and bounded at
+  500ms absolute below that, where the floor dominates (the formula is
+  pinned as the exported `auditRetryTimeoutMs`); a longer or unreserved
+  retry would stall the deny path toward the outer hook budget, where a
+  hook timeout is conventionally allow. With grounding-mcp absent from the manifest
+  altogether there is no transport at all: a BLOCKING decision on that
+  path now emits a dedicated "has NO audit row" stderr line instead of
+  the previous silent no-op. `isBlockingDecision` is now exported and
+  shared with the CLI wrapper's pending-approval staging, which had a
+  drifted hand-rolled copy. New outcome threaded through every consumer:
+  `harness audit` `VALID_OUTCOMES`, `explain`/`audit` `--outcome` filters,
+  the verbose stderr diagnostic (which names the outcome, the fail-closed
+  posture and the operator opt-out, cause-neutrally — the true cause
+  follows on its own reason line), a NEW
+  default-verbosity one-line stderr operator hint per degraded-denied
+  event (carrying the decision's OWN sanitised reason, since
+  deny-degraded has five causes and only one of them is the ledger — a
+  hardcoded ledger-fault wording sent operators of the other four to a
+  green `harness doctor`; pointing at doctor and the docs, deliberately
+  without the opt-out literal on the default channel, and suppressed
+  under verbose where the full diagnostic supersedes it), and the
+  `checkPolicyGroundingMcp` validate/apply warning, whose pre-0.45
+  "every policy will fire in degraded warn-mode" wording described the
+  inverse of the new block-tier behaviour and is now tier-aware and
+  test-pinned; `smoke` assertions classify the new outcome as deny via
+  the unchanged envelope path. A stale-contract drift guard now runs in
+  the suite: `tests/no-stale-fail-posture-claims.test.ts` fails if the
+  pre-0.45 phrasings OR the round-4-enumerated restatement shapes
+  ("ledger degradation → warn-degraded" untiered, "only ever blocks if
+  grounding-mcp", the untiered fail-open framing) reappear under `src/`
+  or `docs/` outside a per-phrase allowlist with freshness checks and
+  one positive control per needle. Honest bound, stated in the guard
+  itself: it is a literal/pattern grep pinning the mechanically
+  greppable phrasings the review rounds found, not a semantic checker —
+  wrong-modality claims were fixed by hand and are not pinned, and a
+  future paraphrase avoiding all needles still needs eyes (four review rounds
+  each found a fresh such surface; docs quoting message literals
+  verbatim was the recurring root cause, so the updated docs now
+  describe messages instead of quoting them); the same sweep updated
+  docs/writing-custom-policies.md,
+  docs/CLI.md, docs/examples/pandora-bootstrap.md, the OKF
+  producer-wiring bundle, the ledger-client module header, the init
+  composer's wizard advisory, and marked the superseded ROADMAP Phase 4
+  acceptance bullets. NOT closed here, named so no
+  doc overclaims: the OUTER hook-budget layer (a hook exceeding its
+  `budget_ms` is allow by harness contract) stays fail-open and is not
+  reachable from this repo's schema; keep hook budgets comfortably above
+  the ledger timeout (the shipped template's 1000-2000ms budgets vs the
+  5000ms grounding-mcp health timeout mean the HANG shape can still blow
+  the hook budget before the deny lands; a validate/doctor consistency
+  check is filed as a follow-up task), and malformed event JSON or a
+  failed manifest load remain allow-with-stderr at the CLI wrapper.
+  docs/risk-gate.md "Degraded mode",
+  docs/okf/gate-fail-posture-matrix.md,
+  docs/okf/policy-engine-producer-wiring.md and
+  docs/okf/debug-verb-selection.md rewritten to the new contract;
+  the two pre-0.45 pins asserting warn-degraded-never-blocks for block
+  tier were rewritten deliberately alongside (unit + e2e), plus new
+  fixtures: require_approval+timeout blocks, warn+timeout allows,
+  fail_open opt-out restores the old mapping end-to-end through the real
+  manifest parse, genuine-timeout e2e (hanging fake grounding-mcp), an
+  AC4 e2e pinning exactly TWO subprocess spawns with the `deny-degraded`
+  row landed in the ledger despite the latch, retry allocation (a warn
+  row failing first does not consume the deny row's retry),
+  envelope-over-ux precedence, envelope sanitisation, the opt-out's
+  absence from the envelope and presence on stderr, the no-transport
+  "has NO audit row" line, and `--outcome deny-degraded` accepted by
+  audit/explain filters.
+
+- nanoid bumped 3.3.16 → 3.3.18 via `npm audit fix` (lockfile-only, no source
+  change), closing GHSA-2v37-7h3g-55p8 / CVE-2026-67213 (High, CVSS 8.2:
+  `customAlphabet`/`customRandom` loop indefinitely when `size` is 0; affected
+  range < 3.3.17). Dev-only transitive (vitest → vite → postcss → nanoid);
+  postcss's declared `^3.3.16` already admits the fix, so no `package.json`
+  change and no override introduced (the same shape as the 0.42.0 entry that
+  carried nanoid 3.3.12 → 3.3.16 for the postcss advisory). harness source
+  never calls nanoid, so the advisory's mechanism is not reachable from the
+  shipped CLI; the practical effect is `npm audit` back to 0 findings and this
+  repo's own preflight npm-audit check unblocked. Note the structural residue
+  the 0.42.0 entry already accepted: postcss's range floor (3.3.16) is below
+  the patched 3.3.17, so only the lockfile pin holds the fix (conscious
+  no-override decision, unchanged). (task `b81e8e09`)
+
+- **SECURITY: the Risk Gate's environment resolver ignored a `git
+  switch`/`checkout <branch>` at the head of a Bash command, so a
+  same-command branch hop onto a production branch ran under the
+  PRE-switch (often `unknown`) label** (task `341e024b`). Measured
+  2026-08-06 (isolated probe home, harness 0.44.0, cwd on a non-production
+  branch): `git switch main && rm -rf <path>` and the `git checkout main`
+  equivalent both classified `critical` severity / `unknown` environment /
+  **ALLOW**, while the comparison `cd <repo-on-main> && rm -rf <path>` form
+  already denied — the branch resolver only ever read `.git/HEAD` at the
+  hook's cwd (or, since the `cd`-target fix below, a leading `cd <path>`'s
+  target), never a `git switch`/`checkout` argument. Alltagsrelevant: the
+  post-merge convention of switching back to the default branch before
+  continuing work is exactly this shape (`git switch main && rm -rf
+  node_modules && npm ci`), so it ran ungated while the identical work with
+  a leading `cd` did not.
+
+  `src/runtime/bash-prefix-parse.ts`'s `parseBashPrefix` now also extracts
+  a `branchTarget` from a leading `git [-C <path>] (switch|checkout)
+  <branch> [&&|;]`, mirroring the existing `cdTarget` extraction (a new
+  `consumeLeadingGitSwitch`, sharing the same command-head-only, two-pass,
+  no-shell-simulation discipline the module's `cdTarget`/`inlineEnv`
+  parsing already has — task `1a8a103d`). Deliberately conservative,
+  unlike `cdTarget`'s bidirectional risk (which can raise OR lower the
+  resolved environment depending on the target, a pre-existing, documented
+  asymmetry — G5, task `98ad072f`/2026-07-27 — untouched by this task):
+  `git checkout -- <path>` (a file restore, not a branch change) and an
+  unresolvable `$VAR`/`${VAR}` branch argument set NO branch signal — never
+  guessed. `src/cli/policy/intercept.ts`'s new `applyBranchSwitchUpgrade`
+  merges the parsed branch candidate against the existing `resolverGit`
+  (cwd- or cd-target-based) UPGRADE-ONLY: both are run through the same
+  `resolveEnvironment` call with identical env/kube inputs, and the
+  switch-target branch is only adopted when it resolves to a MORE
+  dangerous environment than the base; a switch AWAY from a production
+  branch never downgrades an already-production classification.
+
+  5 new end-to-end fixtures in `tests/runtime/intercept-cli-bash-prefix.test.ts`
+  pin the acceptance criteria (`git switch main`/`git checkout main` from
+  a non-prod cwd now deny; `git switch <non-prod-branch>` from a repo
+  already on `main` still denies — no downgrade; `git checkout --
+  <path>` and `git switch $BRANCH` set no signal and stay allow), plus
+  unit coverage for the parser itself in
+  `tests/runtime/bash-prefix-parse.test.ts` (slashed branch names, the
+  optional `-C <path>` skip, the flag/variable/missing-separator
+  exclusions, and — falling out of the existing two-pass loop for free —
+  a leading `cd <path> && git switch <branch>` chain resolving both
+  candidates). Existing `cdTarget`/inline-env fixtures are unchanged and
+  green. `docs/risk-gate.md`'s "Environment resolvers" section documents
+  the new upgrade-only branch signal alongside the pre-existing
+  bidirectional `cd` one.
+
+  Fix round 1 (reviewer-flagged, `accept_with_notes`): the upgrade-only
+  merge itself was verified sound (no downgrade path), but two gaps
+  remained. **MEDIUM (security):** a QUOTED branch name bypassed the
+  gate entirely — `consumeLeadingGitSwitch` read the branch token
+  INCLUDING the quote characters, so `git switch "main" && rm -rf <path>`
+  extracted `branchTarget` as the literal 6-character string `"main"`,
+  which never matches a `branch_patterns` entry like `main`, so no
+  upgrade fired and the destructive command ran ungated — identical in
+  effect to the pre-fix unquoted case above. The sibling `cd`-target
+  parser already stripped quotes (`skipPathToken`/`consumeLeadingCd`);
+  this was an inconsistency, and the module doc's given reason for
+  skipping a quoted branch form ("real git branch names cannot contain
+  whitespace, so this covers slashed names without needing a quoted
+  form") was itself wrong — a whitespace-free branch name can still be
+  quoted by the operator. `consumeLeadingGitSwitch` now reads a single-
+  or double-quoted branch token the same way `skipPathToken` reads a
+  quoted path: literal content, quotes stripped. A `$`-containing
+  DOUBLE-quoted branch argument is still left unresolved (real bash
+  interpolates inside double quotes, consistent with the existing
+  unquoted-`$VAR` rule); a SINGLE-quoted one is always literal, since
+  single quotes never interpolate in real bash. New e2e fixtures in
+  `tests/runtime/intercept-cli-bash-prefix.test.ts` pin `git switch
+  "main"` / `git switch 'main'` / `git checkout "main"` from a non-prod
+  cwd now denying, a quoted switch away from `main` still not
+  downgrading, and a double-quoted `"$BRANCH"` still not guessed; new
+  parser-unit coverage in `tests/runtime/bash-prefix-parse.test.ts`
+  covers the quote-stripping itself, the double-quote-`$` exclusion, the
+  single-quote-`$` literal case, unterminated/empty quoted literals, and
+  the missing-separator rule for a quoted branch. Mutation-probed:
+  disabling the quote-stripping branch turns exactly the 12 new e2e/unit
+  assertions red.
+
+  **LOW (maintainability):** `ENV_RANK` in `src/cli/policy/intercept.ts`
+  is a hand-maintained copy of `ENV_PRECEDENCE` in
+  `src/runtime/environment-resolver.ts`; the `Record<MatchableEnvironment,
+  number>` type catches an added/removed environment but not a REORDER,
+  which could silently invert the upgrade-only direction. A new drift
+  guard, `tests/runtime/intercept-env-rank-drift-guard.test.ts`, measures
+  `ENV_PRECEDENCE`'s real order live via `resolveEnvironment` (four
+  resolvers, one per environment, each on a different signal kind so all
+  four can fire on one probe envelope at once; the conflict winner reveals
+  the true order by elimination) and, for every adjacent pair in that
+  measured order, round-trips `runInterceptCli` to confirm
+  `applyBranchSwitchUpgrade`'s `ENV_RANK`-driven behavior agrees.
+  Mutation-probed: swapping two adjacent entries in `ENV_PRECEDENCE`
+  (without touching `ENV_RANK`) turns exactly the affected pair's two
+  assertions red.
+
+  **LOW, documentation only (not built):** a chained double switch (`git
+  switch dev && git switch main && rm ...`) resolves `branchTarget` as
+  `dev` (first-switch-wins), missing `main`. Multi-switch parsing was
+  deliberately NOT added — it would widen the parser's surface toward the
+  false-positive class task `dbc6d303` already measured. The module doc
+  on `consumeLeadingGitSwitch` and `docs/risk-gate.md` now state this
+  limit explicitly so it is not over-trusted.
+
+### Changed
+
+- Audited `src/runtime/recovery-git-commit.ts`'s three JS `\s`-based
+  tokenizers (the `git\s+commit` anchor and `tokenize`'s leading-skip and
+  token-continuation checks) against the same JS-`\s`-vs-bash-blank
+  divergence class `623640a5` closed elsewhere — reviewer residual from
+  that task. Measured against real bash and git (PATH-stub): unlike
+  `623640a5`, this module's over-split is safe by construction, not a
+  fix. No production change; the safe direction is pinned in
+  `tests/runtime/recovery-git-commit.test.ts` with live bash+git evidence
+  for every call site plus a hermetic pin across all 23 non-bash-blank
+  `\s` codepoints. (task `822a508d`)
+
+### Fixed
+
+- **`init`'s MCP registration could mutate/read the WRONG `claude` CLI registry file under a non-default home, and treated an "already registered" outcome as a hard failure that blocked the settings.json migration** (task `fb3e4dce`, two reviewer findings on run `2026-07-18-init-mcp-wiring-claude-code`). Finding 2: `realClaudeMcpExec` (`src/io/claude-mcp.ts`) spawned the real `claude` CLI with no explicit `env`, so it inherited `process.env` verbatim — identical to `ensureMcpServers`'s own drift-read directory only when that directory happened to be the OS default (`~/.claude.json`). A non-default `homeDir`/`registryPath` override (e.g. `harness init --home`) made the live CLI spawn mutate/read a DIFFERENT registry file than the one `ensureMcpServers` had just compared `desired` against. Fixed by threading a new `configDir` through every verb wrapper to `exec`'s new third argument; `realClaudeMcpExec` now sets `CLAUDE_CONFIG_DIR` in the spawned child's env from it. **Correction (review round 2, task `fb3e4dce`): the original fix set `configDir = path.dirname(registryPath)` unconditionally, which on the DEFAULT resolution path is `~` itself (not the CLI's own actual default `CLAUDE_CONFIG_DIR` of `~/.claude`), so it silently redirected every OTHER config-dir-relative path the CLI resolves (e.g. registry backups landing in `<HOME>/backups` instead of `<HOME>/.claude/backups`) — `resolveMcpConfigDirOverride` (`src/io/claude-mcp.ts`) now emits `configDir` only when the resolution actually used a `CLAUDE_CONFIG_DIR`/`homeDir`/`registryPath` override, leaving the pure default path's real spawn with unmodified `process.env` inheritance; the same helper now also backs `uninstall`'s `claude mcp remove` call (`src/cli/uninstall/index.ts`), which previously threaded no `configDir` at all under a non-default `--home`.** A `claude mcp get` verification that merely timed out or hit a missing CLI (inconclusive, not a positive "absent") no longer overrides a File-verified already-exists match on its own (`addAndVerifyAlreadyExists`); the wizard's post-registration message now distinguishes freshly `add-json`-registered servers ("registered N ...") from verified-already-exists ones ("confirmed N ... already registered"), instead of reporting both as "registered". Finding 3: `ensureMcpServers` reported an `add-json` "already exists" outcome exactly like any other failure, even when the desired server genuinely IS registered (e.g. a registration this run's own registry-file read raced ahead of/missed) — the wizard's `allOk` gate then blocked the dead-`settings.json`-`mcpServers`-block migration even though the target state already held. `addAndVerifyAlreadyExists` now confirms an "already exists" outcome via `claude mcp get` + a fresh re-read of the same registry file (empirically verified: `claude mcp get`'s stdout is prose and does not expose the registered command/args, so the spec comparison uses the file, not `get`'s own output) — a verified, spec-matching registration is surfaced as `EnsureServerResult.verifiedAlreadyExists.matches: true`, which `wireClaudeMcp`'s `allOk` check now treats as success; an unverified or spec-mismatched one preserves the prior conservative behavior unchanged. New coverage in `tests/io/claude-mcp.test.ts` (configDir threaded to every verb across an add/replace/get sequence for a non-default home; matching-spec, mismatched-spec, and get-can't-find-it already-exists variants; a plain "added" outcome never calls `get`) and `tests/cli/init-interactive.test.ts` (end-to-end: a verified-matching already-exists still runs the settings.json migration and prints no failure warning; a verified-mismatched one skips migration and prints the same warning as before this fix). Review round 2 adds: a real `claude mcp add-json` spawn (a throwaway shim binary, never the operator's real CLI/registry) pinning that an explicit `configDir` wins over the parent process's own `CLAUDE_CONFIG_DIR` and that omitting it inherits `process.env` verbatim; pure-function coverage of `resolveMcpConfigDirOverride`'s default-vs-override decision; a `claude mcp remove` configDir-alignment pin for `uninstall` under both an explicit `--home` and the pure default; a timed-out-`get`-still-checks-the-file case; and verb-order plus message-wording pins on the two existing already-exists wizard tests.
+- **The session-start preflight not-ready fail-log's default directory (`~/.harness/logs`) is now repo-wide test-isolation-safe instead of suite-local** (task `80f49922`, reviewer finding on `a48b9729`). `defaultFailLogDir()` called `os.homedir()` directly, so the throw-on-real-home-dir guard in `resolvePaths()` (`loader.ts:45-64`, already pinned by `tests/integration/operator-state-isolation.test.ts`) never covered this seam — only a suite-local `vi.mock("node:os")` pin in `preflight.test.ts` did, protecting the one caller that suite happened to know about, not any future test or child process. `defaultFailLogDir` now resolves via `resolvePaths()` (same idiom as `defaultReportsDir`'s caller in `approve/understanding.ts`), so a caller that forgets to inject `homeDir`/`configPath` now fails at the guard instead of silently writing into the operator's real home. Side effect fix: the fail-log dir now also respects `$HARNESS_HOME` and the legacy `~/.claude/` fallback instead of hardcoding `~/.harness/` regardless of the rest of the harness state's actual location (a pre-existing divergence from task `31fbf856`) — EXCEPT when `configPath` is injected without `homeDir`: `configPath` overrides the manifest path directly, so the log dir becomes `dirname(configPath)/logs` and does not route through home-dir resolution (or the `$HARNESS_HOME`/legacy tiers) at all in that case. The not-ready branch now catches only the guard's throw (`persistFailLog`'s own write failure already never throws, so it stays outside that try/catch) and folds it into the same `{ ok: false, reason }` shape a fail-log write failure already produces, so the SessionStart producer still never throws. New coverage in `tests/integration/operator-state-isolation.test.ts` (no `HARNESS_INTEGRATION_TESTS` opt-in, no subprocess spawn), all exercising `runSessionStartPreflight` directly: a no-injection negative control (asserts the guard blocks the write and the real `~/.harness/logs/` is byte-for-byte unchanged); a hermetic `homeDir`-injection case and a hermetic `configPath`-injection case (neither mocks `os` nor needs `HARNESS_ALLOW_REAL_GENERATED_DIR`, since an injected option bypasses the guard outright); a `$HARNESS_HOME` case (needs the `ALLOW_REAL` escape hatch to reach that precedence tier since neither `homeDir` nor `configPath` is injected, secured with the same real-`~/.harness/logs/`-unchanged assertion as the negative control); and a legacy `~/.claude/` fallback case, the only one of the five that mocks `node:os` — scoped to itself via `vi.doMock` + a dynamic re-import — because that precedence tier reads `os.homedir()` directly and has no LoaderOptions seam to override it. `preflight.test.ts`'s suite-local negative-control test is updated to assert the guard blocks the write; its `vi.mock("node:os")` pin stays in place as a second line of defense for every OTHER `os.homedir()` consumer in that suite (it no longer protects this one seam, which now fails closed independently of it).
+- **Two not-ready preflight fail-logs written in the same millisecond practically never overwrite each other anymore** (task `a48b9729`). The fail-log filename's ISO timestamp has millisecond resolution, so a second persist within the same ms silently clobbered the first; filenames now carry a 4-hex random suffix (`preflight-<repo>-<timestamp>-<hex4>.json`), leaving a 1-in-65536 same-millisecond residual collision chance rather than a guarantee. Alongside (test-only): the preflight suite pins `os.homedir()` to a throwaway tmp home so a not-ready test that forgets to inject `logDir` can never write into the operator's real `~/.harness/logs` (with a negative-control test), plus rotation boundary tests (exactly 20 → no eviction; 21 → exactly the oldest evicted), hostile-repo-basename containment tests, and a multi-failing-checks cap/join pin.
+- **`harness doctor`'s dead-`settings.json`-`mcpServers`-block check now honors `CLAUDE_CONFIG_DIR`** (task `f13c6fbd`, #423). The check read a fixed `<home>/.claude/settings.json`, so with a config-dir override it inspected a file Claude Code does not read. Resolution now mirrors `resolveClaudeUserRegistryPath`'s precedence (non-empty `CLAUDE_CONFIG_DIR` wins), the warning names the resolved path, and doctor gained an `envOverride` test knob so the dead-block tests stay hermetic against the operator's real environment. (This entry was itself backfilled by the first run of the new changelog-coverage gate below.)
+- **`harness dry-run`'s `bash_match` prediction under-predicted the quoted-shell-boundary family (`VAR='a; b' git push origin master`) that `harness policy intercept` already blocks** (task `f561e44c`, follow-up to `cf3dff51`). Task `cf3dff51` wired `normalizeCommandQuoteAware` into `policyMatchesEvent` (`src/runtime/intercept.ts`) as a fourth matching arm but, scoped narrowly to that one wiring point, deliberately left `dry-run`'s own independently-copied matcher (`src/cli/dry-run.ts`) untouched — reintroducing the debug-verb/runtime parity gap that file's own comment (and `docs/okf/debug-verb-selection.md`) has warned about since task `ea8becf5`. `policyMatchesTool` now tries the same fourth, quote-aware OR-arm, literally duplicated to mirror the amp-aware arm's own precedent (no shared-helper seam exists for this OR-chain yet). Debug-verb-only fix, no gate touched; `dry-run` was under-predicting, the fail-safe direction. New parity fixture: `tests/cli/dry-run.test.ts` asserts `dry-run` and `policyMatchesEvent` agree, entry for entry, across the 12 `cf3dff51` target spellings (`;`, `|`, `&&`, `(`, and a literal newline in both spaced/unspaced forms, on `git push` and the operator-only kill switch).
+- **`understanding-before-execution`'s `config.mode` (harness.yaml) was config-drift: it drove prose only, never enforcement** (task `5d73d78d`; fix landed in two rounds, the second a review fix-round closing three HIGH findings against the first). Live repro in an isolated home: `config.mode: grill_me`, an agent report with no `mode:` metadata field, `harness approve understanding` (stdin heredoc) → output read `validation: ✓ fast_confirm report passed structural checks` and persisted `"mode": "fast_confirm"`, silently skipping the `derivedTodos` / `acceptanceCriteria` / `priorArt` sections `grill_me` requires. Root cause, two independent sites: (1) the Claude-runtime `UserPromptSubmit`/`Stop` hooks are bins shipped by `@lannguyensi/understanding-gate` (`understanding-gate-claude-hook` / `understanding-gate-claude-stop`), invoked bare — no `UNDERSTANDING_GATE_MODE` env var — so the package's own env-then-marker-then-`fast_confirm`-default resolver always fell through to its default; (2) `persistStdinReport`'s gap-fill for a report with no declared mode hardcoded the literal `"fast_confirm"`.
+  - Fix: mode resolution is now TWO functions with different contracts (`src/policy-packs/builtin/understanding-before-execution.ts`), not one. `resolveModeFromConfig()` — `config.mode` > default (`grill_me`), **never the env var** — drives the GENERATION path: `resolve()`/`buildHooks` (what `harness apply` bakes into `settings.json` + `instructions.md`) and `registry.ts`'s `resolveBuiltinDefaultConfig` (`harness doctor`'s UX-drift comparison, `harness pack reseed`). `resolveMode()` — `UNDERSTANDING_GATE_MODE` env > `config.mode` > default — is reserved for LIVE runtime consumers that resolve at invocation time with the real process environment available: `approve/understanding.ts`'s stdin-report gap-fill, and the Codex `UserPromptSubmit` injector (`harness pack hook codex-user-prompt-submit`). The first round shipped a single env-aware resolver for BOTH roles, which meant an operator's ambient `UNDERSTANDING_GATE_MODE` (exported for an unrelated one-off override, or left over from a previous shell) would silently override `config.mode` in the GENERATED artefact itself — persisting, frozen, until the next `apply`, and making `doctor`/`reseed` report drift that had nothing to do with `harness.yaml`. `buildHooks` still bakes the (now config-only) resolved mode into the two npm-backed Claude bin commands via the same env var (`wrapMode`), but omits the prefix entirely when the resolved mode already coerces to the package's own default (`fast_confirm`) — baking it unconditionally (the first round's behavior) made the package's own in-prompt `/grill` / "grill me" per-prompt escalation marker permanently dead, since the package's own resolver checks its env var before ever looking at the marker.
+  - Fix: `harness approve understanding`'s stdin-report path now genuinely REFUSES the approval marker when the submitted report is rejected under the resolved mode (e.g. a `fast_confirm`-shaped report submitted against a `grill_me`-configured host) and no report matching this session id exists — no marker, no ledger tag, no report flip, unless `--force` (mirroring the pre-existing `priorArt`-validation short-circuit). The first round resolved the correct mode but a rejected stdin submission with no fallback report still fell through to a `{ skipped: true }` validation outcome (not `ok: false`), so the marker was written anyway — a config-drift-shaped hole reopened one call deeper than the one this task closes. A second review round (verification round 2) closed a further gap in the same guard: a sessionId-null pending report ADOPTED via the tolerant fallback (not a strict sessionId match) does not count as "matching this session id" either, so a rejected submission can no longer silently ride on an unrelated leftover report's already-valid content and get stamped with the live session's id.
+  - `strict` has no upstream equivalent (the package's own mode type is two-valued); `toPackageMode()` coerces it to `grill_me` — the closest available rigor — only at that interop boundary, not inside harness's own `strict` semantics.
+  - **Behavior change, corrected blast-radius statement (the first round's was inaccurate — it implied only an EXPLICITLY-configured non-`fast_confirm` host was affected):** the mode actually enforced now matches `config.mode` in all three cases — `config.mode: fast_confirm` (was already effectively `fast_confirm`, unaffected save for the marker-liveness fix above), `config.mode: grill_me` / `strict` (now genuinely enforced, was silently `fast_confirm`), **and no `config:` block / no `mode:` key at all** (now genuinely enforced at `grill_me`, the package default — this last case is the WIDEST blast radius of the three and was NOT called out by the first round's changelog entry: every unconfigured host is affected, not only hosts with an explicit setting). Previously-accepted reports missing `derivedTodos` / `acceptanceCriteria` / `priorArt` are now rejected until the agent supplies them, for any host in the latter two buckets.
+  - New/updated coverage: `tests/policy-packs/resolve-mode.test.ts` (both resolvers' contracts, LOW-8/LOW-9 warning + normalisation fixes), `tests/policy-packs/expand.test.ts` and `tests/cli/apply/apply.test.ts` (generation-path env-independence, the omitted-prefix case), `tests/cli/approve-understanding.test.ts` and `tests/cli/approve-stdin-report.test.ts` (mode gap-fill end to end, the stdin-rejection marker-refusal enforcement + its `--force` escape hatch, the disabled-pack LOW-10 case), and a new suite-wide `tests/_helpers/scrub-ambient-env.ts` setup file (MEDIUM-5: an ambient `UNDERSTANDING_GATE_MODE` in the operator/CI shell no longer leaks into tests that don't explicitly set it).
+- **`harness approve understanding` could persist a self-contradictory report: `approvalStatus: "approved"` alongside a stale `expiredAt` timestamp** (task `646b7b6a`, reviewer finding on `agent-grounding` `5120938c`, the harness-side twin of that repo's `withApprovalStatus` fix in PR #173). `rewriteReportApproved` (`src/cli/approve/understanding.ts`) rewrote `approvalStatus` to `"approved"` in place without clearing `expiredAt`; since `@lannguyensi/understanding-gate` 0.4.11 declared `expiredAt` in the report schema, the field survived the rewrite whenever an operator approved a report that `expirePersistedReport` (`understanding-before-execution-runtime.ts`) had previously expired. Not a gate bypass — enforcement only reads `approvalStatus` — but a data-integrity defect in the persisted audit record. Fix: `rewriteReportApproved` now `delete`s `expiredAt` from the parsed report before serializing, mirroring the package's own `withApprovalStatus` idiom. New test in `tests/cli/approve-understanding.test.ts` covers approving a report fixtured exactly as `expirePersistedReport` writes one (`approvalStatus: "expired"` + ISO `expiredAt`), asserting the key is absent after approval.
+
+### Added
+
+- **Release-pipeline guards: CI now fails fast when a commit since the last
+  tag has no `[Unreleased]` changelog entry, and release.yml aborts instead
+  of shipping an empty release body** (task `3ed3d333`). New
+  `scripts/check-changelog-coverage.mjs` (`npm run
+  check:changelog-coverage`, wired before Build in ci.yml in the
+  check-no-only idiom) compares `git log <last-tag>..HEAD` against the
+  `[Unreleased]` section: a commit counts as covered when the section cites
+  one of its mechanical link tokens (an 8-hex task id from the commit
+  message, the squash-merge `#PR` number, a GHSA advisory id, or the
+  commit's own SHA); commits typed `test`/`docs`/`ci`/`style`/`refactor`/
+  `chore` are skipped by a convention documented — with its limits — in the
+  script header. Verified against the historical failure: a checkout of
+  `5b7a36f` (pre-0.42.0) goes red with 14 uncovered commits (including the
+  postcss HIGH advisory close), while this branch is green; the gate's
+  first live run also caught the missing `f13c6fbd` doctor entry backfilled
+  under Fixed above. release.yml additionally hard-stops after the awk
+  extraction when `release_notes.md` came out empty or whitespace-only
+  (the "tag pushed before converting [Unreleased]" failure mode), naming
+  the missing `## [<version>]` section in the error.
+- The `toolchain-parity` ledger fact now carries unparseable peer snapshots
+  instead of silently absorbing them into a shrunken comparison (task
+  `690fba7c`, consumer hardening motivated by the agent-memory `06d09cde`
+  incident where a corrupted `machine-state/<profile>.json` — inline git
+  conflict markers, not valid JSON — made the drift count quietly fall from
+  `drift:22` to `drift:5` with no warning). A peer file that fails
+  `parseSnapshotJson` now also logs a `parity:unparseable-peer:<file-derived
+  label>` stderr line, and the run's ledger fact gains a
+  `:unparseable-peer:<n>` suffix (e.g. `toolchain-parity:drift:7:unparseable-peer:2`)
+  whenever one or more peer files were skipped this way, so an unparseable
+  peer never makes `drift:N` look like a complete comparison. (Peers whose
+  file cannot be READ at all are a separate branch scoped to task
+  `c1b5ade5`; the absence of the suffix alone therefore does not prove
+  completeness.) The file-derived label is sanitized before interpolation —
+  peer filenames arrive cross-machine via sync and are untrusted, so a
+  crafted name cannot forge a standalone parity line in stderr — and falls
+  back to the raw filename when stripping `.json` would leave it empty. The
+  existing "peer snapshot `<file>` is corrupt" warn line is unchanged;
+  valid-only peer sets keep the exact pre-existing `toolchain-parity:ok` /
+  `toolchain-parity:drift:<n>` format (no behaviour change). Four new tests
+  (negative control, corrupt-peer-plus-drift, multi-peer aggregation
+  pinning `:unparseable-peer:2`, hostile-filename sanitization) plus two
+  existing cases extended.
+- Both PreToolUse hooks (Claude and Codex) now tell a blocked agent WHICH
+  Understanding Report sections were malformed on their last attempt: a
+  `(list)` heading that was present but held prose instead of markdown
+  list items, with an agent-facing sentence naming each section as
+  `<Display Name> (<key>)` (e.g. `Prior Art (priorArt)`), paired with
+  `renderReportSchemaHint`'s existing display-name vocabulary rather than
+  the bare camelCase key the parser itself uses (task `823837fd`, review
+  Fix 3). The sentence is only appended when the session has NO persisted
+  report at all, never when a fixed report is merely pending operator
+  approval (review Fix 1), and is defined once and shared by both hooks
+  via `renderMalformedSectionsNotice` (`src/cli/approve/understanding.ts`,
+  review Fix 4) instead of two byte-identical copies.
+- `harness approve understanding`'s one-line parse-error summary
+  (`findLatestParseError`) likewise names malformed sections when the
+  operator-facing reason is not already sourced from the package's own
+  `message` field, which annotates them inline since
+  `@lannguyensi/understanding-gate` 0.4.10 (review Fix 5).
+- `@lannguyensi/understanding-gate` lockfile refreshed to 0.4.10 (the
+  `malformedSections` `ParseError` field this surfacing depends on);
+  the declared range stays `^0.4.9`.
+- **`harness doctor` now warns (advisory, never an error) when
+  `UNDERSTANDING_GATE_MODE` is set in the operator's shell environment and
+  diverges from `policy_packs[understanding-before-execution].config.mode`**
+  (task `24abdecb`, reviewer finding on the `5d73d78d` Batch 11
+  verification round). After that task's fix, only the LIVE runtime path
+  (`resolveMode` in `approve/understanding.ts`'s stdin-report gap-fill, and
+  the Codex `UserPromptSubmit` injector) reads the env var at all — the
+  GENERATION path (`resolve()`/`buildHooks`, what `harness apply` bakes
+  into settings.json) never has and still doesn't. An operator who carries
+  `UNDERSTANDING_GATE_MODE` in their shell profile therefore silently
+  downgrades live enforcement relative to what `harness.yaml` declares,
+  with no signal anywhere that the two have diverged — live-verified:
+  `harness approve understanding` accepted a `fast_confirm`-shaped report
+  against a `grill_me`-configured manifest with no warning. New
+  `checkUnderstandingModeEnvDivergence` (`src/cli/doctor/understanding-mode-env.ts`)
+  is a pure manifest+env check, gated on the pack being declared and
+  enabled, normalising the env value the same way `resolveMode` does
+  (trim + lowercase) so an env value the live resolver would itself reject
+  is correctly treated as non-divergent; the advisory names both the env
+  value and the resolved `config.mode` and renders in doctor's
+  `Environment` section (mirroring the existing npm-global-bin-off-PATH
+  advisory there). `harness doctor`'s existing `envOverride` test-injection
+  knob is reused rather than adding a second one. New coverage in
+  `tests/cli/doctor-understanding-mode-env.test.ts`: the pure function's
+  unset/empty/agreeing/invalid/undeclared/disabled no-advisory cases, the
+  diverging-value case (naming both values), and a `doctor()`-level
+  integration pass through `format()` asserting the rendered `Environment`
+  section and `warningCount`.
+- **`harness apply --runtime opencode`: a third policy-pack adapter
+  runtime alongside `claude-code` and `codex`** (task `f34eb233`).
+  New `src/cli/apply/generate-opencode-config.ts` emits
+  `harness.generated/opencode/opencode.json` in place of settings.json,
+  carrying an ADR-style header documenting the adapter-mapping decisions
+  verified against opencode's published config JSON Schema and docs:
+  `tools.mcp[]` IS projected (opencode's native `mcp` block, reusing
+  `generate-settings.ts`'s `buildMcpServers` / `projectGroundingEnv` so
+  the grounding-mcp `EVIDENCE_LEDGER_DB` wiring and the literal-tilde
+  warning stay identical across every runtime); manifest `hooks[]` and
+  `memory.router` are NOT projected (opencode has no declarative
+  hook/event field at all, only a JS/TS plugin API — out of this task's
+  scope), and opencode's native `permission` block is deferred to a
+  follow-up (v1 keeps parity with the codex adapter's own deferred
+  sandbox-profile mapping), both cases surfacing a warning instead of a
+  silent drop. Output is byte-stable across repeat applies and harness
+  never merges into, or writes, any operator-owned opencode config file
+  (`~/.config/opencode/`, a project `opencode.json`, or `$OPENCODE_CONFIG`)
+  — the generated artefact's own banner explains how an operator wires it
+  in. `--target <path>` is rejected with `--runtime opencode`, symmetric
+  to the existing `--runtime codex` rejection (both wire Claude Code's
+  settings.json). `harness doctor --target opencode`
+  (`src/cli/doctor/opencode.ts`) checks the generated artefact's
+  presence + banner and that every projected MCP server's command
+  resolves on PATH; `countStatusDiagnostics` is factored out of
+  `doctor/codex.ts`'s `countCodexDiagnostics` so both target modules
+  share one tally loop instead of two copies. New coverage:
+  `tests/cli/apply/generate-opencode-config.test.ts`,
+  `tests/cli/apply/apply-opencode-runtime.test.ts`,
+  `tests/cli/doctor-opencode.test.ts`.
+- **`harness apply --runtime opencode` review fix-round** (task
+  `f34eb233`): addresses five findings from the batch18 review of the
+  opencode adapter above. HIGH: `branch-protection` /
+  `understanding-before-execution` / `solution-acceptance` /
+  `post-merge-gate`'s `buildInstructions()` each branched only on
+  `runtime === "codex"`, so opencode silently fell through to the
+  claude-code `else` branch and its `instructions.md` falsely claimed
+  hooks were "wired into the harness-managed settings.json" even though
+  nothing is wired for opencode (no settings.json exists, and
+  `packExpansion.hooks` is never projected into the opencode artefact).
+  Each pack's instructions now mark opencode UNSUPPORTED/not-wired,
+  mirroring `post-merge-gate`'s existing codex marker;
+  `post-merge-gate`'s pack-level apply warning widened from
+  `runtime === "codex"` to `runtime !== "claude-code"` so opencode gets
+  it too; `apply.ts`'s stale "pack instructions.md are runtime-agnostic"
+  comment corrected. MED: added a golden `toBe()` test over
+  `generateOpencodeConfig`'s full rendered output (a manifest with mcp +
+  hooks + a policy-pack-shaped hook + memory.router, deterministic
+  `homeDir`) — the prior substring-only assertions missed a
+  deleted/garbled line inside the generator's static HEADER banner.
+  `src/cli/init/interactive.ts`'s three stale "disabled until f34eb233
+  lands" comments/messages reworded: the adapter has shipped, wizard
+  wiring is tracked separately as installer v1.1 task `c5287b80`;
+  `docs/for-agents.md`'s CLI cheat sheet gains the missing
+  `doctor --target opencode` row. LOW: a `tools.mcp[]` entry declared
+  `enabled: false` is now projected into the opencode `mcp` block as an
+  explicit `{"enabled": false}` marker instead of being omitted --
+  opencode MERGES multiple config sources, so an omitted key does not
+  override an active declaration for the same server name elsewhere,
+  while opencode does accept a bare `{"enabled": false}` entry;
+  `harness doctor --target opencode`'s MCP command-resolution check
+  skips the PATH lookup for such a marker instead of reading its missing
+  `.command`. `countStatusDiagnostics` and its status type moved out of
+  `doctor/codex.ts` into new `doctor/target-checks.ts` (re-exported from
+  `codex.ts` for compatibility) -- `codex.ts` was not a natural home for
+  a target-agnostic tally helper other adapters also depend on.
+
 ## [0.44.0] - 2026-08-03
 
 ### Security