doctrina-cli 0.2.2 → 0.4.0

package/src/commands/validate.js

@@ -3,9 +3,12 @@ import process from "node:process";
 import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, lineCount, read, relPath, walk } from "../lib/fs-ops.js";
 import * as idx from "../lib/index-json.js";
+import { SCHEMA_VERSION } from "../lib/index-json.js";
+import { cliVersion } from "../lib/version.js";
 import { c } from "../lib/colors.js";
 import { parseFrontmatter } from "./skill.js";
 import { checkEars, isEarsSpec } from "../lib/ears.js";
+import { specHeader, listHeader } from "../lib/scan.js";
 
 export async function run(_positional, _flags) {
   const projectRoot = process.cwd();
@@ -44,8 +47,20 @@ export async function run(_positional, _flags) {
   }
 
   if (index) {
-    if (index.$schema_version !== "0.1.0") {
-      warnings.push(`index.json $schema_version is "${index.$schema_version}" (expected "0.1.0")`);
+    if (index.$schema_version !== SCHEMA_VERSION) {
+      warnings.push(`index.json $schema_version is "${index.$schema_version}" (expected "${SCHEMA_VERSION}")`);
+    }
+    // framework_version stamp divergence (3.6). The index records which CLI
+    // manages it; a stamp behind (or absent vs.) the running CLI means the
+    // tree may predate the current schema. `index rebuild` migrates it.
+    const runningVersion = cliVersion();
+    if (!index.framework_version) {
+      warnings.push(`index.json has no framework_version (run \`doctrina index rebuild\` to stamp it)`);
+    } else if (index.framework_version !== runningVersion) {
+      warnings.push(
+        `index.json framework_version is "${index.framework_version}" but the running CLI is ` +
+          `${runningVersion} (run \`doctrina index rebuild\` to stamp/migrate)`,
+      );
     }
     if (!index.artifacts) {
       errors.push("index.json missing artifacts object");
@@ -57,6 +72,7 @@ export async function run(_positional, _flags) {
       for (const d of index.artifacts.decisions ?? []) allArtifactPaths.push(d.path);
       for (const ch of index.artifacts.changes ?? []) allArtifactPaths.push(ch.path);
       for (const ch of index.artifacts.changes_archive ?? []) allArtifactPaths.push(ch.path);
+      for (const ct of index.artifacts.contracts ?? []) allArtifactPaths.push(ct.path);
       for (const rel of allArtifactPaths) {
         const full = path.join(projectRoot, rel);
         if (!exists(full)) errors.push(`index.json references missing artifact: ${rel}`);
@@ -77,10 +93,20 @@ export async function run(_positional, _flags) {
 
   // 5. ADRs have parseable Status: header
   const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  // Track which files claim each NNNN so a merge-time collision (two branches
+  // both allocating the same number) becomes a loud error rather than one ADR
+  // silently shadowing the other (C2).
+  const adrByNumber = new Map();
   if (isDir(adrDir)) {
     for (const f of walk(adrDir)) {
       if (!f.endsWith(".md")) continue;
       const base = path.basename(f);
+      const numMatch = base.match(/^(\d{4})-/);
+      const num = numMatch ? numMatch[1] : null;
+      if (num) {
+        if (!adrByNumber.has(num)) adrByNumber.set(num, []);
+        adrByNumber.get(num).push(relPath(projectRoot, f));
+      }
       // ADR filenames must be NNNN-slug.md (four digits). The entire ADR
       // toolchain — decision new/accept/supersede, index derivation, and
       // the orphan check below — keys off this shape; a file like
@@ -99,6 +125,54 @@ export async function run(_positional, _flags) {
             `(expected a Markdown list item exactly like "- **Status:** accepted")`,
         );
       }
+
+      // 5b. ADR evidence drift. A decision is only true if reality reflects
+      //     it; an accepted ADR that points at nothing — or at a file that
+      //     no longer exists — is the classic "ADR decrees X, the code
+      //     never did X". Two header fields anchor a decision to reality:
+      //     **Evidence:** (cited at any point) and **Landed:** (the
+      //     non-mutating "this is now implemented and verified here" stamp,
+      //     written by `doctrina decision land`; 3.4). Both are checked for
+      //     dangling citations; an accepted ADR is only flagged bare when
+      //     BOTH are empty. ADRs that adopt neither header opt out entirely.
+      const evidence = listHeader(text, "Evidence");
+      const landed = listHeader(text, "Landed");
+      const isBare = (v) => {
+        const t = (v ?? "").trim();
+        return t === "" || t === "—" || t === "-";
+      };
+      for (const [field, value] of [["Evidence", evidence], ["Landed", landed]]) {
+        if (value === null || isBare(value)) continue;
+        for (const token of extractBacktickPaths(value)) {
+          const candidates = [path.resolve(path.dirname(f), token), path.resolve(projectRoot, token)];
+          if (!candidates.some(exists)) {
+            warnings.push(
+              `${relPath(projectRoot, f)}: ${field} cites \`${token}\` which is missing on disk — ` +
+                `the decision may have drifted from the code (update it or supersede the ADR)`,
+            );
+          }
+        }
+      }
+      const adrStatus = (listHeader(text, "Status") ?? "").toLowerCase();
+      if (adrStatus === "accepted" && evidence !== null && isBare(evidence) && isBare(landed)) {
+        warnings.push(
+          `${relPath(projectRoot, f)}: accepted ADR cites no implementation evidence ` +
+            `(link the file(s) that prove it, run \`doctrina decision land ${num ?? "NNNN"}\` once ` +
+            `it ships, or note "n/a — <why>"); a decision with nothing behind it may be drift ` +
+            `waiting to be superseded`,
+        );
+      }
+    }
+
+    // 5c. Duplicate ADR numbers (C2).
+    for (const [num, files] of adrByNumber) {
+      if (files.length > 1) {
+        errors.push(
+          `ADR number ${num} is claimed by ${files.length} files (${files.join(", ")}) — ` +
+            `two branches likely allocated it concurrently; renumber all but one ` +
+            `(the index keys decisions by number, so duplicates silently shadow each other)`,
+        );
+      }
     }
   }
 
@@ -145,6 +219,30 @@ export async function run(_positional, _flags) {
             warnings.push(`${relPath(projectRoot, specPath)}:${f.line} ${f.message}`);
           }
         }
+
+        // 8c. Capability-state honesty (two-axis status). An "active"
+        //     document that records no built capability is an inventory
+        //     claim — the gap the framework is meant to make visible.
+        //     Warn when Status is active and Implementation is "planned"
+        //     with no explanatory note after the state word. A note
+        //     ("planned — deferred, see ADR 0007") is the deliberate-gap
+        //     escape hatch. Specs with no Implementation header are off
+        //     the axis and never warn.
+        const implRaw = specHeader(text, "Implementation");
+        if (implRaw) {
+          const docStatus = (specHeader(text, "Status") ?? "active").toLowerCase();
+          const implTokens = implRaw.trim().split(/\s+/);
+          const implWord = (implTokens[0] ?? "").replace(/[—-]+$/, "").toLowerCase();
+          const hasNote = implTokens.length > 1;
+          if (docStatus === "active" && implWord === "planned" && !hasNote) {
+            warnings.push(
+              `${relPath(projectRoot, specPath)}: Status is "active" but Implementation is ` +
+                `"planned" with no note — an active spec with no built capability is an ` +
+                `inventory claim (advance Implementation, set Status: draft, or add a note ` +
+                `after the value: "planned — <why deferred>")`,
+            );
+          }
+        }
       }
     }
   }
@@ -202,6 +300,44 @@ export async function run(_positional, _flags) {
         }
       }
     }
