doctrina-cli 0.4.0 → 0.8.0

package/README.md

@@ -3,7 +3,7 @@
 > CLI for the Doctrina framework. The package is published as
 > `doctrina-cli`; the executable it installs is `doctrina`.
 
-**Status:** v0.4.0 — current release. Zero runtime dependencies
+**Status:** v0.6.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install
@@ -22,11 +22,16 @@ Requires Node.js 20.12 or later.
 doctrina init                              scaffold AGENTS.md + .doctrina/ in cwd
 doctrina intake [<file>]                   store the full description + bootstrap playbook (clarification gate)
 doctrina work "<prompt>"                   brief prompt -> scaffolded change + work playbook (clarification gate)
+doctrina work --resume <id>                reprint an open change's playbook (no new change)
+doctrina work --from-diff                  backfill a spec from working-tree changes (code-first)
+doctrina work "<prompt>" --chore           spec-less chore (infra/docs/build): no spec-delta steps
 doctrina spec new <capability>             create a capability spec
 doctrina spec list                         list specs with version, status, size
+doctrina spec set <cap> [--bump ...]       edit spec headers/criterion + resync index (no lockstep)
 doctrina change new <id> "<title>"         open a change proposal
-doctrina change apply <id>                 apply spec deltas (ADDED/REMOVED auto)
+doctrina change apply <id>                 apply spec deltas (ADDED/REMOVED auto; MODIFIED ops block applies)
 doctrina change archive <id>               archive an applied change
+doctrina change abandon <id>               delete an open change + its index entry (ledgered)
 doctrina change diff <id>                  preview spec deltas (line diff for MODIFIED)
 doctrina contract new <name>               own the integration surface (ports, env, interfaces)
 doctrina contract check                    verify port collisions, env drift, referenced specs
@@ -42,10 +47,11 @@ doctrina analyze <change-id>               inspect a change folder before applyi
 doctrina clarify <path>                    smell-test a Markdown file for ambiguity (--all: tree)
 doctrina context [<capability>]            print the context pack in read order (--concat)
 doctrina search <term> [...]               search artifacts, grouped by category (ranked)
-doctrina validate                          schema + artifact-existence checks
-doctrina coverage                          acceptance criteria with linked evidence (--strict gates)
+doctrina validate                          schema + artifact-existence + index-drift checks (--fix rebuilds)
+doctrina coverage                          acceptance criteria with linked evidence (--strict gates; skips = conditional)
 doctrina trace                             intent provenance: product intent -> specs (--strict gates)
 doctrina verify                            run project typecheck/test/build checks (the real gate)
+doctrina verify --clean                    reproducibility lint: clean-checkout footguns (dist/codegen)
 doctrina templates list                    enumerate shipped templates
 doctrina templates check                   compare project against recommended template shape
 doctrina templates update                  additive fixer for check findings (preview; --write applies)
@@ -92,10 +98,17 @@ For each spec delta found under `.doctrina/changes/<id>/specs/`:
 - **ADDED:** writes the delta body to the target spec; refuses if the
   target already exists.
 - **REMOVED:** deletes the target spec.
