create-pmos 0.28.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Scaffold the PMOS portable kit \u2014 run the PMOS product-management workflow (initiative \u2192 lane-fit spec \u2192 contract \u2192 build \u2192 three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@d333cd5
+kernel-source: pmos@4104fde
 assembled: 2026-08-04
 mode: vendor

package/payload/scripts/pmos-log.sh

@@ -45,10 +45,37 @@ case "$cmd" in
     append runs.jsonl "{\"run_id\":$(js "$1"),\"initiative_id\":$(js "$2"),\"human_corrections\":$corr,\"date\":\"$today\"$model_field}"
     ;;
   eval)
-    [ $# -ge 5 ] || fail "usage: eval <run_id> <initiative_id> <score 0..1> <PASS|PASS-WITH-FINDINGS|FAIL> <rubric_path> [evaluator_model]"
+    # SKIPPED is a verdict this writer must be able to record.
+    #
+    # The enum here was PASS|PASS-WITH-FINDINGS|FAIL, while AGENTS.md tells every adopter: "a gate
+    # that was skipped is recorded as skipped — never leave a missing eval to be read as a pass."
+    # An adopter following that instruction hit `fail` and had no way to comply except by hand-
+    # appending, which is the drift this writer exists to prevent. PMOS-self's own ledger carries 16
+    # SKIPPED rows; the kit could not have written one of them.
+    #
+    # A skip is NOT a soft pass: it takes no score (a skip has no score to give), it requires a
+    # stated reason — an unexplained skip is indistinguishable from a forgotten one — and it leaves
+    # the verification the run owes still owing.
+    if [ "${4:-}" = "SKIPPED" ] || [ "${3:-}" = "SKIPPED" ]; then
+      # tolerated both argument positions: `eval <run> <init> SKIPPED <reason>` is the natural form
+      # when there is no score to give, and refusing it on argument order would just push people
+      # back to hand-appending.
+      if [ "${3:-}" = "SKIPPED" ]; then skip_reason="${4:-}"; skip_rubric="${5:-}"; skip_model="${6:-}"
+      else skip_reason="${5:-}"; skip_rubric="${6:-}"; skip_model="${7:-}"; fi
+      nonempty run_id "$1"; nonempty initiative_id "$2"
+      [ -n "$skip_reason" ] || fail "SKIPPED needs a reason: eval <run_id> <initiative_id> SKIPPED <reason> [rubric_path] [evaluator_model]"
+      rubric_field=""
+      if [ -n "$skip_rubric" ]; then rubric_field=",\"rubric_path\":$(js "$skip_rubric")"; fi
+      emodel_field=""
+      if [ -n "$skip_model" ]; then emodel_field=",\"evaluator_model\":$(js "$skip_model")"; fi
+      append evals.jsonl "{\"run_id\":$(js "$1"),\"initiative_id\":$(js "$2"),\"score\":null,\"verdict\":\"SKIPPED\",\"skipped_reason\":$(js "$skip_reason")$rubric_field,\"date\":\"$today\"$emodel_field}"
+      exit 0
+    fi
+    [ $# -ge 5 ] || fail "usage: eval <run_id> <initiative_id> <score 0..1> <PASS|PASS-WITH-FINDINGS|FAIL> <rubric_path> [evaluator_model]
+       or: eval <run_id> <initiative_id> SKIPPED <reason> [rubric_path] [evaluator_model]"
     nonempty run_id "$1"; nonempty initiative_id "$2"
     printf '%s' "$3" | grep -qE '^(0?\.[0-9]+|0|1(\.0+)?)$' || fail "score must be 0..1 written as 0, 1, N.N or .N — got '$3'."
-    case "$4" in PASS|PASS-WITH-FINDINGS|FAIL) ;; *) fail "verdict must be PASS | PASS-WITH-FINDINGS | FAIL, got '$4'." ;; esac
+    case "$4" in PASS|PASS-WITH-FINDINGS|FAIL) ;; *) fail "verdict must be PASS | PASS-WITH-FINDINGS | FAIL | SKIPPED, got '$4'." ;; esac
     score="$3"; case "$score" in .*) score="0$score" ;; esac  # ".5" -> "0.5": bare .5 is not valid JSON
     [ -f "$KIT/$5" ] || [ -f "$5" ] || fail "rubric_path '$5' not found (relative to the kit or the repo)."
     # optional evaluator-model provenance (which model rendered the verdict). Calibration (κ) is a

package/payload/scripts/workflow-state.js