+    const indexedContractIds = new Set((index.artifacts.contracts ?? []).map((ct) => ct.id));
+    const contractsDir = path.join(projectRoot, ".doctrina", "contracts");
+    if (isDir(contractsDir)) {
+      for (const f of walk(contractsDir)) {
+        if (!f.endsWith(".md")) continue;
+        const id = path.basename(f, ".md");
+        if (!indexedContractIds.has(id)) {
+          warnings.push(`orphan contract ${relPath(projectRoot, f)} (id "${id}" not in index.json)`);
+        }
+      }
+    }
+  }
+
+  // 11. Archive ledger ↔ index cross-check. The history of archived
+  //     changes is recorded twice — once human-facing in
+  //     changes/archive/LEDGER.md, once machine-facing in
+  //     index.json.changes_archive. Two sources of truth that silently
+  //     disagree are worse than one: an incomplete ledger makes the
+  //     history look shorter than it is. When the ledger exists, every
+  //     archived change must appear in both, or validation fails.
+  const ledgerPath = path.join(changesDir, "archive", "LEDGER.md");
+  if (index?.artifacts && isFile(ledgerPath)) {
+    const ledgerIds = new Set();
+    for (const line of read(ledgerPath).split(/\r?\n/)) {
+      const m = line.match(/^-\s+\d{4}-\d{2}-\d{2}\s+[—-]\s+(\S+)\s+[—-]\s+/);
+      if (m) ledgerIds.add(m[1]);
+    }
+    const archiveIds = new Set((index.artifacts.changes_archive ?? []).map((ch) => ch.id));
+    for (const id of archiveIds) {
+      if (!ledgerIds.has(id)) {
+        errors.push(`archived change "${id}" is in index.json but missing from changes/archive/LEDGER.md (ledger and index disagree)`);
+      }
+    }
+    for (const id of ledgerIds) {
+      if (!archiveIds.has(id)) {
+        errors.push(`changes/archive/LEDGER.md lists "${id}" but index.json.changes_archive does not (ledger and index disagree)`);
+      }
+    }
   }
 
   // 12-14. Skills validation