-- **MODIFIED:** prints a manual-merge pointer and does not write. The
-  user merges the delta into the target spec by hand. This is
-  deliberate; auto-merging is the kind of implicit decision Doctrina
-  avoids.
+- **MODIFIED:** when the delta carries a fenced ` ```ops ` block
+  (`set-header` / `bump-version` / `set-criterion` / `replace-criterion`
+  / `append-criterion`), applies it mechanically to the target spec — all
+  ops or none — and regenerates the index (ADR 0007). Without an ops
+  block it prints a manual-merge pointer and does not write: auto-merging
+  arbitrary prose is the kind of implicit decision Doctrina avoids.
+
+On any spec write, the index is rebuilt from the tree so it never drifts
+from the applied spec. `doctrina change abandon <id>` is the inverse of
+`change new`: it deletes an open change and its index entry and ledgers
+the abandonment.
 
 ## `validate` checks
 
@@ -113,7 +126,9 @@ For each spec delta found under `.doctrina/changes/<id>/specs/`:
 12. Skills carry the required frontmatter triple (`name`, `description`, `when`).
 13. Skills are ≤ 200 lines (warns at > 150).
 14. Each skill's `name:` matches its filename slug.
-15. Each spec's `Version:` header matches the version in `index.json` (drift warn).
+15. Indexed artifact metadata (spec/decision/change/contract) matches its
+    file — a mismatch is an **error** so a green `validate` can't hide the
+    drift `index rebuild --check` would catch (G5; `validate --fix` rebuilds).
 16. Each skill's frontmatter description matches `index.json` (drift warn; `skill sync` fixes).
 17. EARS grammar shape per section in specs declaring `## Requirements (EARS)` (warn).
 18. Nested `AGENTS.md` files obey the root size caps (warn > 150, error > 200).
@@ -123,12 +138,16 @@ For each spec delta found under `.doctrina/changes/<id>/specs/`:
 21. Accepted ADRs anchor to reality via `Evidence:` and/or `Landed:`; cited
     paths must exist on disk (drift warn).
 
-Exit code: 0 if no errors (warnings allowed), 1 otherwise.
+Exit code: 0 if no errors (warnings allowed), 1 otherwise. `--fix`
+regenerates `index.json` from the tree before validating.
 
 Two related read-only reports gate separately: `doctrina coverage`
-(each acceptance criterion cites a real test) and `doctrina trace`
-(each product intent has a capability, each capability traces to an
-intent). Both exit 1 under `--strict` for CI.
+(each acceptance criterion cites a real test; a criterion proven only by
+a skipped suite is `conditional` and fails `--strict`) and `doctrina
+trace` (each product intent has a capability, each capability traces to
+an intent). Both exit 1 under `--strict` for CI. `doctrina verify
+--clean` statically lints for clean-checkout footguns (a build-dir entry
+point with no `prepare`; a Prisma dep with no generate on install).
 
 ## Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.4.0",
+  "version": "0.8.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [

package/src/commands/change.js

