doctrina-cli 0.3.0 → 0.6.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.3.0 — current release. Zero runtime dependencies
+**Status:** v0.4.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install
@@ -20,14 +20,24 @@ 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
 doctrina decision new "<title>"            create the next sequential ADR
 doctrina decision accept <num>             flip a proposed ADR to accepted
+doctrina decision land <num> [path...]     stamp an accepted ADR as implemented (non-mutating Landed:)
 doctrina decision supersede <num> "<t>"    supersede an existing ADR
 doctrina decision list                     list ADRs with status, date, title
 doctrina skill new <name>                  scaffold an on-demand procedural-memory skill
@@ -36,8 +46,12 @@ doctrina skill sync                        mirror skill frontmatter descriptions
 doctrina analyze <change-id>               inspect a change folder before applying
 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
-doctrina validate                          schema + artifact-existence checks
+doctrina search <term> [...]               search artifacts, grouped by category (ranked)
+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)
@@ -84,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
 
@@ -105,12 +126,28 @@ 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).
-
-Exit code: 0 if no errors (warnings allowed), 1 otherwise.
+19. No two ADR files share the same `NNNN` number (merge-collision error).
+20. `index.json` records a `framework_version` matching the running CLI
+    (stamp-divergence warn; `index rebuild` migrates it).
+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. `--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; 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.3.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;
@@ -144,6 +190,7 @@ function changeApply(args, _flags) {
   // Flip proposal status from "proposed" to "applied" when fully successful.
   // Zero-delta changes are trivially successful (no work to fail), so they
   // also flip — otherwise metadata-only changes are stuck at "proposed".
+  let flippedToApplied = false;
   if (errors === 0 && manual === 0) {
     const proposalPath = path.join(changeDir, "proposal.md");
     if (exists(proposalPath)) {
@@ -155,32 +202,23 @@ function changeApply(args, _flags) {
       if (updated !== txt) {
         write(proposalPath, updated, { force: true });
         console.log(c.green("status") + " proposal.md → applied");
+        flippedToApplied = true;
       }
     }
   }
 
-  // Update index for ADDED/REMOVED that affected specs
-  if (writes > 0) {
-    const index = idx.load(projectRoot);
-    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);
-      }
-    }
-    idx.touch(index, date);
-    idx.save(projectRoot, index);
+  // 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 current = idx.load(projectRoot);
+    const derived = deriveIndex(projectRoot, current);
+    derived.last_updated = date;
+    idx.save(projectRoot, derived);
   }
 
   console.log("");
@@ -293,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) {
@@ -436,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/decision.js

@@ -8,7 +8,7 @@ import { today, slugify, padNumber } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
-const SUBCOMMANDS = ["new", "supersede", "accept", "list"];
+const SUBCOMMANDS = ["new", "supersede", "accept", "land", "list"];
 
 export async function run(positional, _flags) {
   const sub = positional[0];
@@ -19,6 +19,8 @@ export async function run(positional, _flags) {
       return decisionSupersede(positional.slice(1));
     case "accept":
       return decisionAccept(positional.slice(1));
+    case "land":
+      return decisionLand(positional.slice(1));
     case "list":
       return decisionList();
     default:
@@ -198,6 +200,81 @@ function decisionAccept(args) {
   return 0;
 }
 
+// Record that an accepted ADR is now implemented and verified, without
+// editing the immutable body. Mutates ONLY the **Landed:** header line (the
+// same "headers are updatable, the decision prose is not" pattern that accept
+// and supersede already use), stamping today's date plus any cited proof
+// paths. This closes the gap where a design-time ADR ("Evidence: n/a — no
+// implementation yet") had no first-class way to record that reality caught up
+// short of a heavyweight supersede. (3.4)
+function decisionLand(args) {
+  const target = args[0];
+  if (!target) {
+    console.error(c.red("error:") + " decision land requires the target ADR number (e.g. 0003)");
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const padded = padNumber(parseInt(target, 10));
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  const file = walk(adrDir).find((f) => path.basename(f).startsWith(`${padded}-`));
+  if (!file) {
+    console.error(c.red("error:") + ` no ADR found with number ${padded} in ${relPath(projectRoot, adrDir)}`);
+    return 1;
+  }
+  const text = read(file);
+  const statusMatch = text.match(/^-\s+\*\*Status:\*\*\s+(.+)$/m);
+  if (!statusMatch) {
+    console.error(c.red("error:") + ` ADR at ${relPath(projectRoot, file)} has no Status: header`);
+    return 1;
+  }
+  const status = statusMatch[1].trim().toLowerCase();
+  if (status !== "accepted") {
+    console.error(
+      c.red("error:") +
+        ` ADR ${padded} is "${statusMatch[1].trim()}", not "accepted" — accept it before recording that it landed`,
+    );
+    return 1;
+  }
+
+  const date = today();
+  const proofPaths = args.slice(1).filter(Boolean);
+  const cited = proofPaths.map((p) => `\`${p}\``).join(", ");
+  const landedValue = cited ? `${date} — ${cited}` : date;
+
+  // Rewrite the existing Landed header, or insert one (after Evidence, else
+  // after Status) for ADRs that predate the field. The body stays untouched.
+  let updated;
+  if (/^-\s+\*\*Landed:\*\*/m.test(text)) {
+    updated = text.replace(/^(-\s+\*\*Landed:\*\*)\s+.*$/m, `$1 ${landedValue}`);
+  } else if (/^-\s+\*\*Evidence:\*\*.*$/m.test(text)) {
+    updated = text.replace(/^(-\s+\*\*Evidence:\*\*.*)$/m, `$1\n- **Landed:** ${landedValue}`);
+  } else {
+    updated = text.replace(/^(-\s+\*\*Status:\*\*.*)$/m, `$1\n- **Landed:** ${landedValue}`);
+  }
+  write(file, updated, { force: true });
+  console.log(c.green("landed") + ` ${relPath(projectRoot, file)} on ${date}`);
+
+  const index = idx.load(projectRoot);
+  // Store the same value the header now carries, so the index matches what
+  // `index rebuild` would derive from the file (no perpetual drift).
+  idx.updateDecision(index, padded, () => ({ landed: landedValue }));
+  idx.touch(index, date);
+  idx.save(projectRoot, index);
+  console.log(c.green("indexed") + ` decision ${padded} landed`);
+
+  // Parity with `validate`: cited proof that does not resolve is a dangling
+  // citation, surfaced now rather than at the next validate.
+  for (const p of proofPaths) {
+    const candidates = [path.resolve(path.dirname(file), p), path.resolve(projectRoot, p)];
+    if (!candidates.some(exists)) {
+      console.log(c.yellow("warn:") + ` cited proof \`${p}\` not found on disk`);
+    }
+  }
+  return 0;
+}
+
 function decisionList() {
   const projectRoot = process.cwd();
   ensureDoctrinaProject(projectRoot);
@@ -259,6 +336,11 @@ Subcommands:
   new "<title>"                        Create the next sequentially numbered ADR
   accept <number>                      Flip a proposed ADR to accepted (rewrites
                                        only the Status: header) and update the index
+  land <number> [path ...]             Stamp an accepted ADR as implemented:
+                                       rewrites only the Landed: header with today's
+                                       date plus any cited proof paths. The decision
+                                       body stays immutable. Satisfies the accepted-
+                                       ADR evidence check without a supersede.
   supersede <number> "<new title>"     Create a new ADR that supersedes the target
                                        and rewrite the target's Status: header
   list                                 One line per ADR: number, status, date,

package/src/commands/index-rebuild.js

@@ -3,6 +3,7 @@ import process from "node:process";
 import { exists } from "../lib/fs-ops.js";
 import * as idx from "../lib/index-json.js";
 import { deriveIndex, indexesMatch, stableStringify } from "../lib/scan.js";
+import { cliVersion } from "../lib/version.js";
 import { today } from "../lib/dates.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
@@ -42,6 +43,11 @@ function rebuild(flags) {
   }
 
   const derived = deriveIndex(projectRoot, current);
+  // Migrate the framework stamp to the running CLI (3.6). deriveIndex carries
+  // the old value over (so `next` does not nag on a version-only difference);
+  // overriding it here lets a stale stamp count as drift, so `index rebuild`
+  // both reports and fixes it instead of short-circuiting on "nothing to do".
+  derived.framework_version = cliVersion();
 
   if (indexesMatch(derived, current)) {
     console.log(c.green("ok") + " index.json matches the tree (nothing to do)");
@@ -72,6 +78,9 @@ function rebuild(flags) {
 function describeDrift(current, derived) {
   const lines = [];
   if (!current) return ["index.json missing or unreadable"];
+  if ((current.framework_version ?? null) !== (derived.framework_version ?? null)) {
+    lines.push(`framework_version: ${current.framework_version ?? "unset"} -> ${derived.framework_version}`);
+  }
   const categories = ["specs", "decisions", "changes", "changes_archive", "skills"];
   for (const cat of categories) {
     const cur = new Map((current.artifacts?.[cat] ?? []).map((e) => [e.id, e]));