@@ -859,14 +859,48 @@ function computeWorkflow(id, opts) {
   // ── review ─ the Review Gate's verdict, where the lane has a rubric ──────────────────────────
   const evals = readJsonl(path.join(L.runsDir, 'evals.jsonl')).filter((e) => e && e.initiative_id === id);
   {
-    if (effLane === 'chore' || effLane === 'prototype') {
-      steps.push(step('review', 'review', 'na', effLane === 'prototype'
-        ? 'leg A is grilled as dialogue, never scored (D60)'
-        : 'chore lane carries no rubric (D56)'));
+    /* The rung reads the RUBRIC, not the lane.
+     *
+     * It keyed on `lane` alone, so a chore that deliberately carries a rubric could never surface
+     * its Review Gate — the ladder said "chore lane carries no rubric (D56)" while a SKIPPED verdict
+     * sat in evals.jsonl unread. That is how `guard-and-ledger-hardening`, a chore whose own record
+     * argues "blast radius overrides lane" and which carried a rubric on purpose, reached `accept`
+     * with the gate never run. The board could not show what the ledger already knew.
+     *
+     * A prototype is still never scored — D60 grills leg A as dialogue, and that is a property of
+     * the lane, not of whether someone attached a rubric. Every other lane defers to the artifact. */
+    const declaresRubric = !!String(fm.rubric_path || '').trim();
+    /* EVERY lane defers to the artifact — the first version said so in the comment and applied it
+     * only to `chore`, so a discovery or incident initiative with no rubric (legitimate under D56)
+     * showed a permanent `no Review-Gate verdict recorded`: a rung it could never satisfy. The lanes
+     * that carry no rubric by design are named once, here. */
+    const RUBRIC_OPTIONAL = ['chore', 'discovery', 'incident', 'content'];
+    if (effLane === 'prototype') {
+      steps.push(step('review', 'review', 'na', 'leg A is grilled as dialogue, never scored (D60)'));
+    } else if (RUBRIC_OPTIONAL.includes(effLane) && !declaresRubric && !evals.length) {
+      steps.push(step('review', 'review', 'na', `${effLane} lane carries no rubric (D56)`));
     } else if (evals.length) {
       const last = evals[evals.length - 1];
-      steps.push(step('review', 'review', 'done',
-        `${last.verdict}${last.score != null ? ` (${last.score})` : ''} — advisory until calibrated per evaluator model (D40)`));
+      const verdict = String(last.verdict || '').toUpperCase();
+      const label = `${last.verdict}${last.score != null ? ` (${last.score})` : ''} — advisory until calibrated per evaluator model (D40)`;
+      /* A SKIPPED gate is NOT a satisfied gate, and a FAIL is emphatically not one.
+       *
+       * This rung rendered both as a green ✓, which is the watermelon this repo names as its own
+       * failure mode: the board said the Review Gate was done over a row that says judging never
+       * happened. Thirteen initiatives currently render `✓ review` over a SKIPPED verdict, and the
+       * fix that made a chore's gate visible ADDED one. The module's own rule, repeated in three
+       * files — "a skip is an honest RECORD that verification did not happen; it is not
+       * verification" — now applies to the surface that reports it. */
+      if (verdict === 'SKIPPED') {
+        steps.push(step('review', 'review', 'pending', label,
+          'the gate was skipped, so it is still owed — commission an independent evaluator and record a real verdict',
+          { rule: 'R3' }));
+      } else if (verdict === 'FAIL') {
+        steps.push(step('review', 'review', 'blocked', label,
+          'the Review Gate FAILED — remediate the findings and record a new verdict', { rule: 'R3' }));
+      } else {
+        steps.push(step('review', 'review', 'done', label));
+      }
     } else {
       steps.push(step('review', 'review', 'pending', 'no Review-Gate verdict recorded',
         'score the build against the rubric (build-skills/evaluator.skill), then append to evals.jsonl',

package/payload/skills/evaluator.skill

@@ -7,7 +7,7 @@ description: Adversarially evaluate an agent run's output against its rubric and
 
 This skill is PMOS's **Review Gate** made a first-class, repeatable capability (P4). It formalizes the
 adversarial independent evaluator run by hand through P1–P3: judge what an agent run produced against a
-rubric, write a structured verdict to the `evals` table, and surface it on the radar/board. It runs in
+rubric, write a structured verdict through the validated writer (step 9), and surface it on the board. It runs in
 the **interactive agent runtime** — any capable coding agent; heavy judgment belongs in the agent, not
 an Edge Function ([D09](/DECISIONS.md)/[D34](/DECISIONS.md), amended 2026-07-23). PMOS-self runs it in
 Claude Code, but the runtime is not Claude-specific.
@@ -32,7 +32,7 @@ Claude Code, but the runtime is not Claude-specific.
   may under-reward an unfamiliar style. Either way: **default to skeptical**, and when a pass feels easy
   or you are uncertain, **say so explicitly** and flag the run for the cross-family spot-check /
   minority-veto jury ([calibration-method](/planning/evals/calibration-method.md)). Do not let stylistic
-  (un)familiarity read as quality. **Record your `evaluator_model` on the `save_eval` verdict** — κ is
+  (un)familiarity read as quality. **Record your `evaluator_model` on the verdict** — κ is
   calibrated per evaluator model, and an unrecorded model silently pools calibration across model swaps.
 - **Capability floor — this role assumes a frontier-tier reasoner.** The adversarial passes below
   (default-to-refute, both-ways pairwise, semantic-pass-not-grep, injection resistance) degrade
@@ -57,8 +57,8 @@ Claude Code, but the runtime is not Claude-specific.
   ([injection-defenses](/planning/research/injection-defenses.md)).
 - **Structural scope (binding).** You are **read-only**: no external-communication tool, no
   repository writes, no artifact publishing; your **only write is the schema-constrained
-  `save_eval`** verdict. This removes the exfiltration leg of the lethal trifecta — the component
-  that reads adversarial content must not be the component that can act. Any future widening of
+  verdict, written through the validated writer (step 9)**. This removes the exfiltration leg of the
+  lethal trifecta — the component that reads adversarial content must not be the component that can act. Any future widening of
   this scope requires the trifecta audit in [AGENTS.md](/AGENTS.md) and a PM decision
   ([injection-defenses](/planning/research/injection-defenses.md)).
 - **Advisory, not final.** Your verdict informs; it does not decide. The human PM **Acceptance Gate**
@@ -158,13 +158,45 @@ FAIL — never a clean PASS.) The split is **persisted**, not just narrated (ste
    available, or state `pass-fraction: unknown (no backend)` in kit mode. A high pass-fraction is a
    leniency-drift warning to the PM, not a compliment to the builders
    ([llm-judge-calibration](/planning/research/llm-judge-calibration.md)).
-9. **Persist it** — `save_eval({ initiative_id, run_id, rubric_path, score, verdict, dimensions })`,
-   where `dimensions` is `{ <name>: { score, weight, note, evidence, axis } }` — `evidence` carries
-   the quote/pointer from step 6 (or the string `unverified`), and **`axis` is `"spec"` or
-   `"standards"`** so the two-axis split is persisted, not just narrated. Put the two axis pass/fail
-   summaries in the top-level `note`/report and tag every dimension with its axis. This is what makes
-   the gate self-hosting — the verdict lands in `evals` and surfaces on `v_eval_gate_status`
-   (radar/board).
+9. **Persist it through the validated writer — never by hand.** Which writer depends on where you
+   are running, and **both are validated; neither is a raw append**:
+
+   | you are in | the writer | why |
+   |---|---|---|
+   | **a vendored kit** (`pmos/` in a product repo) | `pmos/scripts/pmos-log.sh eval …` | ships with the kit; writes the kit's `state/evals.jsonl` |
+   | **PMOS-self** (file mode, [D64](/DECISIONS.md)) | `node scripts/record-eval.js --file verdict.json` | writes `planning/runs/evals.jsonl` |
+   | a hosted tenant | the `save_eval` MCP tool | **deprecated for PMOS-self**; does not exist in file mode |
+
+   ```
+   # kit
+   pmos/scripts/pmos-log.sh eval <run_id> <initiative_id> <score> <PASS|PASS-WITH-FINDINGS|FAIL> <rubric_path> [evaluator_model]
+   pmos/scripts/pmos-log.sh eval <run_id> <initiative_id> SKIPPED "<reason>" [rubric_path] [evaluator_model]
+
+   # PMOS-self
+   node scripts/record-eval.js --file verdict.json     # or pipe the JSON on stdin
+   ```
+
+   Both **fail loud**: a rejected verdict exits non-zero with the specific reason and writes nothing,
+   so a malformed record can never light the gate green. `record-eval.js` additionally refuses any
+   sink but the eval ledger — resolved, not by name — which is what keeps a Review-Gate verdict out
+   of the PM's acceptance ledger.
+
+   If the writer your context calls for is not present, **say so in the verdict and stop** — do not
+   hand-append. A ledger written by hand is how a field ends up meaning three things.
+
+   The record carries `{ initiative_id, run_id, rubric_path, score, verdict, evaluator_model,
+   recorded_at, dimensions }`, where `dimensions` is `{ <name>: { score, weight, note, evidence,
+   axis } }` — `evidence` carries the quote/pointer from step 6 (or the string `unverified`), and
+   **`axis` is `"spec"` or `"standards"`** so the two-axis split is persisted, not just narrated. Put
+   the two axis pass/fail summaries in the top-level `note` and tag every dimension with its axis.
+
+   A `SKIPPED` verdict is **declared, not omitted** — it requires `skipped_reason` and carries
+   `score: null`. A skip is an honest record that judging did not happen; it does not close the
+   verification the run owes, and the queue checker (PMOS-self: `scripts/check-verify-queue.js`)
+   will keep reporting the debt.
+
+   This is what makes the gate self-hosting: the verdict lands in the eval ledger and surfaces on the
+   board.
 10. **Hand to the PM.** The Acceptance Gate is theirs, and the PM records the ground-truth `pm_label` to
    `acceptances` — paired against your verdict by `v_calibration` to compute the kappa that calibrates this
    gate ([D40](/DECISIONS.md), [calibration-method](/planning/evals/calibration-method.md)). If the PM
@@ -177,5 +209,6 @@ A short report: **most important finding first**, then the **two axis verdicts (
 one line; Standards: pass/fail — one line)** and the **overall VERDICT** (score vs threshold, under
 the combine rule) with the pass-fraction disclosure, the calibration exemplars used (step 3), the
 numbered defects, and the per-dimension scores **with their evidence quotes/pointers and `axis`
-tag** — followed by the `save_eval` call. Be concrete; cite specifics; if it is genuinely solid, say
+tag** — followed by the verdict record, written through **the writer for your context (step 9)**:
+`pmos/scripts/pmos-log.sh eval …` in a vendored kit, `node scripts/record-eval.js …` in PMOS-self. Be concrete; cite specifics; if it is genuinely solid, say
 so — but only after a real refutation attempt.

package/payload/skills/pmos-router.skill

@@ -19,7 +19,7 @@ lanes and gates that already exist; where it and an authority disagree, the auth
 router is the bug (fix it via the weekly harness scan).
 
 > **Format note:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)).
-> Sources of truth: the AGENTS.md lane list, `.github/scripts/initiative-gate.sh`, D56/D58/D60.
+> Sources of truth: the AGENTS.md lane list, the initiative gate (PMOS-self: `.github/scripts/initiative-gate.sh`; a vendored kit: `pmos/scripts/gate-initiative.sh`), D56/D58/D60.
 
 ## Step 0 — three checks before any route
 

package/payload/skills-native/evaluator/SKILL.md

@@ -8,7 +8,7 @@ license: MIT
 
 This skill is PMOS's **Review Gate** made a first-class, repeatable capability (P4). It formalizes the
 adversarial independent evaluator run by hand through P1–P3: judge what an agent run produced against a
-rubric, write a structured verdict to the `evals` table, and surface it on the radar/board. It runs in
+rubric, write a structured verdict through the validated writer (step 9), and surface it on the board. It runs in
 the **interactive agent runtime** — any capable coding agent; heavy judgment belongs in the agent, not
 an Edge Function ([D09](/DECISIONS.md)/[D34](/DECISIONS.md), amended 2026-07-23). PMOS-self runs it in
 Claude Code, but the runtime is not Claude-specific.
@@ -33,7 +33,7 @@ Claude Code, but the runtime is not Claude-specific.
   may under-reward an unfamiliar style. Either way: **default to skeptical**, and when a pass feels easy
   or you are uncertain, **say so explicitly** and flag the run for the cross-family spot-check /
   minority-veto jury ([calibration-method](/planning/evals/calibration-method.md)). Do not let stylistic
-  (un)familiarity read as quality. **Record your `evaluator_model` on the `save_eval` verdict** — κ is
+  (un)familiarity read as quality. **Record your `evaluator_model` on the verdict** — κ is
   calibrated per evaluator model, and an unrecorded model silently pools calibration across model swaps.
 - **Capability floor — this role assumes a frontier-tier reasoner.** The adversarial passes below
   (default-to-refute, both-ways pairwise, semantic-pass-not-grep, injection resistance) degrade
@@ -58,8 +58,8 @@ Claude Code, but the runtime is not Claude-specific.
   ([injection-defenses](/planning/research/injection-defenses.md)).
 - **Structural scope (binding).** You are **read-only**: no external-communication tool, no
   repository writes, no artifact publishing; your **only write is the schema-constrained
-  `save_eval`** verdict. This removes the exfiltration leg of the lethal trifecta — the component
-  that reads adversarial content must not be the component that can act. Any future widening of
+  verdict, written through the validated writer (step 9)**. This removes the exfiltration leg of the
+  lethal trifecta — the component that reads adversarial content must not be the component that can act. Any future widening of
   this scope requires the trifecta audit in [AGENTS.md](/AGENTS.md) and a PM decision
   ([injection-defenses](/planning/research/injection-defenses.md)).
 - **Advisory, not final.** Your verdict informs; it does not decide. The human PM **Acceptance Gate**
@@ -159,13 +159,45 @@ FAIL — never a clean PASS.) The split is **persisted**, not just narrated (ste
    available, or state `pass-fraction: unknown (no backend)` in kit mode. A high pass-fraction is a
    leniency-drift warning to the PM, not a compliment to the builders
    ([llm-judge-calibration](/planning/research/llm-judge-calibration.md)).
-9. **Persist it** — `save_eval({ initiative_id, run_id, rubric_path, score, verdict, dimensions })`,
-   where `dimensions` is `{ <name>: { score, weight, note, evidence, axis } }` — `evidence` carries
-   the quote/pointer from step 6 (or the string `unverified`), and **`axis` is `"spec"` or
-   `"standards"`** so the two-axis split is persisted, not just narrated. Put the two axis pass/fail
-   summaries in the top-level `note`/report and tag every dimension with its axis. This is what makes
-   the gate self-hosting — the verdict lands in `evals` and surfaces on `v_eval_gate_status`
-   (radar/board).
+9. **Persist it through the validated writer — never by hand.** Which writer depends on where you
+   are running, and **both are validated; neither is a raw append**:
+
+   | you are in | the writer | why |
+   |---|---|---|
+   | **a vendored kit** (`pmos/` in a product repo) | `pmos/scripts/pmos-log.sh eval …` | ships with the kit; writes the kit's `state/evals.jsonl` |
+   | **PMOS-self** (file mode, [D64](/DECISIONS.md)) | `node scripts/record-eval.js --file verdict.json` | writes `planning/runs/evals.jsonl` |
+   | a hosted tenant | the `save_eval` MCP tool | **deprecated for PMOS-self**; does not exist in file mode |
+
+   ```
+   # kit
+   pmos/scripts/pmos-log.sh eval <run_id> <initiative_id> <score> <PASS|PASS-WITH-FINDINGS|FAIL> <rubric_path> [evaluator_model]
+   pmos/scripts/pmos-log.sh eval <run_id> <initiative_id> SKIPPED "<reason>" [rubric_path] [evaluator_model]
+
+   # PMOS-self
+   node scripts/record-eval.js --file verdict.json     # or pipe the JSON on stdin
+   ```
+
+   Both **fail loud**: a rejected verdict exits non-zero with the specific reason and writes nothing,
+   so a malformed record can never light the gate green. `record-eval.js` additionally refuses any
+   sink but the eval ledger — resolved, not by name — which is what keeps a Review-Gate verdict out
+   of the PM's acceptance ledger.
+
+   If the writer your context calls for is not present, **say so in the verdict and stop** — do not
+   hand-append. A ledger written by hand is how a field ends up meaning three things.
+
+   The record carries `{ initiative_id, run_id, rubric_path, score, verdict, evaluator_model,
+   recorded_at, dimensions }`, where `dimensions` is `{ <name>: { score, weight, note, evidence,
+   axis } }` — `evidence` carries the quote/pointer from step 6 (or the string `unverified`), and
+   **`axis` is `"spec"` or `"standards"`** so the two-axis split is persisted, not just narrated. Put
+   the two axis pass/fail summaries in the top-level `note` and tag every dimension with its axis.
+
+   A `SKIPPED` verdict is **declared, not omitted** — it requires `skipped_reason` and carries
+   `score: null`. A skip is an honest record that judging did not happen; it does not close the
+   verification the run owes, and the queue checker (PMOS-self: `scripts/check-verify-queue.js`)
+   will keep reporting the debt.
+
+   This is what makes the gate self-hosting: the verdict lands in the eval ledger and surfaces on the
+   board.
 10. **Hand to the PM.** The Acceptance Gate is theirs, and the PM records the ground-truth `pm_label` to
    `acceptances` — paired against your verdict by `v_calibration` to compute the kappa that calibrates this
    gate ([D40](/DECISIONS.md), [calibration-method](/planning/evals/calibration-method.md)). If the PM
@@ -178,5 +210,6 @@ A short report: **most important finding first**, then the **two axis verdicts (
 one line; Standards: pass/fail — one line)** and the **overall VERDICT** (score vs threshold, under
 the combine rule) with the pass-fraction disclosure, the calibration exemplars used (step 3), the
 numbered defects, and the per-dimension scores **with their evidence quotes/pointers and `axis`
-tag** — followed by the `save_eval` call. Be concrete; cite specifics; if it is genuinely solid, say
+tag** — followed by the verdict record, written through **the writer for your context (step 9)**:
+`pmos/scripts/pmos-log.sh eval …` in a vendored kit, `node scripts/record-eval.js …` in PMOS-self. Be concrete; cite specifics; if it is genuinely solid, say
 so — but only after a real refutation attempt.

package/payload/skills-native/pmos-router/SKILL.md

@@ -21,7 +21,7 @@ lanes and gates that already exist; where it and an authority disagree, the auth
 router is the bug (fix it via the weekly harness scan).
 
 > **Format note:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)).
-> Sources of truth: the AGENTS.md lane list, `.github/scripts/initiative-gate.sh`, D56/D58/D60.
+> Sources of truth: the AGENTS.md lane list, the initiative gate (PMOS-self: `.github/scripts/initiative-gate.sh`; a vendored kit: `pmos/scripts/gate-initiative.sh`), D56/D58/D60.
 
 ## Step 0 — three checks before any route
 

package/workspace/lib/drive-guard.js

@@ -102,16 +102,38 @@ const ALLOWED_DIR_PREFIXES = Object.freeze([
  * its own run is the free zone working as designed, and a fabricated `PM_approved` INSIDE that write
  * is caught by the content guard below, not by refusing the file.
  */
-const ALLOWED_BASENAMES = Object.freeze([
-  'agent-runs.jsonl',
-  'verify-queue.jsonl',
-  'work-items.jsonl',
+/**
+ * RESOLVE BEFORE ALLOWING — each ledger paired with the ONE directory it may live in.
+ *
+ * This was a bare basename list matched with `path.basename` in any directory, and an independent
+ * evaluator walked through it on 2026-08-04 with `/etc/agent-runs.jsonl`,
+ * `/home/user/.ssh/discoveries.md` and `workspace/lib/discoveries.md` — all permitted, because the
+ * name was the whole identity. Worse, the two halves of the allowlist disagreed: the PREFIX half
+ * correctly refused absolute paths while the basename half waved them through, so which rule
+ * happened to match decided whether `/etc/…` was inside the repo.
+ *
+ * A ledger is now its path, not its name.
+ */
+const ALLOWED_FILES = Object.freeze([
+  'planning/runs/agent-runs.jsonl',
+  'planning/runs/verify-queue.jsonl',
+  'planning/runs/work-items.jsonl',
   'discoveries.md',
 ]);
 
+/** Kept for the refusal message only — never for deciding permission. */
+const ALLOWED_BASENAMES = Object.freeze(ALLOWED_FILES.map((f) => path.posix.basename(f)));
+
 /** Named explicitly so the refusal says WHY, rather than "not on the allowlist". Each of these
  *  would otherwise be caught by the allowlist anyway — the value here is the message. */
 const HUMAN_DECISION_SINKS = Object.freeze({
+  // The module argues that a DIRECTORY prefix "would admit the FOURTH ledger somebody adds next year
+  // without anyone deciding to — exactly the class-failure this rewrite exists to close" — and then
+  // allows `planning/evals/` as a prefix, which admits the PM's own override log and any future
+  // planning/evals/*.jsonl. The argument is right; it just was not applied to its own second
+  // directory. These two are the PM's calibration record, not the driver's scratch space.
+  'eval-calibration.md': 'the PM\'s log of every override of an evaluator verdict is the PM\'s (D40)',
+  'calibration-status.md': 'the declared calibration state is the PM\'s to assert, not the driver\'s',
   'acceptances.jsonl': 'the Acceptance Gate is the PM\'s and non-delegable (D12)',
   'evals.jsonl': 'a Review-Gate verdict on the driver\'s own work is self-grading — the driver may not record one (D40)',
   'outcome_checks.jsonl': 'whether the bet paid off is the PM\'s judgement (D57)',
@@ -127,6 +149,167 @@ const HUMAN_DECISION_SINKS = Object.freeze({
  * individually, which is the whole argument for the suite below. */
 const DISPOSITION_RE = /^\s*"?\s*(PROMOTE(D)?|ITERATE(D)?|KILL(ED)?)\b/i;
 
+/**
+ * The leading-token rule above is correct and insufficient, and the measurement says so.
+ *
+ * Anchoring to the value's first token bought the false positive back (`derived from the promoted
+ * prototype` is permitted, rightly) and paid for it in false NEGATIVES nobody counted. Swept over
+ * every disposition-bearing `status:` line in this repo's own planning/initiatives/ on 2026-08-04:
+ * **26 of 30 were permitted**, including four real recorded PM dispositions —
+ *
+ *     status: "CLOSED — disposed PROMOTE by PM wawan 2026-07-28…"
+ *     status: "CLOSED — PROMOTED 2026-07-28…"
+ *     status: "…PM disposition 2026-07-29: ITERATE A…"
+ *     status: "**PM disposition 2026-07-30: ITERATE C**"
+ *
+ * — because each leads with CLOSED, or with the word "PM". A guard validated against six test
+ * strings and never against the corpus it protects. So the leading-token rule stays, and these
+ * value-INTERNAL forms join it: a disposition announced as a disposition, wherever it sits in the
+ * line. Prose that merely mentions a verb still passes, because these require the announcing noun.
+ */
+const DISPOSITION_INTERNAL_RE = new RegExp(
+  '(?:' +
+    'dispositions?\\s*[:=]\\s*|' +          // "disposition: PROMOTE", "PM disposition: ITERATE A"
+    'dispos(?:ed|ition)\\s+(?:to\\s+)?|' +  // "disposed PROMOTE", "disposed to KILL"
+    'disposition\\s+\\S{0,24}?\\s*[:=]\\s*' + // "PM disposition 2026-07-30: ITERATE C"
+  ')' +
+  '\\W{0,4}(PROMOTE(?:D)?|ITERATE(?:D)?|KILL(?:ED)?)\\b',
+  'i');
+
+/**
+ * The third rule, rewritten after independent verification refuted its first form.
+ *
+ * The first attempt keyed on CASE: dispositions are written `PROMOTED`, prose writes "the promoted
+ * prototype". Swept over the corpus it looked perfect — 7 all-caps lines, all 7 genuine, zero false
+ * positives. An independent verifier then pointed out the obvious: **a driver forging a disposition
+ * defeats a case-sensitive guard by not pressing shift.**
+ *
+ *     status: CLOSED — promoted 2026-07-28 by PM wawan     prev=refused  →  mine=PERMITTED
+ *
+ * That is `workspace-doc-editing.md`'s real recorded disposition in lower case, and it was a strict
+ * regression against the module I was fixing — the same veto I wrote the rubric to catch, in the fix
+ * for the round that failed it. It also carried the SAME `KILLED?` typo this file documents itself
+ * catching twenty lines up ("KILLE" plus an optional D never matches a bare `KILL`).
+ *
+ * So case is not the signal. The signal is GRAMMAR: a disposition is the verb used as a verb, and
+ * the false positive this round must preserve is the verb used as an ADJECTIVE or in a PASSIVE
+ * clause — "derived from *the promoted* prototype", "M3 *was killed* off upstream". Both are marked
+ * by a small closed set of words immediately before the verb. Everything else is a disposition,
+ * whatever its case.
+ *
+ * Default refuse, carve out narrowly, and enumerate the carve-out — rather than default permit and
+ * enumerate the catches, which is the denylist shape this whole round exists to remove.
+ */
+const DISPOSITION_VERB = '(?:PROMOTE[SD]?|ITERATE[SD]?|KILL(?:ED|S)?)';
+
+/** Immediately-preceding words that make the verb a modifier or a passive, not an act. */
+const PROSE_LEAD = new Set([
+  'the', 'a', 'an', 'this', 'that', 'these', 'those', 'its', 'their', 'our', 'his', 'her',
+  'was', 'were', 'been', 'being', 'is', 'are', 'be', 'get', 'gets', 'got', 'gotten',
+  'not', 'never', 'unless', 'if', 'when', 'would', 'could', 'should', 'may', 'might',
+]);
+
+/**
+ * True when a status VALUE announces a PM disposition. Case-insensitive by construction; the
+ * carve-out, not the catch, is what is enumerated.
+ */
+function isDisposition(value) {
+  const v = String(value);
+  if (DISPOSITION_RE.test(v) || DISPOSITION_INTERNAL_RE.test(v)) return true;
+  const re = new RegExp(`(^|[^A-Za-z])(${DISPOSITION_VERB})\\b`, 'gi');
+  let m;
+  while ((m = re.exec(v)) !== null) {
+    const before = v.slice(0, m.index + m[1].length);
+    const prior = (before.match(/([A-Za-z']+)[^A-Za-z']*$/) || [])[1];
+    if (prior && PROSE_LEAD.has(prior.toLowerCase())) continue;   // adjectival or passive — prose
+    return true;
+  }
+  return false;
+}
+
+/**
+ * NORMALIZE BEFORE MATCHING — and the reason this rule is written as a rule.
+ *
+ * The predecessor tested `/PM_approved\s*[:=]\s*true/i`: unbounded whitespace. Its replacement — the
+ * "hardening" — tested `/PM_approved\W{0,4}(true|1|yes)/i`, which widened the VALUE side and, without
+ * anyone noticing, capped the SEPARATOR side at four non-word characters. An independent evaluator
+ * measured both modules side by side on 2026-08-04:
+ *
+ *     PM_approved  :  true       old=refused    new=PERMITTED
+ *     PM_approved:      true     old=refused    new=PERMITTED
+ *
+ * A hardening round that shipped a strict regression, on the one predicate whose whole job is to stop
+ * a driver forging the PM's approval. `{"pre_run_contract"  :  {"PM_approved"   :   true}}` written
+ * as text to the allowlisted agent-runs.jsonl JSON.parses to `PM_approved === true`, which
+ * scripts/workflow-state.js accepts as O5 satisfaction.
+ *
+ * The lesson is not "use a bigger budget". Any budget is a denylist of the gaps you thought of, and
+ * the next one is defeated by a form nobody enumerated (the double-stringified payload defeated four
+ * with five escape characters). So: collapse the input to a canonical form FIRST — drop the
+ * characters an encoding can multiply, squeeze whitespace — and only then match, with unbounded
+ * separators. There is no budget to overrun because there is nothing left to pad with.
+ */
+/** Returned when normalization will not settle — the call site treats it as refusal, never as text. */
+const NON_CONVERGENT = '\u0000NON_CONVERGENT\u0000';
+
+function normalizeForMatch(s) {
+  let out = String(s);
+  /* DECODE, do not delete. The first attempt at this stripped backslashes outright — and a literal
+   * tab, which JSON.stringify writes as the two characters `\t`, became the letter `t`:
+   *
+   *     PM_approved<TAB>:<TAB>true   →   "PM_approved\t:\ttrue"   →   PM_approvedt:ttrue
+   *
+   * …which matches nothing, so a tab-separated approval walked straight through the "fix". Caught by
+   * this round's own N-R1 assertion, which is the argument for attempting each form individually.
+   * Escape sequences are DATA and must be decoded to what they denote, never erased.
+   *
+   * Applied repeatedly so that multiply-stringified payloads (the ninth bypass) unwrap layer by
+   * layer rather than one level deep. Bounded, because a fixed point is not guaranteed on hostile
+   * input and an unbounded loop here is a denial of service. */
+  /* ONE left-to-right pass per round, not four independent global replaces.
+   *
+   * The four-replace form was itself defective, and an independent verifier found it: because
+   * `JSON.stringify` DOUBLES backslashes, the `\\u....` replace consumed the second backslash and
+   * left the first dangling in front of the decoded letter, which the `\\[tnrfvb0]` replace then
+   * ATE as a control char — turning `PM_approved` into `PM_app o ed` and permitting the write. The
+   * same `\t` → `t` corruption as the first attempt, one rule to the right, because the rules could
+   * see each other's output mid-pass. A single scanner consumes each escape exactly once.
+   *
+   * Loops to a FIXED POINT rather than a fixed count. The earlier `i < 4` was a budget — and this
+   * file argues at length that a budget is a denylist of the gaps you thought of; five layers of
+   * stringification walked past it. The cap here is a non-termination guard, not a budget, and
+   * hitting it means the input is still changing after 16 rounds, which is not something a
+   * legitimate write does: it fails CLOSED at the call site. */
+  const decodeOnce = (s) => {
+    let r = '';
+    for (let i = 0; i < s.length; i++) {
+      if (s[i] !== '\\') { r += s[i]; continue; }
+      const n = s[i + 1];
+      if (n === undefined) { r += ' '; break; }
+      if (n === 'u' && /^[0-9a-fA-F]{4}$/.test(s.slice(i + 2, i + 6))) {
+        r += String.fromCharCode(parseInt(s.slice(i + 2, i + 6), 16)); i += 5;
+      } else if (n === 'x' && /^[0-9a-fA-F]{2}$/.test(s.slice(i + 2, i + 4))) {
+        r += String.fromCharCode(parseInt(s.slice(i + 2, i + 4), 16)); i += 3;
+      } else if ('tnrfvb0'.includes(n)) { r += ' '; i += 1; }
+      else { r += n; i += 1; }
+    }
+    return r;
+  };
+  let converged = false;
+  for (let i = 0; i < 16; i++) {
+    const before = out;
+    out = decodeOnce(out);
+    if (out === before) { converged = true; break; }
+  }
+  if (!converged) return NON_CONVERGENT;
+  return out
+    .replace(/["'`]/g, '')     // quoting is packaging, not content
+    .replace(/\s+/g, ' ');     // any run of whitespace is one space
+}
+
+/** Unbounded separators, by construction. Applied only to normalized text. */
+const APPROVAL_RE = /PM_approved\s*[:=]\s*(true|1|yes)\b/i;
+
 /** Truthy-tolerant: an approval the PM never gave is what is being refused; its JSON type is not the
  *  point. Closes bypass 2. */
 const TRUTHY = new Set([true, 1, 'true', 'TRUE', 'True', 'yes', 'YES', '1']);
@@ -145,22 +328,53 @@ function carriesApproval(value, seen) {
   return false;
 }
 
-/** True when a `status`/`disposition` key ANYWHERE carries a leading disposition token (bypass 5). */
+/**
+ * True when a `status`/`disposition` key ANYWHERE carries a disposition (bypass 5).
+ *
+ * Three type-loose gaps closed here, each measured on 2026-08-04: the key test was case-SENSITIVE
+ * (`Status` walked past), the value test required `typeof v === 'string'` (so `status: ['PROMOTED']`
+ * walked past), and a Buffer serialized to a byte array invisible to every scan.
+ */
 function carriesDisposition(value, seen) {
   const s = seen || new Set();
   if (!isObj(value) || s.has(value)) return false;
   s.add(value);
   for (const [k, v] of Object.entries(value)) {
-    if ((k === 'status' || k === 'disposition') && typeof v === 'string' && DISPOSITION_RE.test(v)) return true;
+    const isStatusKey = k.toLowerCase() === 'status' || k.toLowerCase() === 'disposition';
+    if (isStatusKey) {
+      // A status value may be a string, a Buffer, or a list of candidate values. All are inspected.
+      const candidates = Array.isArray(v) ? v : [v];
+      for (const c of candidates) {
+        if (typeof c === 'string' && isDisposition(c)) return true;
+        if (Buffer.isBuffer(c) && isDisposition(c.toString('utf8'))) return true;
+      }
+    }
+    if (Buffer.isBuffer(v)) continue;   // a Buffer's numeric indices are not an object graph
     if (carriesDisposition(v, s)) return true;
   }
   return false;
 }
 
+/**
+ * Repo-relative, canonical, or nothing.
+ *
+ * `path.posix.normalize` collapses `.` and `..` properly instead of the old substring test, which
+ * both over-refused (a legitimate `draft..v2.md`) and under-thought the problem. The backslash
+ * rewrite is gone: on POSIX a backslash is an ordinary filename character, and rewriting it let the
+ * single root-level file `planning\prd\x.md` pose as a file inside `planning/prd/`.
+ */
 function onAllowlist(file) {
-  const norm = String(file).replace(/\\/g, '/').replace(/^\.\//, '');
-  if (norm.includes('..')) return false;                 // no traversal out of an allowed directory
-  if (ALLOWED_BASENAMES.includes(path.basename(norm))) return true;
+  const raw = String(file);
+  if (path.posix.isAbsolute(raw) || path.win32.isAbsolute(raw)) return false;  // never outside the repo
+  const norm = path.posix.normalize(raw.replace(/^\.\//, ''));
+  if (norm === '.' || norm.startsWith('../')) return false;                    // escaped the repo root
+  if (norm.split('/').includes('..')) return false;
+  if (ALLOWED_FILES.includes(norm)) return true;
+  /* The prefix half admits DRAFT ARTIFACTS, never ledgers. Without this the module's own
+   * fourth-ledger argument fails against its own second directory: `planning/evals/anything.jsonl`
+   * was permitted, so the next append-only ledger anyone puts there is admitted by default —
+   * "exactly the class-failure this rewrite exists to close", as the comment above says. */
+  if (/\.jsonl$/i.test(norm)) return false;
   return ALLOWED_DIR_PREFIXES.some((p) => norm.startsWith(p));
 }
 
@@ -179,6 +393,20 @@ function assertWritable(req) {
     throw new ForbiddenWrite('a request with no target', 'a write request must name its `file` — refused (fail-closed)');
   }
 
+  /* A Buffer or TypedArray supplied AS the payload is bytes the writer will put on disk verbatim,
+   * and JSON.stringify renders it `{"type":"Buffer","data":[80,77,…]}` — invisible to the text scan
+   * and to the object walk alike. Both were handled NESTED and neither at the top level, which an
+   * independent verifier walked straight through with
+   * `payload: Buffer.from(JSON.stringify({pre_run_contract:{PM_approved:true}}))`. Decode to text
+   * and adjudicate it as text. */
+  if (Buffer.isBuffer(req.payload) || ArrayBuffer.isView(req.payload)) {
+    const asText = Buffer.from(
+      ArrayBuffer.isView(req.payload) && !Buffer.isBuffer(req.payload)
+        ? Buffer.from(req.payload.buffer, req.payload.byteOffset, req.payload.byteLength)
+        : req.payload).toString('utf8');
+    return assertWritable({ file: req.file, text: `${req.text || ''}\n${asText}` });
+  }
+
   const why = HUMAN_DECISION_SINKS[path.basename(req.file)];
   if (why) throw new ForbiddenWrite(path.basename(req.file), why);
 
@@ -197,7 +425,12 @@ function assertWritable(req) {
     throw new ForbiddenWrite('an unserialisable payload',
       'a payload that cannot be inspected cannot be permitted — refused (fail-closed)');
   }
-  if (/PM_approved\W{0,4}(true|1|yes)/i.test(serialized) || carriesApproval(req.payload)) {
+  const normalized = normalizeForMatch(serialized);
+  if (normalized === NON_CONVERGENT) {
+    throw new ForbiddenWrite('an input that will not normalize',
+      'a payload whose escaping does not settle cannot be inspected — refused (fail-closed)');
+  }
+  if (APPROVAL_RE.test(normalized) || carriesApproval(req.payload)) {
     throw new ForbiddenWrite('pre_run_contract.PM_approved',
       'the contract is the PM\'s to approve before any build (D16, AGENTS.md §4)');
   }
@@ -209,11 +442,34 @@ function assertWritable(req) {
     throw new ForbiddenWrite('a disposition', 'promote/iterate/kill is the PM\'s (D60 step 7)');
   }
   if (typeof req.text === 'string') {
-    for (const line of req.text.split('\n')) {
-      const m = /^\s*(?:status|disposition)\s*:\s*(.*)$/i.exec(line);
-      if (m && DISPOSITION_RE.test(m[1])) {
+    // Split on /\r?\n/, not '\n'. The old split left a trailing '\r' on every CRLF line, and the
+    // matcher's `$` anchor (without the `m` flag) then matched nothing at all — a CRLF document
+    // sailed through the raw-text check entirely.
+    for (const line of req.text.split(/\r?\n/)) {
+      /* Markdown prefixes are how a status line is ACTUALLY written in the driver's own sinks —
+       * `- status:`, `**status:**`, `> status:`, `| status |` — and the old anchor allowed only
+       * leading whitespace, so every one of them walked past the check. */
+      const m = /^[\s>*\-+#|]*\**\s*(?:status|disposition)\**\s*[:|]\s*(.*?)\s*\|?\s*$/i.exec(line);
+      if (m && isDisposition(m[1])) {
         throw new ForbiddenWrite('a disposition', 'promote/iterate/kill is the PM\'s (D60 step 7)');
       }
+      // The raw and structured paths must agree. A JSONL line supplied as `text` was permitted while
+      // the identical object supplied as `payload` was refused — the same content, two verdicts,
+      // decided by which field it arrived in.
+      const t = line.trim();
+      if (t.startsWith('{') || t.startsWith('[')) {
+        let parsed;
+        try { parsed = JSON.parse(t); } catch { parsed = undefined; }
+        if (parsed !== undefined) {
+          if (carriesDisposition(parsed)) {
+            throw new ForbiddenWrite('a disposition', 'promote/iterate/kill is the PM\'s (D60 step 7)');
+          }
+          if (carriesApproval(parsed)) {
+            throw new ForbiddenWrite('pre_run_contract.PM_approved',
+              'the contract is the PM\'s to approve before any build (D16, AGENTS.md §4)');
+          }
+        }
+      }
     }
   }
   return true;

package/workspace/lib/engine/workflow-state.js

@@ -859,14 +859,48 @@ function computeWorkflow(id, opts) {
   // ── review ─ the Review Gate's verdict, where the lane has a rubric ──────────────────────────
   const evals = readJsonl(path.join(L.runsDir, 'evals.jsonl')).filter((e) => e && e.initiative_id === id);
   {
-    if (effLane === 'chore' || effLane === 'prototype') {
-      steps.push(step('review', 'review', 'na', effLane === 'prototype'
-        ? 'leg A is grilled as dialogue, never scored (D60)'
-        : 'chore lane carries no rubric (D56)'));
+    /* The rung reads the RUBRIC, not the lane.
+     *
+     * It keyed on `lane` alone, so a chore that deliberately carries a rubric could never surface
+     * its Review Gate — the ladder said "chore lane carries no rubric (D56)" while a SKIPPED verdict
+     * sat in evals.jsonl unread. That is how `guard-and-ledger-hardening`, a chore whose own record
+     * argues "blast radius overrides lane" and which carried a rubric on purpose, reached `accept`
+     * with the gate never run. The board could not show what the ledger already knew.
+     *
+     * A prototype is still never scored — D60 grills leg A as dialogue, and that is a property of
+     * the lane, not of whether someone attached a rubric. Every other lane defers to the artifact. */
+    const declaresRubric = !!String(fm.rubric_path || '').trim();
+    /* EVERY lane defers to the artifact — the first version said so in the comment and applied it
+     * only to `chore`, so a discovery or incident initiative with no rubric (legitimate under D56)
+     * showed a permanent `no Review-Gate verdict recorded`: a rung it could never satisfy. The lanes
+     * that carry no rubric by design are named once, here. */
+    const RUBRIC_OPTIONAL = ['chore', 'discovery', 'incident', 'content'];
+    if (effLane === 'prototype') {
+      steps.push(step('review', 'review', 'na', 'leg A is grilled as dialogue, never scored (D60)'));
+    } else if (RUBRIC_OPTIONAL.includes(effLane) && !declaresRubric && !evals.length) {
+      steps.push(step('review', 'review', 'na', `${effLane} lane carries no rubric (D56)`));
     } else if (evals.length) {
       const last = evals[evals.length - 1];
-      steps.push(step('review', 'review', 'done',
-        `${last.verdict}${last.score != null ? ` (${last.score})` : ''} — advisory until calibrated per evaluator model (D40)`));
+      const verdict = String(last.verdict || '').toUpperCase();
+      const label = `${last.verdict}${last.score != null ? ` (${last.score})` : ''} — advisory until calibrated per evaluator model (D40)`;
+      /* A SKIPPED gate is NOT a satisfied gate, and a FAIL is emphatically not one.
+       *
+       * This rung rendered both as a green ✓, which is the watermelon this repo names as its own
+       * failure mode: the board said the Review Gate was done over a row that says judging never
+       * happened. Thirteen initiatives currently render `✓ review` over a SKIPPED verdict, and the
+       * fix that made a chore's gate visible ADDED one. The module's own rule, repeated in three
+       * files — "a skip is an honest RECORD that verification did not happen; it is not
+       * verification" — now applies to the surface that reports it. */
+      if (verdict === 'SKIPPED') {
+        steps.push(step('review', 'review', 'pending', label,
+          'the gate was skipped, so it is still owed — commission an independent evaluator and record a real verdict',
+          { rule: 'R3' }));
+      } else if (verdict === 'FAIL') {
+        steps.push(step('review', 'review', 'blocked', label,
+          'the Review Gate FAILED — remediate the findings and record a new verdict', { rule: 'R3' }));
+      } else {
+        steps.push(step('review', 'review', 'done', label));
+      }
     } else {
       steps.push(step('review', 'review', 'pending', 'no Review-Gate verdict recorded',
         'score the build against the rubric (build-skills/evaluator.skill), then append to evals.jsonl',

package/workspace/server.js

@@ -830,9 +830,20 @@ function searchIndex(root) {
   const hit = searchIndexCache.get(root);
   if (hit && now - hit.at < SEARCH_INDEX_TTL_MS) return hit;
   const files = [];
-  let truncated = false;
+  let depthCut = false;    // some branch was too deep — a LOCAL fact
+  let budgetCut = false;   // the file budget ran out — a GLOBAL stop
+  /* Two truncation causes, two flags, and only ONE of them stops the walk.
+   *
+   * They used to share `truncated`, and the guard at the top of `walk` read it — so the first branch
+   * that hit SEARCH_MAX_DEPTH aborted every not-yet-visited subdirectory in the whole tree. Measured
+   * by an independent evaluator on 2026-08-04: 51 files at depth <= 1, `scanned: 50`, an entire
+   * in-bound sibling directory lost because an unrelated deep branch tripped the cap first — and
+   * which sibling survived depended on readdir order.
+   *
+   * Depth is a bound on ONE path. The file budget is a bound on the WHOLE walk. Only the second is
+   * a reason to stop walking. */
   (function walk(dir, rel, depth) {
-    if (truncated) return;
+    if (budgetCut) return;
     let ents = [];
     try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
     for (const e of ents) {
@@ -840,16 +851,17 @@ function searchIndex(root) {
       const full = path.join(dir, e.name);
       const r = rel ? rel + '/' + e.name : e.name;
       if (e.isDirectory()) {
-        // Depth is a bound like any other: reaching it means files below were NOT looked at.
+        // Depth is a bound like any other: reaching it means files below were NOT looked at —
+        // but only BELOW HERE. Siblings elsewhere in the tree are still in bounds.
         if (depth < SEARCH_MAX_DEPTH) walk(full, r, depth + 1);
-        else truncated = true;
+        else depthCut = true;
       } else if (e.isFile()) {
-        if (files.length >= SEARCH_MAX_FILES) { truncated = true; return; }
+        if (files.length >= SEARCH_MAX_FILES) { budgetCut = true; return; }
         files.push({ path: r, name: e.name, dir: rel, kind: preview.previewKind(e.name) });
       }
     }
   })(root, '', 0);
-  const entry = { at: now, files, truncated, scanned: files.length };
+  const entry = { at: now, files, truncated: depthCut || budgetCut, scanned: files.length };
   searchIndexCache.set(root, entry);
   return entry;
 }
@@ -882,15 +894,51 @@ function searchWorkspace(root, query, limit) {
   const seen = new Set();
   let overflow = false;                       // more matched than `cap` — a REAL cut, not a coincidence
 
+  /* `openable` means ONE thing: /api/doc will serve this. So it asks /api/doc's own reader rather
+   * than re-deciding from the extension.
+   *
+   * It used to be `SEARCH_OPENABLE.has(f.kind)` — extension only — while `readTextDoc` applies a
+   * SECOND refusal the search never replicated: a NUL byte anywhere in the file. A `.txt` holding
+   * binary therefore rendered as a clickable hit that opened a tab printing a read failure, which
+   * is the PRD's own constraint 6 violated ("the result says so rather than letting the PM click
+   * into a predictable failure"). An independent evaluator reproduced it on 2026-08-04:
+   *
+   *     hit masquerade.txt  kind=text openable=true  ->  /api/doc status=404
+   *
+   * Two notions of "servable" that can disagree is the defect; one definition, consulted, is the
+   * fix. Bounded by `cap` (<= 200 hits), and only for path matches — a content match already read
+   * the body and proved it NUL-free. */
+  const servable = (rel) => {
+    try {
+      /* SIZE-BOUNDED. `readTextDoc` has no size limit, so consulting it for every path hit read up
+       * to `cap` (200) WHOLE files on the server's only thread — measured by an independent verifier
+       * at 285 ms for 200 × 1 MB, and 5.7 s plus a 600 MB read for one oversized file. The comment
+       * twelve lines above SEARCH_CONTENT_BYTES says a bigger file is "path-matched only, never read
+       * whole"; the fix quietly broke that. A file past the content budget reports NOT openable —
+       * the honest answer is "we did not look", and the safe rendering of that is a hit the PM
+       * cannot click into an unknown. */
+      const st = fs.statSync(path.join(root, rel));
+      if (!st.isFile() || st.size > SEARCH_CONTENT_BYTES) return false;
+      return readTextDoc(root, rel) !== null;
+    } catch { return false; }
+  };
+
   for (const f of idx.files) {
     if (!f.path.toLowerCase().includes(needle)) continue;
     seen.add(f.path);
     if (hits.length >= cap) { overflow = true; break; }
-    hits.push({ ...f, match: 'path', line: null, snippet: null, openable: SEARCH_OPENABLE.has(f.kind) });
+    hits.push({ ...f, match: 'path', line: null, snippet: null,
+      openable: SEARCH_OPENABLE.has(f.kind) && servable(f.path) });
   }
 
   let read = 0;
   let contentCut = false;
+  /* When path matches overflow the cap, the ENTIRE content pass is skipped — so every body in the
+   * workspace went unread. `content_truncated` reported `false` alongside `content_scanned: 0`,
+   * contradicting the flag's own documented meaning ("every file was named, but not every body was
+   * read"). Masked by `truncated: true`, so the PM was warned — but a flag that disagrees with
+   * reality is the failure the two-flag split exists to prevent. */
+  if (overflow) contentCut = true;
   if (!overflow) {
     for (const f of idx.files) {
       if (seen.has(f.path) || !SEARCH_OPENABLE.has(f.kind)) continue;
@@ -906,7 +954,9 @@ function searchWorkspace(root, query, limit) {
       if (text.indexOf(String.fromCharCode(0)) !== -1) continue;    // binary masquerading as text — never scanned
       const at = text.toLowerCase().indexOf(needle);
       if (at === -1) continue;
-      if (hits.length >= cap) { overflow = true; break; }
+      // The cap biting HERE also leaves bodies unread — the sibling branch of the same defect, and
+      // the half the first fix missed.
+      if (hits.length >= cap) { overflow = true; contentCut = true; break; }
       const before = text.slice(0, at);
       const lineNo = before.split('\n').length;
       const lineStart = before.lastIndexOf('\n') + 1;