@@ -4,12 +4,14 @@ import { exists, isDir, lineCount, mkdirp, move, read, relPath, remove, walk, wr
 import { diffLines, formatUnified } from "../lib/diff.js";
 import { locateTemplatesDir, loadTemplateTree, materialiseEntry } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
+import { deriveIndex } from "../lib/scan.js";
+import { extractOps, applyOps } from "../lib/spec-ops.js";
 import { today } from "../lib/dates.js";
-import { flagBool } from "../lib/args.js";
+import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
-const SUBCOMMANDS = ["new", "apply", "archive", "diff"];
+const SUBCOMMANDS = ["new", "apply", "archive", "diff", "abandon"];
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -22,6 +24,8 @@ export async function run(positional, flags) {
       return changeArchive(positional.slice(1), flags);
     case "diff":
       return changeDiff(positional.slice(1), flags);
+    case "abandon":
+      return changeAbandon(positional.slice(1), flags);
     default:
       console.error(c.red("error:") + ` unknown change subcommand "${sub ?? ""}"`);
       const guess = suggest(sub, SUBCOMMANDS);
@@ -45,6 +49,11 @@ function changeNew(args, flags) {
   }
 
   const force = flagBool(flags, "force", false);
+  // A chore is a spec-less change (infra / docs / build / migration) — review
+  // G9. It runs the full proposal → apply → archive → ledger lifecycle (so the
+  // history shows it) without forcing a fake spec delta. The empty specs/ dir
+  // is kept so `change apply`'s zero-delta path flips it to applied unchanged.
+  const chore = flagBool(flags, "chore", false) || flagBool(flags, "no-spec", false);
   const projectRoot = process.cwd();
   ensureDoctrinaProject(projectRoot);
 
@@ -66,14 +75,29 @@ function changeNew(args, flags) {
   }
   mkdirp(path.join(changeDir, "specs"));
 
+  // Stamp the proposal so a chore is honest in the artifact, not just the CLI.
+  if (chore) {
+    const proposalPath = path.join(changeDir, "proposal.md");
+    if (exists(proposalPath)) {
+      const txt = read(proposalPath);
+      const updated = txt.replace(/^(-\s+\*\*Affects specs:\*\*).*$/m, "$1 (none — chore)");
+      if (updated !== txt) write(proposalPath, updated, { force: true });
+    }
+  }
+
   const index = idx.load(projectRoot);
   idx.addChange(index, { id, title, path: `.doctrina/changes/${id}`, status: "proposed", opened: date });
   idx.touch(index, date);
   idx.save(projectRoot, index);
 
   console.log("");
-  console.log(c.bold("Change opened.") + " Add spec deltas under " +
-    c.cyan(`.doctrina/changes/${id}/specs/<capability>/delta.md`));
+  if (chore) {
+    console.log(c.bold("Chore opened.") + " No spec deltas expected — implement, check the tasks, then " +
+      c.cyan(`doctrina change apply ${id}`) + " and " + c.cyan(`doctrina change archive ${id}`) + ".");
+  } else {
+    console.log(c.bold("Change opened.") + " Add spec deltas under " +
+      c.cyan(`.doctrina/changes/${id}/specs/<capability>/delta.md`));
+  }
   return 0;
 }
 
@@ -133,8 +157,30 @@ function changeApply(args, _flags) {
       writes += 1;
       console.log(c.green("applied[REMOVED]") + ` ${relPath(projectRoot, targetPath)}`);
     } else if (op === "MODIFIED") {
-      console.log(c.yellow("manual[MODIFIED]") + ` merge ${relPath(projectRoot, deltaPath)} into ${relPath(projectRoot, targetPath)} by hand`);
-      manual += 1;
+      // A MODIFIED delta is applied mechanically when it carries a structured
+      // `ops` block (set-header / bump-version / set-criterion / ...; F3);
+      // otherwise it falls back to the historical manual-merge pointer, so
+      // prose deltas keep working unchanged.
+      const ops = extractOps(text);
+      if (ops.length === 0) {
+        console.log(c.yellow("manual[MODIFIED]") + ` merge ${relPath(projectRoot, deltaPath)} into ${relPath(projectRoot, targetPath)} by hand (no ops block)`);
+        manual += 1;
+      } else if (!exists(targetPath)) {
+        console.error(c.red("error:") + ` MODIFIED delta targets missing spec ${relPath(projectRoot, targetPath)}`);
+        errors += 1;
+      } else {
+        const result = applyOps(read(targetPath), ops);
+        if (result.errors.length > 0) {
+          console.error(c.red("error:") + ` ${result.errors.length} operation error${result.errors.length === 1 ? "" : "s"} in ${rel} — spec left untouched:`);
+          for (const e of result.errors) console.error(`  - ${e}`);
+          errors += 1;
+        } else {
+          write(targetPath, result.text, { force: true });
+          writes += 1;
+          console.log(c.green("applied[MODIFIED]") + ` ${relPath(projectRoot, targetPath)} (${result.applied.length} op${result.applied.length === 1 ? "" : "s"})`);
+          for (const s of result.applied) console.log(c.gray(`    · ${s}`));
+        }
+      }
     } else {
       console.error(c.red("error:") + ` unknown Operation "${op}" in ${rel}`);
       errors += 1;
@@ -161,38 +207,18 @@ function changeApply(args, _flags) {
     }
   }
 
-  // Update the index when specs changed (ADDED/REMOVED) and/or the proposal
-  // flipped to applied. The change entry's status must mirror the proposal —
-  // the same value `index rebuild` derives from the file — or the index
-  // drifts from the tree in the apply→archive window (caught by
-  // `index rebuild --check`, e.g. in the pre-commit hook).
+  // Update the index whenever specs changed (ADDED / REMOVED / MODIFIED-ops)
+  // or the proposal flipped to applied. The files are the source of truth, so
+  // rather than patch entry by entry — the old path that let a spec's
+  // version/implementation text drift from the index, and forced a manual
+  // lockstep bump (F3 / G5 / G7 / G8) — the index is rebuilt from the
+  // now-updated tree in one shot. This keeps `index rebuild --check` green
+  // immediately after apply.
   if (writes > 0 || flippedToApplied) {
-    const index = idx.load(projectRoot);
-    if (writes > 0) {
-      for (const deltaPath of deltaFiles) {
-        const text = read(deltaPath);
-        const op = parseOperation(text);
-        const capability = parseCapabilityFromDelta(text, deltaPath);
-        if (!capability) continue;
-        if (op === "ADDED") {
-          idx.addSpec(index, {
-            id: capability,
-            path: `.doctrina/specs/${capability}/spec.md`,
-            status: "active",
-            version: "0.1.0",
-            last_updated: date,
-          });
-        } else if (op === "REMOVED") {
-          idx.removeSpec(index, capability);
-        }
-      }
-    }
-    if (flippedToApplied) {
-      const entry = index.artifacts.changes.find((ch) => ch.id === id);
-      if (entry) entry.status = "applied";
-    }
-    idx.touch(index, date);
-    idx.save(projectRoot, index);
+    const current = idx.load(projectRoot);
+    const derived = deriveIndex(projectRoot, current);
+    derived.last_updated = date;
+    idx.save(projectRoot, derived);
   }
 
   console.log("");
@@ -305,6 +331,52 @@ function changeArchive(args, flags) {
   return 0;
 }
 
+// Abandon an open change: delete the folder AND the index entry in one step,
+// and record the abandonment in the ledger so the history shows the dead end
+// instead of a silent gap. This is the missing inverse of `change new` — the
+// review had to delete a stray folder and hand-edit index.json (G6).
+function changeAbandon(args, flags) {
+  const id = args[0];
+  if (!id) {
+    console.error(c.red("error:") + " change abandon requires <id>");
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
+  if (!isDir(changeDir)) {
+    console.error(c.red("error:") + ` change "${id}" not found at ${relPath(projectRoot, changeDir)}`);
+    return 1;
+  }
+
+  const reason = flagString(flags, "reason") ?? "";
+  const date = today();
+
+  remove(changeDir);
+  console.log(c.green("removed") + ` ${relPath(projectRoot, changeDir)}`);
+
+  // Ledger line so the abandonment is part of the visible history.
+  const ledgerPath = path.join(projectRoot, ".doctrina", "changes", "archive", "LEDGER.md");
+  if (!exists(ledgerPath)) {
+    write(ledgerPath,
+      "# Change ledger\n\n" +
+      "One line per archived change, newest last. Appended by\n" +
+      "`doctrina change archive`; edit freely, the CLI only appends.\n\n");
+  }
+  const reasonSuffix = reason ? ` — ${reason}` : "";
+  write(ledgerPath, read(ledgerPath) + `- ${date} — ${id} — abandoned${reasonSuffix}\n`, { force: true });
+  console.log(c.green("ledger") + ` +1 line in ${relPath(projectRoot, ledgerPath)}`);
+
+  // Drop the change entry; rebuild from the tree so nothing drifts.
+  const current = idx.load(projectRoot);
+  const derived = deriveIndex(projectRoot, current);
+  derived.last_updated = date;
+  idx.save(projectRoot, derived);
+  console.log(c.green("indexed") + ` change "${id}" removed from index.json`);
+  return 0;
+}
+
 function changeDiff(args, _flags) {
   const id = args[0];
   if (!id) {
@@ -448,13 +520,31 @@ Usage: doctrina change <subcommand> [args]
 
 Subcommands:
   new <id> "<title>"     Open a new change proposal at .doctrina/changes/<id>/
-  apply <id>             Apply spec deltas (ADDED writes, REMOVED deletes, MODIFIED is manual)
+                         (--chore / --no-spec: a spec-less change for infra /
+                         docs / build that still gets a proposal + ledger)
+  apply <id>             Apply spec deltas: ADDED writes, REMOVED deletes,
+                         MODIFIED with an \`\`\`ops block is applied mechanically
+                         (set-header / bump-version / set-criterion / ...),
+                         MODIFIED without one prints a manual-merge pointer.
+                         On any spec write the index is rebuilt from the tree.
   archive <id>           Move the change to .doctrina/changes/archive/YYYY-MM-DD-<id>/
+  abandon <id>           Delete an open change folder and its index entry, and
+                         record the abandonment in the ledger ([--reason "..."]).
   diff <id>              Preview every spec delta: line diff for MODIFIED,
                          summary for ADDED/REMOVED. Read-only.
 
+A MODIFIED delta may carry a fenced operations block that \`apply\` executes:
+  \`\`\`ops
+  set-header Implementation: verified — durable adapter (\`src/db.ts\`)
+  bump-version minor
+  set-criterion 1: verified
+  append-criterion [unverified] new signal — verified by \`test/x.test.ts\`
+  \`\`\`
+
 Options:
   --force                Overwrite existing files (where applicable)
+  --chore, --no-spec     With new, open a spec-less chore change
+  --reason "<text>"      With abandon, the reason recorded in the ledger
 `;
 
 // Re-export parsers so scan.js (index rebuild) can reuse them, and the

package/src/commands/close.js

@@ -0,0 +1,104 @@
+import path from "node:path";
+import process from "node:process";
+import { exists, isFile } from "../lib/fs-ops.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import * as analyze from "./analyze.js";
+import * as change from "./change.js";
+import * as verify from "./verify.js";
+import * as coverage from "./coverage.js";
+import * as trace from "./trace.js";
+import * as validate from "./validate.js";
+
+// One-command close (review 2026-06-27 passive-user feature #2). The work
+// playbook lists the closing sequence — analyze → apply → verify → coverage →
+// trace → archive → validate — and the agent runs it step by step, which is
+// exactly where a gate gets skipped. `close` runs the whole sequence in one
+// pass, in-process, stopping at the first failure with the exact command to
+// rerun, so the agent makes one call and the human approves once. It is a
+// driver over the existing commands; it adds no new checks of its own.
+
+export async function run(positional, flags) {
+  const id = positional[0];
+  if (!id) {
+    console.error(c.red("error:") + " close requires a change <id> (e.g. doctrina close 0001-add-login)");
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+
+  const force = flagBool(flags, "force", false);
+  const strict = new Map([["strict", true]]);
+  const archiveFlags = force ? new Map([["force", true]]) : new Map();
+
+  // Each step: a label, the command that runs it, and the literal command to
+  // rerun on failure. verify is conditional (skipped, with a loud note, when no
+  // verify.json is declared — a project may not have wired the real gate yet).
+  const verifyConfigured = isFile(path.join(projectRoot, ".doctrina", "verify.json"));
+  const steps = [
+    { label: "analyze", rerun: `doctrina analyze ${id}`, run: () => analyze.run([id], new Map()) },
+    { label: "apply", rerun: `doctrina change apply ${id}`, run: () => change.run(["apply", id], new Map()) },
+    verifyConfigured
+      ? { label: "verify", rerun: "doctrina verify", run: () => verify.run([], new Map()) }
+      : { label: "verify", skip: "no .doctrina/verify.json — declare the real gate with `doctrina verify --init`" },
+    { label: "coverage", rerun: "doctrina coverage --strict", run: () => coverage.run([], strict) },
+    // trace is advisory (provenance is a warning, not a hard gate): report it,
+    // never let it block the close.
+    { label: "trace", rerun: "doctrina trace", run: async () => { await trace.run([], new Map()); return 0; } },
+    { label: "archive", rerun: `doctrina change archive ${id}${force ? " --force" : ""}`, run: () => change.run(["archive", id], archiveFlags) },
+    { label: "validate", rerun: "doctrina validate", run: () => validate.run([], new Map()) },
+  ];
+
+  console.log(c.bold(`Closing change ${id}`) + c.gray(" — analyze → apply → verify → coverage → trace → archive → validate"));
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    console.log("");
+    console.log(c.gray(`──── ${i + 1}/${steps.length} ${step.label}`));
+    if (step.skip) {
+      console.log(c.yellow("skip   ") + step.skip);
+      continue;
+    }
+    let code;
+    try {
+      code = await step.run();
+    } catch (err) {
+      code = 1;
+      console.error(c.red("error:") + ` ${err.message}`);
+    }
+    if (code !== 0) {
+      console.log("");
+      console.log(c.red(`✗ close stopped at "${step.label}"`) + c.gray(` (step ${i + 1}/${steps.length})`));
+      console.log(c.gray("Fix it, then rerun the step or the whole close:"));
+      console.log(`    ${c.cyan(step.rerun)}`);
+      console.log(`    ${c.cyan(`doctrina close ${id}`)}`);
+      return 1;
+    }
+  }
+
+  console.log("");
+  console.log(c.green(`✓ change ${id} closed`) + c.gray(" — verified, archived, and validated."));
+  console.log(c.gray("Next: ") + c.cyan("doctrina next"));
+  return 0;
+}
+
+export const help = `
+Usage: doctrina close <id> [--force]
+
+Run the whole closing sequence for a change in one pass, stopping at the
+first failure with the exact command to rerun:
+
+  analyze → change apply → verify → coverage --strict → trace → change
+  archive → validate
+
+verify is skipped (with a note) when no .doctrina/verify.json is declared;
+trace is advisory (a report, never a blocker). This is a driver over the
+existing commands — it adds no checks of its own — so the agent makes one
+call instead of seven and the human approves once.
+
+Options:
+  --force    Pass through to \`change archive\` (archive even if verification
+             is incomplete; records the gap).
+`;

package/src/commands/coverage.js

@@ -15,9 +15,10 @@ import { c } from "../lib/colors.js";
 // a backtick path span, e.g.
 //   1. Returns HTTP 429 above the quota — verified by `test/quota.test.ts`.
 // A criterion is "covered" when at least one cited path resolves to a
-// file. A cited path that does not resolve is "dangling" (broken
-// traceability) and reported separately. Criteria with no cited path are
-// "bare" — the spec promises something nothing is shown to satisfy.
+// real proof, "conditional" when its only resolving proof is a test file
+// whose suite is skipped (a `describe.skip`/`xit`/`@pytest.mark.skip` that
+// proves nothing — review G3: existence ≠ a passing test), "dangling" when
+// a cited path does not resolve, and "bare" when nothing is cited.
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -47,6 +48,7 @@ export async function run(_positional, flags) {
   let totalCriteria = 0;
   let totalCovered = 0;
   let totalDangling = 0;
+  let totalConditional = 0;
 
   console.log(c.bold("Coverage") + c.gray(" — acceptance criteria with linked evidence:"));
   console.log("");
@@ -54,16 +56,23 @@ export async function run(_positional, flags) {
   for (const rep of reports) {
     const covered = rep.rows.filter((r) => r.kind === "covered").length;
     const dangling = rep.rows.filter((r) => r.kind === "dangling").length;
+    const conditional = rep.rows.filter((r) => r.kind === "conditional").length;
     totalCriteria += rep.rows.length;
     totalCovered += covered;
     totalDangling += dangling;
+    totalConditional += conditional;
 
-    const danglingNote = dangling > 0 ? c.yellow(`  (${dangling} dangling)`) : "";
-    console.log(`  ${c.cyan(rep.cap.padEnd(20))} ${covered}/${rep.rows.length} criteria${danglingNote}`);
+    const notes = [];
+    if (conditional > 0) notes.push(c.yellow(`${conditional} conditional`));
+    if (dangling > 0) notes.push(c.yellow(`${dangling} dangling`));
+    const note = notes.length > 0 ? `  (${notes.join(", ")})` : "";
+    console.log(`  ${c.cyan(rep.cap.padEnd(20))} ${covered}/${rep.rows.length} criteria${note}`);
     for (const r of rep.rows) {
       if (r.kind === "covered") continue;
       if (r.kind === "bare") {
         console.log(`    ${c.red("✗")} #${r.n}  no evidence linked — cite the file/test that proves it in backticks`);
+      } else if (r.kind === "conditional") {
+        console.log(`    ${c.yellow("!")} #${r.n}  evidence is a skipped test (proves nothing): ${r.skipped.map((m) => `\`${m}\``).join(", ")}`);
       } else {
         console.log(`    ${c.yellow("!")} #${r.n}  evidence not found on disk: ${r.missing.map((m) => `\`${m}\``).join(", ")}`);
       }
@@ -73,17 +82,48 @@ export async function run(_positional, flags) {
   const pct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
   console.log("");
   const summary = `${totalCovered} of ${totalCriteria} acceptance criteria across ${reports.length} spec${reports.length === 1 ? "" : "s"} have linked evidence (${pct}%)`;
-  const clean = totalCovered === totalCriteria && totalDangling === 0;
+  const clean = totalCovered === totalCriteria && totalDangling === 0 && totalConditional === 0;
   if (clean) {
     console.log(c.green("ok") + " " + summary);
     return 0;
   }
-  const danglingSummary = totalDangling > 0 ? `, ${totalDangling} dangling` : "";
-  console.log((strict ? c.red("fail") : c.yellow("gap")) + " " + summary + danglingSummary);
-  // A report by default (exit 0); a gate under --strict (exit 1 for CI).
+  const extras = [];
+  if (totalConditional > 0) extras.push(`${totalConditional} conditional`);
+  if (totalDangling > 0) extras.push(`${totalDangling} dangling`);
+  const extraSummary = extras.length > 0 ? `, ${extras.join(", ")}` : "";
+  console.log((strict ? c.red("fail") : c.yellow("gap")) + " " + summary + extraSummary);
+  // A report by default (exit 0); a gate under --strict (exit 1 for CI). A
+  // conditional criterion fails the gate too: a skipped test is not proof.
   return strict ? 1 : 0;
 }
 
+// Pure summary of coverage across the spec tree, for other commands
+// (`status`, `review`) that need the numbers without the report output.
+export function summarize(projectRoot) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  let totalCriteria = 0, totalCovered = 0, totalDangling = 0, totalConditional = 0;
+  const perCap = [];
+  if (isDir(specsDir)) {
+    for (const cap of readdirSync(specsDir).sort()) {
+      const specPath = path.join(specsDir, cap, "spec.md");
+      if (!isFile(specPath)) continue;
+      const criteria = extractAcceptanceCriteria(read(specPath));
+      if (criteria.length === 0) continue;
+      const rows = criteria.map((crit, i) => classify(crit, i + 1, projectRoot, path.dirname(specPath)));
+      const covered = rows.filter((r) => r.kind === "covered").length;
+      const dangling = rows.filter((r) => r.kind === "dangling").length;
+      const conditional = rows.filter((r) => r.kind === "conditional").length;
+      totalCriteria += rows.length;
+      totalCovered += covered;
+      totalDangling += dangling;
+      totalConditional += conditional;
+      perCap.push({ cap, total: rows.length, covered, dangling, conditional });
+    }
+  }
+  const pct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
+  return { perCap, totalCriteria, totalCovered, totalDangling, totalConditional, pct };
+}
+
 // Pull the numbered items out of the "## Acceptance criteria" section.
 // Each item may span multiple lines (continuation prose); accumulate until
 // the next number or the next "## " heading. Returns an array of strings.
@@ -121,22 +161,60 @@ function extractAcceptanceCriteria(text) {
   return out.filter((s) => s.length > 0);
 }
 
-// Decide whether a single criterion is covered, dangling, or bare.
+// Decide whether a single criterion is covered, conditional, dangling, or bare.
 function classify(criterion, n, projectRoot, specDir) {
   const cited = extractBacktickPaths(criterion);
   if (cited.length === 0) return { kind: "bare", n };
   const missing = [];
-  let resolved = 0;
+  const resolved = [];
   for (const token of cited) {
     const candidates = [
       path.resolve(projectRoot, token),
       path.resolve(specDir, token),
     ];
-    if (candidates.some(exists)) resolved += 1;
-    else missing.push(token);
+    const hit = candidates.find(exists);
+    if (!hit) {
+      missing.push(token);
+      continue;
+    }
+    const isTest = looksLikeTestFile(token);
+    const skipped = isTest && isFile(hit) ? testSuiteIsSkipped(read(hit)) : false;
+    resolved.push({ token, isTest, skipped });
+  }
+  if (resolved.length === 0) return { kind: "dangling", n, missing };
+  // Real proof = a non-test artifact, or a test file whose suite runs. If the
+  // only thing that resolves is a skipped test, the criterion is conditional.
+  const hasRealProof = resolved.some((r) => !r.isTest || !r.skipped);
+  if (hasRealProof) return { kind: "covered", n };
+  return { kind: "conditional", n, skipped: resolved.map((r) => r.token) };
+}
+
+// A cited path is a test file when it sits under a tests directory or carries
+// a test/spec/e2e filename marker — the only files skip-detection applies to.
+function looksLikeTestFile(token) {
+  if (/(?:^|\/)(?:tests?|__tests__|specs?|e2e)\//i.test(token)) return true;
+  if (/(?:\.|_|-)(?:test|spec|e2e)\.[a-z0-9]+$/i.test(token)) return true;
+  if (/(?:^|\/)test_[^/]+\.py$/i.test(token)) return true;
+  return false;
+}
+
+// Heuristic, dependency-free "is this whole test file gated off?" check: the
+// first test construct in the file is a skip/todo (e.g. the Prisma e2e suite
+// wrapped in `describe.skip`). A file whose first suite runs is treated as
+// real proof even if it has an incidental `it.skip` later — that keeps the
+// false-positive rate low without parsing the file. Python skip decorators
+// and a module-level `pytest.skip` count too.
+function testSuiteIsSkipped(text) {
+  const m = text.match(
+    /\b(x(?:describe|context|it|test)|(?:describe|context|suite|it|test|specify)\s*\.\s*(?:skip|todo)|(?:describe|context|suite|it|test|specify))\s*\(/,
+  );
+  if (m) {
+    const head = m[1];
+    if (/^x/.test(head) || /\.\s*(?:skip|todo)/.test(head)) return true;
   }
-  if (resolved > 0) return { kind: "covered", n };
-  return { kind: "dangling", n, missing };
+  if (/@(?:pytest\.mark\.skip|unittest\.skip)\b/.test(text)) return true;
+  if (/^\s*pytest\.skip\s*\(/m.test(text)) return true;
+  return false;
 }
 
 // Backtick spans that look like repository file paths. Mirrors the
@@ -169,11 +247,13 @@ Report how many acceptance criteria across .doctrina/specs/ cite an
 artifact or test that exists on disk. Each numbered criterion may cite
 its evidence as a backtick path span, e.g. \`test/quota.test.ts\`.
 
-A criterion is covered when at least one cited path resolves to a file,
-dangling when a cited path is missing on disk, and bare when nothing is
-cited. Read-only.
+A criterion is covered when a cited path resolves to real proof,
+conditional when its only resolving proof is a test file whose suite is
+skipped (\`describe.skip\` / \`xit\` / \`@pytest.mark.skip\` — proves
+nothing), dangling when a cited path is missing on disk, and bare when
+nothing is cited. Read-only.
 
 Flags:
-  --strict   Exit 1 when any criterion is bare or dangling (CI gate).
-             Without it the command always exits 0 (a report).
+  --strict   Exit 1 when any criterion is bare, dangling, or conditional
+             (CI gate). Without it the command always exits 0 (a report).
 `;