doctrina-cli 0.4.0 → 0.6.0

package/README.md

@@ -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.6.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/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,14 +82,18 @@ 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;
 }
 
@@ -121,22 +134,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 +220,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).
 `;

package/src/commands/spec.js

@@ -3,14 +3,15 @@ import process from "node:process";
 import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, lineCount, read, relPath, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
-import { specHeader } from "../lib/scan.js";
+import { specHeader, deriveIndex } from "../lib/scan.js";
+import { setHeader, bumpVersion, setCriterionMark } from "../lib/spec-ops.js";
 import * as idx from "../lib/index-json.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", "list"];
+const SUBCOMMANDS = ["new", "list", "set"];
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -23,6 +24,7 @@ export async function run(positional, flags) {
     return 2;
   }
   if (sub === "list") return specList();
+  if (sub === "set") return specSet(positional.slice(1), flags);
 
   const capability = positional[1];
   if (!capability || !/^[a-z][a-z0-9-]*$/.test(capability)) {
@@ -109,6 +111,82 @@ function specList() {
   return 0;
 }
 
+// Edit a spec's bookkeeping headers (and a criterion mark) and resync the
+// index in one step — the inverse drift footgun the review hit (G8): a manual
+// "bump the version in the spec, then bump it again in index.json" lockstep.
+// Reuses the same structured ops as `change apply` (ADR 0007), so the header
+// and the index can never diverge after a `spec set`.
+function specSet(args, flags) {
+  const capability = args[0];
+  if (!capability || !/^[a-z][a-z0-9-]*$/.test(capability)) {
+    console.error(c.red("error:") + " spec set requires a <capability> (lowercase letters, digits, hyphens)");
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const specPath = path.join(projectRoot, ".doctrina", "specs", capability, "spec.md");
+  if (!isFile(specPath)) {
+    console.error(c.red("error:") + ` no spec at ${relPath(projectRoot, specPath)} (create it with \`doctrina spec new ${capability}\`)`);
+    return 1;
+  }
+
+  const impl = flagString(flags, "implementation");
+  const status = flagString(flags, "status");
+  const bump = flagString(flags, "bump");
+  const criterion = flagString(flags, "criterion");
+  if (impl === undefined && status === undefined && bump === undefined && criterion === undefined) {
+    console.error(c.red("error:") + " spec set needs at least one of --implementation, --status, --bump, --criterion");
+    console.error(c.gray("hint: ") + `example: doctrina spec set ${capability} --implementation "verified — \`src/x.js\`" --bump minor`);
+    return 2;
+  }
+
+  let text = read(specPath);
+  const applied = [];
+  const errors = [];
+  const apply = (res) => {
+    if (res.error) errors.push(res.error);
+    else { text = res.text; applied.push(res.summary); }
+  };
+  // Order: headers, then version, then criterion — independent edits, all or
+  // none (a failed op leaves the spec untouched, like `change apply`).
+  if (status !== undefined) apply(setHeader(text, "Status", status));
+  if (impl !== undefined) apply(setHeader(text, "Implementation", impl));
+  if (bump !== undefined) {
+    if (!["major", "minor", "patch"].includes(bump)) errors.push(`--bump needs major|minor|patch (got "${bump}")`);
+    else apply(bumpVersion(text, bump));
+  }
+  if (criterion !== undefined) {
+    const m = String(criterion).match(/^(\d+)\s*:\s*(.+)$/);
+    if (!m) errors.push(`--criterion needs "<n>:<mark>" (got "${criterion}")`);
+    else apply(setCriterionMark(text, Number(m[1]), m[2].trim()));
+  }
+
+  if (errors.length > 0) {
+    console.error(c.red("error:") + ` ${errors.length} operation error${errors.length === 1 ? "" : "s"} — spec left untouched:`);
+    for (const e of errors) console.error(`  - ${e}`);
+    return 1;
+  }
+
+  // Stamp Last updated when the header exists (best-effort, never an error).
+  const date = today();
+  const lu = setHeader(text, "Last updated", date);
+  if (!lu.error) text = lu.text;
+
+  write(specPath, text, { force: true });
+  console.log(c.green("updated") + ` ${relPath(projectRoot, specPath)}`);
+  for (const s of applied) console.log(c.gray(`    · ${s}`));
+
+  // Single source of truth: regenerate the index from the now-updated tree so
+  // the spec headers and the index can never drift (no manual lockstep — G8).
+  const index = idx.load(projectRoot);
+  const derived = deriveIndex(projectRoot, index);
+  derived.last_updated = date;
+  idx.save(projectRoot, derived);
+  console.log(c.green("indexed") + ` spec "${capability}" synced`);
+  return 0;
+}
+
 function ensureDoctrinaProject(projectRoot) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
@@ -125,9 +203,17 @@ Subcommands:
   list                                 One line per spec: id, version,
                                        status, line count, last updated.
                                        Read-only.
+  set <capability> [opts]              Edit a spec's headers / a criterion
+                                       mark and resync the index in one step
+                                       (no manual lockstep bump — G8).
 
 Options:
-  --bug      Scaffold the bug-shape template (current / expected /
-             unchanged behaviour) instead of the EARS capability spec.
-  --force    Overwrite an existing spec.
+  --bug                  Scaffold the bug-shape template (current / expected /
+                         unchanged behaviour) instead of the EARS capability spec.
+  --force                Overwrite an existing spec (with \`new\`).
+  --implementation "..." With \`set\`: set the Implementation header.
+  --status "..."         With \`set\`: set the Status header.
+  --bump major|minor|patch  With \`set\`: bump the spec Version.
+  --criterion "<n>:<mark>"  With \`set\`: set criterion n's [mark]
+                         (e.g. --criterion "2:verified").
 `;