@@ -290,6 +426,17 @@ function extractPathReferences(text) {
   return [...out];
 }
 
+// Path-like tokens inside backtick spans — the convention for citing
+// evidence (ADR **Evidence:**, acceptance-criteria links).
+function extractBacktickPaths(text) {
+  const out = new Set();
+  for (const m of text.matchAll(/`([^`]+)`/g)) {
+    const token = m[1].trim();
+    if (isLikelyPath(token)) out.add(stripFragment(token));
+  }
+  return [...out];
+}
+
 function stripFragment(s) {
   // Remove an in-page anchor (#section) or query string from a path token.
   return s.split(/[#?]/)[0];

package/src/commands/verify.js

@@ -0,0 +1,153 @@
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { exists, isFile, read, write, relPath } from "../lib/fs-ops.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+
+// The build/verify gate `validate` is not. `validate` checks the shape of
+// the artifact tree; it never runs the project, so a repo that does not
+// compile still "passes". `verify` closes that hole: it executes the
+// project-declared checks (typecheck / test / build) and fails when any
+// of them fails. Doctrina is language-agnostic and ships zero runtime
+// deps, so it cannot know your build — you declare it in
+// `.doctrina/verify.json`, and `verify` runs exactly that, in order.
+
+const CONFIG_REL = ".doctrina/verify.json";
+
+const STARTER = {
+  $comment:
+    "doctrina verify runs each check below, in order, through your shell. " +
+    "Replace the example with your real typecheck/test/build commands. A " +
+    "non-zero exit fails the gate. This file is the project's executable " +
+    "definition of 'the code actually works'.",
+  checks: [
+    { name: "example", run: "exit 1" },
+  ],
+};
+
+export async function run(_positional, flags) {
+  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 configPath = path.join(projectRoot, CONFIG_REL);
+
+  // --init scaffolds a starter config so the gate is one edit away.
+  if (flagBool(flags, "init", false)) {
+    const force = flagBool(flags, "force", false);
+    if (isFile(configPath) && !force) {
+      console.error(c.red("error:") + ` ${CONFIG_REL} already exists (pass --force to overwrite)`);
+      return 1;
+    }
+    write(configPath, JSON.stringify(STARTER, null, 2) + "\n", { force: true });
+    console.log(c.green("created") + ` ${CONFIG_REL}`);
+    console.log(c.gray("Edit the `checks` array with your real commands, then run `doctrina verify`."));
+    return 0;
+  }
+
+  if (!isFile(configPath)) {
+    // A verify gate with nothing configured would pass vacuously — exactly
+    // the false confidence this command exists to prevent. Fail loudly.
+    console.error(c.red("error:") + ` no ${CONFIG_REL} — nothing to verify`);
+    console.error(c.gray("hint: ") + "scaffold one with `doctrina verify --init`, then declare your typecheck/test/build commands");
+    return 1;
+  }
+
+  let config;
+  try {
+    config = JSON.parse(read(configPath));
+  } catch (err) {
+    console.error(c.red("error:") + ` ${CONFIG_REL} is not valid JSON: ${err.message}`);
+    return 1;
+  }
+  const checks = Array.isArray(config?.checks) ? config.checks : null;
+  if (!checks) {
+    console.error(c.red("error:") + ` ${CONFIG_REL} must contain a "checks" array of { name, run }`);
+    return 1;
+  }
+  for (const ch of checks) {
+    if (!ch || typeof ch.run !== "string" || ch.run.trim() === "") {
+      console.error(c.red("error:") + ` every check in ${CONFIG_REL} needs a non-empty "run" string`);
+      return 1;
+    }
+  }
+  if (checks.length === 0) {
+    console.error(c.red("error:") + ` ${CONFIG_REL} declares zero checks — a verify gate with no checks proves nothing`);
+    return 1;
+  }
+
+  // --list prints the configured checks without running them.
+  if (flagBool(flags, "list", false)) {
+    console.log(c.bold("Verify checks") + c.gray(` (from ${CONFIG_REL}):`));
+    console.log("");
+    checks.forEach((ch, i) => {
+      console.log(`  ${i + 1}. ${c.cyan((ch.name ?? "check").padEnd(16))} ${c.gray(ch.run)}`);
+    });
+    return 0;
+  }
+
+  console.log(c.bold("doctrina verify") + c.gray(` — ${checks.length} check${checks.length === 1 ? "" : "s"} from ${CONFIG_REL}`));
+  const results = [];
+  for (const ch of checks) {
+    const name = ch.name ?? "check";
+    console.log("");
+    const where = ch.cwd ? c.gray(` [${ch.cwd}]`) : "";
+    console.log(c.gray(`──── ${name}: `) + ch.run + where);
+    // Run through the shell so declared commands can use pipes, &&, env,
+    // and platform builtins. stdio is inherited so the operator sees the
+    // real output — verify shows the truth, it does not summarise it away.
+    // An optional per-check `cwd` (relative to the project root) lets a
+    // monorepo target a sub-package, e.g. { run: "node --test", cwd:
+    // "packages/api" } — the multi-service shape the contract artifact
+    // also serves.
+    const res = spawnSync(ch.run, {
+      cwd: ch.cwd ? path.resolve(projectRoot, ch.cwd) : projectRoot,
+      shell: true,
+      stdio: "inherit",
+    });
+    const ok = !res.error && res.status === 0;
+    if (res.error) {
+      console.log(c.red(`✗ ${name}`) + c.gray(` — could not run: ${res.error.message}`));
+    } else {
+      console.log(ok ? c.green(`✓ ${name}`) : c.red(`✗ ${name} (exit ${res.status})`));
+    }
+    results.push({ name, ok });
+    // Fail fast is tempting, but running every check surfaces all breakage
+    // in one pass — more useful for an agent fixing the gap.
+  }
+
+  const passed = results.filter((r) => r.ok).length;
+  console.log("");
+  if (passed === results.length) {
+    console.log(c.green("ok") + ` ${passed}/${results.length} checks passed`);
+    return 0;
+  }
+  const failed = results.filter((r) => !r.ok).map((r) => r.name).join(", ");
+  console.log(c.red("fail") + ` ${passed}/${results.length} checks passed — failed: ${failed}`);
+  return 1;
+}
+
+export const help = `
+Usage: doctrina verify [--list] [--init] [--force]
+
+Run the project-declared build/verify checks from ${CONFIG_REL} in order,
+streaming their output, and exit non-zero if any check fails. This is the
+real "does the code work" gate, separate from the structural \`validate\`.
+
+${CONFIG_REL} shape (an optional per-check "cwd", relative to the project
+root, targets a sub-package in a monorepo):
+  {
+    "checks": [
+      { "name": "typecheck", "run": "tsc --noEmit", "cwd": "packages/api" },
+      { "name": "test",      "run": "npm test" },
+      { "name": "build",     "run": "npm run build" }
+    ]
+  }
+
+Flags:
+  --init     Scaffold a starter ${CONFIG_REL} (refuses to overwrite without --force)
+  --list     Print the configured checks without running them
+  --force    With --init, overwrite an existing config
+`;

package/src/commands/work.js

@@ -4,14 +4,16 @@ import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
 import { flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { assessBrief } from "../lib/clarity.js";
 import { changeNew } from "./change.js";
 
 // `work` is the second half of the no-ceremony path (ADR 0005): a brief
 // prompt ("add login") becomes a fully scaffolded change plus a playbook
 // the host agent executes — context, spec deltas, tasks, implementation,
-// then the analyze → apply → archive → validate close. The CLI's own
-// language processing stops at slugging and term counting; everything
-// semantic is the agent's job.
+// then the analyze → apply → verify → archive → validate close (verify =
+// `doctrina verify` + `doctrina coverage`, since archive now refuses
+// unproven verification). The CLI's own language processing stops at
+// slugging and term counting; everything semantic is the agent's job.
 
 export async function run(positional, flags) {
   const prompt = positional.join(" ").trim();
@@ -57,9 +59,10 @@ export async function run(positional, flags) {
 
   const matches = pinned ? [] : rankCapabilities(projectRoot, prompt);
   const capability = pinned ?? matches[0]?.id ?? null;
+  const clarity = assessBrief(prompt, { kind: "prompt" });
 
   console.log("");
-  printPlaybook(projectRoot, { id, prompt, pinned, matches, capability });
+  printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, clarity });
   return 0;
 }
 
@@ -149,12 +152,21 @@ export function rankCapabilities(projectRoot, prompt) {
   return ranked.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, 3);
 }
 
-function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability }) {
+function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, clarity }) {
   const capToken = capability ?? "<capability>";
   console.log(c.bold(`Work playbook — change ${id}`) + c.gray(" — agent-executed (ADR 0005)."));
   console.log("");
   console.log(`Prompt: "${prompt}"`);
 
+  // Clarification gate (review Topic A): a thin prompt is the moment to ask
+  // the user, not to invent a spec. Advisory — the change is still scaffolded
+  // (it is a draft), but the agent is told to resolve the gaps first.
+  if (clarity?.thin) {
+    console.log("");
+    console.log(c.yellow("⚠ thin prompt — clarify with the user before writing spec deltas:"));
+    for (const r of clarity.reasons) console.log(`    - ${r}`);
+  }
+
   if (pinned) {
     const hasSpec = isFile(path.join(projectRoot, ".doctrina", "specs", pinned, "spec.md"));
     console.log(`Capability (pinned): ${c.cyan(pinned)}` +
@@ -183,18 +195,27 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability })
   console.log(c.gray("       **Operation:** ADDED | MODIFIED | REMOVED"));
   console.log(c.gray("       **Target spec on apply:** `.doctrina/specs/<capability>/spec.md`"));
   console.log(c.gray("       ---"));
-  console.log(c.gray("       <EARS requirements: full spec body for ADDED, fragment for MODIFIED>"));
+  console.log(c.gray("       <EARS body. Keep the two axes honest (Status vs Implementation),"));
+  console.log(c.gray("        keep aspiration under ## Maturity → Future, and cite the proof per"));
+  console.log(c.gray("        criterion: \"1. [unverified] <signal> — verified by `path/to/test`\">"));
   console.log("");
   console.log(`4. Replace the placeholder tasks in .doctrina/changes/${id}/tasks.md`);
   console.log("   with small, checkable implementation tasks (a few hours each, max).");
   console.log("");
-  console.log("5. Implement task by task, checking each box as it lands. If the");
-  console.log("   prompt is genuinely ambiguous, ask the user before assuming.");
+  console.log("5. Implement task by task, checking each box as it lands. Advance the");
+  console.log("   spec's Implementation: planned → partial → implemented as code lands.");
+  console.log("   If the prompt is genuinely ambiguous, ask the user before assuming.");
   console.log("");
   console.log(`6. ${c.cyan(`doctrina analyze ${id}`)} — fix every ✗ before applying.`);
   console.log(`7. ${c.cyan(`doctrina change apply ${id}`)}   (MODIFIED deltas are merged by hand).`);
-  console.log(`8. ${c.cyan(`doctrina change archive ${id}`)}`);
-  console.log(`9. ${c.cyan("doctrina validate")}, then ${c.cyan("doctrina next")} for the follow-up.`);
+  console.log("8. Prove it before declaring done (archive refuses unchecked boxes):");
+  console.log(`       ${c.cyan("doctrina verify")}     — the project's typecheck/test/build gate`);
+  console.log(`       ${c.cyan("doctrina coverage")}   — each acceptance criterion cites a real test`);
+  console.log("   Then check the proposal's ## Verification boxes and every task,");
+  console.log("   closing steps included, and bump Implementation to verified.");
+  console.log("");
+  console.log(`9. ${c.cyan(`doctrina change archive ${id}`)}`);
+  console.log(`10. ${c.cyan("doctrina validate")}, then ${c.cyan("doctrina next")} for the follow-up.`);
 }
 
 export const help = `
@@ -204,9 +225,11 @@ Turn a brief prompt into a scaffolded change plus the work playbook the
 host AI agent executes (see ADR 0005). The CLI derives a sequential
 change id (NNNN-<slug>) from the prompt, opens the change folder,
 records the prompt under the proposal's "## Why", ranks existing specs
-by term overlap as a capability hint, and prints the ordered steps:
-context → spec delta → tasks → implement → analyze → apply → archive →
-validate. No natural-language interpretation happens in the CLI.
+by term overlap as a capability hint, flags a thin/under-specified prompt
+so you clarify before writing deltas (advisory), and prints the steps:
+context → spec delta → tasks → implement → analyze → apply → verify
+(verify + coverage) → archive → validate. No natural-language
+interpretation happens in the CLI.
 
 Options:
   --capability <cap>   Pin the capability instead of ranking matches

package/src/index.js

@@ -1,11 +1,9 @@
 #!/usr/bin/env node
 import process from "node:process";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { readFileSync } from "node:fs";
 import { parseArgs } from "./lib/args.js";
 import { c } from "./lib/colors.js";
 import { suggest } from "./lib/suggest.js";
+import { cliVersion } from "./lib/version.js";
 
 import * as init from "./commands/init.js";
 import * as spec from "./commands/spec.js";
@@ -24,11 +22,15 @@ import * as context from "./commands/context.js";
 import * as search from "./commands/search.js";
 import * as intake from "./commands/intake.js";
 import * as work from "./commands/work.js";
+import * as coverage from "./commands/coverage.js";
+import * as verify from "./commands/verify.js";
+import * as contract from "./commands/contract.js";
+import * as trace from "./commands/trace.js";
 
 const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
   templates, skill, index: indexCmd, next, metrics, context, search,
-  intake, work,
+  intake, work, coverage, verify, contract, trace,
 };
 
 const TOP_HELP = `
@@ -44,8 +46,11 @@ Commands:
   change apply         Apply spec deltas (ADDED/REMOVED auto, MODIFIED manual)
   change archive       Archive an applied change
   change diff          Preview spec deltas (line diff for MODIFIED)
+  contract new         Own the integration surface (ports, env, interfaces)
+  contract check       Verify port collisions, env drift, referenced specs
   decision new         Create the next sequentially numbered ADR
   decision accept      Flip a proposed ADR to accepted
+  decision land        Record that an accepted ADR is now implemented (non-mutating)
   decision supersede   Create a new ADR that supersedes an existing one
   decision list        List ADRs with status, date, and title
   skill new            Scaffold an on-demand procedural memory skill
@@ -56,6 +61,9 @@ Commands:
   context              Print the context pack for a task in read order
   search               Search the artifact tree, grouped by category
   validate             Run schema and structural checks
+  coverage             Report acceptance criteria with linked evidence (--strict gates)
+  trace                Report intent provenance: product intent → specs (--strict gates)
+  verify               Run project-declared typecheck/test/build checks (the real gate)
   templates list       List the templates shipped by the installed CLI
   templates check      Compare the project against the recommended template shape
   hooks install        Install the pre-commit hook
@@ -70,11 +78,11 @@ Global flags:
 
 async function main(argv) {
   const { positional, flags } = parseArgs(argv, {
-    boolean: ["help", "h", "version", "v", "force", "non-interactive", "check", "save", "bug", "write", "all", "concat", "archive"],
+    boolean: ["help", "h", "version", "v", "force", "non-interactive", "check", "save", "bug", "write", "all", "concat", "archive", "strict", "list", "init"],
   });
 
   if (flags.get("version") || flags.get("v")) {
-    console.log(readVersion());
+    console.log(cliVersion());
     return 0;
   }
 
@@ -112,14 +120,4 @@ async function main(argv) {
   }
 }
 
-function readVersion() {
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  const pkgPath = path.resolve(here, "..", "package.json");
-  try {
-    return JSON.parse(readFileSync(pkgPath, "utf8")).version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-}
-
 main(process.argv.slice(2)).then((code) => process.exit(code ?? 0));

package/src/lib/clarity.js

@@ -0,0 +1,49 @@
+// Deterministic under-specification detector for free-text briefs and
+// intakes — the clarification gate (review Topic A). It does NOT judge
+// meaning (that stays the agent's job, ADR 0005); it flags input that is
+// structurally too thin to spec from, so `intake` and `work` prompt the
+// agent to clarify with the user before speculating a spec or change out of
+// too little. Advisory only: it surfaces the gap, it does not block.
+
+const WEASEL = /\b(might|could|perhaps|maybe|probably|somehow|approximately|roughly|etc)\b/gi;
+const VAGUE = /\b(some|several|various|appropriate|robust|scalable|nice|good|better|fast|simple|stuff|things?)\b/gi;
+
+// Generic verbs/nouns that carry no capability information on their own. A
+// brief made only of these ("add the feature", "do the thing") names nothing
+// concrete to build.
+const FILLER = new Set([
+  "the", "and", "for", "with", "this", "that", "something", "anything",
+  "make", "add", "create", "build", "implement", "feature", "thing",
+  "things", "stuff", "task", "work", "please", "just", "some", "any",
+]);
+
+// Assess a brief/intake. `kind` tunes the thresholds: a one-line work prompt
+// is held to a lower bar than a full project intake.
+export function assessBrief(text, { kind = "prompt" } = {}) {
+  const clean = String(text ?? "").replace(/\s+/g, " ").trim();
+  const tokens = clean ? clean.split(" ") : [];
+  const words = tokens.length;
+  const vague = (clean.match(VAGUE) ?? []).length + (clean.match(WEASEL) ?? []).length;
+  const meaningful = tokens
+    .map((t) => t.toLowerCase().replace(/[^a-z0-9]/g, ""))
+    .filter((t) => t.length >= 3 && !FILLER.has(t));
+
+  const minWords = kind === "intake" ? 20 : 3;
+  const maxVague = kind === "intake" ? 4 : 2;
+
+  const reasons = [];
+  if (words < minWords) {
+    reasons.push(
+      `only ${words} word${words === 1 ? "" : "s"} — say what the behaviour is, ` +
+        `what the inputs are, and how you'll know it's done`,
+    );
+  }
+  if (words > 0 && meaningful.length === 0) {
+    reasons.push("no concrete terms once filler words are removed — name the actual capability or behaviour");
+  }
+  if (vague >= maxVague) {
+    reasons.push(`${vague} vague/weasel term${vague === 1 ? "" : "s"} — replace with definite, checkable wording`);
+  }
+
+  return { thin: reasons.length > 0, words, reasons };
+}

package/src/lib/index-json.js

@@ -1,7 +1,8 @@
 import path from "node:path";
 import { read, write, exists } from "./fs-ops.js";
+import { cliVersion } from "./version.js";
 
-const SCHEMA_VERSION = "0.1.0";
+export const SCHEMA_VERSION = "0.1.0";
 
 export function indexPath(projectRoot) {
   return path.join(projectRoot, ".doctrina", "index.json");
@@ -21,6 +22,11 @@ export function load(projectRoot) {
 }
 
 export function save(projectRoot, index) {
+  // Stamp the managing framework version on every write (3.6): the index
+  // records which CLI last wrote it, so a stale stamp (an index written by an
+  // older CLI) is detectable by `doctrina validate` and migrated by
+  // `doctrina index rebuild`.
+  index.framework_version = cliVersion();
   const p = indexPath(projectRoot);
   const text = JSON.stringify(index, null, 2) + "\n";
   write(p, text, { force: true });
@@ -30,7 +36,7 @@ export function blank(projectName, date) {
   return {
     $schema_version: SCHEMA_VERSION,
     project: projectName,
-    framework_version: "0.0.0",
+    framework_version: cliVersion(),
     last_updated: date,
     artifacts: {
       product: {
@@ -44,6 +50,7 @@ export function blank(projectName, date) {
       changes: [],
       changes_archive: [],
       skills: [],
+      contracts: [],
     },
   };
 }
@@ -56,6 +63,14 @@ export function addSkill(index, entry) {
   return index;
 }
 
+export function addContract(index, entry) {
+  if (!index.artifacts.contracts) index.artifacts.contracts = [];
+  if (!index.artifacts.contracts.some((s) => s.id === entry.id)) {
+    index.artifacts.contracts.push(entry);
+  }
+  return index;
+}
+
 export function removeSkill(index, id) {
   if (!index.artifacts.skills) return index;
   index.artifacts.skills = index.artifacts.skills.filter((s) => s.id !== id);