doctrina-cli 0.3.0 → 0.6.0

package/src/commands/init.js

@@ -3,10 +3,11 @@ import process from "node:process";
 import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, loadTemplateTree, materialiseEntry, substitute } from "../lib/templates.js";
 import { today } from "../lib/dates.js";
+import { cliVersion } from "../lib/version.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { ask } from "../lib/prompt.js";
-import { writeIntakeFile, printBootstrapPlaybook } from "./intake.js";
+import { writeIntakeFile, printBootstrapPlaybook, warnIfThinIntake } from "./intake.js";
 
 const SUPPORTED_AGENTS = [
   "claude",
@@ -90,6 +91,10 @@ export async function run(_positional, flags) {
     PROJECT_DESCRIPTION: description,
     DATE: date,
     AGENTS_MD_PATH: "AGENTS.md",
+    // Stamp the framework version into the scaffolded index.json. init writes
+    // it straight from the template (bypassing idx.save), so the token is the
+    // stamp point here. (3.6)
+    FRAMEWORK_VERSION: cliVersion(),
   };
 
   // Root AGENTS.md — with optional --from base content prepended.
@@ -154,6 +159,7 @@ export async function run(_positional, flags) {
     console.log(`${c.cyan(".doctrina/product.md")} and capability specs. Any AGENTS.md-aware agent`);
     console.log(`runs it on its own; reprint anytime with ${c.cyan("doctrina intake")}.`);
     console.log("");
+    warnIfThinIntake(intakeBody);
     printBootstrapPlaybook(projectRoot);
   } else {
     console.log(`Next: edit ${c.cyan("AGENTS.md")} and ${c.cyan(".doctrina/product.md")} for your project.`);

package/src/commands/intake.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import process from "node:process";
 import { exists, isFile, read, relPath, write } from "../lib/fs-ops.js";
 import { listHeader } from "../lib/scan.js";
+import { assessBrief } from "../lib/clarity.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
 import { flagBool, flagString } from "../lib/args.js";
@@ -69,10 +70,23 @@ export async function run(positional, flags) {
   writeIntakeFile(projectRoot, { body, source, projectName, date: today(), force });
   console.log(c.green("created") + ` ${relPath(projectRoot, intakePath)}`);
   console.log("");
+  warnIfThinIntake(body);
   printBootstrapPlaybook(projectRoot);
   return 0;
 }
 
+// Clarification gate (review Topic A). A description too thin to spec from is
+// the moment to ask the user, not to let the agent invent requirements. Prints
+// the specific gaps before the bootstrap playbook; advisory, never blocking —
+// the intake is still captured verbatim (the playbook step 6 resolves it).
+export function warnIfThinIntake(body) {
+  const assessment = assessBrief(body, { kind: "intake" });
+  if (!assessment.thin) return;
+  console.log(c.yellow("⚠ thin intake — clarify with the user before converting to specs:"));
+  for (const reason of assessment.reasons) console.log(`    - ${reason}`);
+  console.log("");
+}
+
 // Shared with `init --intake`. Writes the intake verbatim under a small
 // status header; the agent flips Status to converted at the end of the
 // playbook, which is how `next` knows the bootstrap is done.
@@ -158,7 +172,8 @@ Store the full project description verbatim at .doctrina/intake.md and
 print the bootstrap playbook — the ordered instruction sequence the host
 AI agent executes to convert the intake into product.md content and
 capability specs (see ADR 0005). The CLI itself does no natural-language
-interpretation.
+interpretation. A thin/under-specified description is flagged so the agent
+clarifies with the user before converting (advisory, never blocking).
 
 Forms:
   doctrina intake <file>              Ingest a description file

package/src/commands/search.js

@@ -6,7 +6,14 @@ import { c } from "../lib/colors.js";
 
 // Category-aware full-text search across the artifact tree. Answers
 // "where is X specified / decided / proposed?" without knowing the
-// layout. Plain substring matching, every term must hit (AND).
+// layout. Plain substring matching, every term must hit (AND) on a line.
+//
+// Results are ranked, not dumped in file order: each hit is scored (a match
+// in a heading or metadata header, or an adjacent full-phrase match, outranks
+// a bare body line), files are scored by their hits plus a filename bonus, and
+// files within a category print best-first. This mirrors the framework's own
+// "ranked selection over dumping" thesis — at scale the agent reads the most
+// relevant hit first instead of scanning an unordered list.
 
 const MAX_MATCHES_PER_FILE = 5;
 
@@ -16,6 +23,7 @@ export async function run(positional, flags) {
     console.error(c.red("error:") + " search requires at least one term");
     return 2;
   }
+  const phrase = terms.join(" ");
   const includeArchive = flagBool(flags, "archive", false);
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
@@ -48,16 +56,22 @@ export async function run(positional, flags) {
       const lines = read(f).split("\n");
       const hits = [];
       for (let i = 0; i < lines.length; i++) {
-        const low = lines[i].toLowerCase();
+        const raw = lines[i];
+        const low = raw.toLowerCase();
         if (terms.every((t) => low.includes(t))) {
-          hits.push({ line: i + 1, text: lines[i].trim() });
-          if (hits.length === MAX_MATCHES_PER_FILE) break;
+          hits.push({ line: i + 1, text: raw.trim(), score: lineScore(raw, low, phrase) });
         }
       }
-      if (hits.length > 0) findings.push({ rel, hits });
+      if (hits.length === 0) continue;
+      // Keep the highest-scoring lines (best-first), not merely the first few.
+      hits.sort((a, b) => b.score - a.score || a.line - b.line);
+      const fileScore = hits.reduce((s, h) => s + h.score, 0) + filenameBonus(rel, terms);
+      findings.push({ rel, hits: hits.slice(0, MAX_MATCHES_PER_FILE), score: fileScore });
     }
 
     if (findings.length === 0) continue;
+    // Most relevant file first; stable tie-break by path.
+    findings.sort((a, b) => b.score - a.score || a.rel.localeCompare(b.rel));
     console.log(c.bold(cat.name));
     for (const file of findings) {
       filesWithMatches += 1;
@@ -81,13 +95,34 @@ function truncate(s, n) {
   return s.length > n ? s.slice(0, n - 1) + "…" : s;
 }
 
+// Relevance of a single matching line. A heading or metadata-header line
+// names the topic; an adjacent full-phrase match means the terms occur
+// together, not scattered. Both outrank a bare body line.
+function lineScore(raw, low, phrase) {
+  let s = 1;
+  if (/^\s*#{1,6}\s/.test(raw)) s += 2;
+  if (/\*\*[^*]+:\*\*/.test(raw)) s += 1;
+  if (phrase && low.includes(phrase)) s += 2;
+  return s;
+}
+
+// A file whose name carries the query is almost always the right one;
+// reward a full filename match more than a partial one.
+function filenameBonus(rel, terms) {
+  const base = rel.toLowerCase();
+  if (terms.every((t) => base.includes(t))) return 3;
+  return terms.some((t) => base.includes(t)) ? 1 : 0;
+}
+
 export const help = `
 Usage: doctrina search <term> [<term> ...] [--archive]
 
 Case-insensitive substring search across the artifact tree, grouped
 by category (specs, decisions, changes, skills, product, AGENTS.md).
-Every term must match on the same line. The change archive is
-excluded unless --archive is passed.
+Every term must match on the same line. Within each category, files are
+ranked best-first (heading / metadata / full-phrase / filename matches
+score higher), and the highest-scoring lines per file are shown. The
+change archive is excluded unless --archive is passed.
 
 Exits 0 when matches are found, 1 otherwise. Read-only.
 `;

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").
 `;

package/src/commands/trace.js

@@ -0,0 +1,157 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
+import { specHeader } from "../lib/scan.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+
+// Intent-provenance report (ADR 0006). `coverage` proves a criterion has a
+// test; `trace` proves a capability traces to a stated intent. Together they
+// form the chain product-intent -> capability -> criterion -> test.
+//
+// Conventions (all opt-in; absent markers are "not yet traced", not errors):
+//   - product.md tags an intent anchor at the head of a bullet: "- [SC1] ...".
+//     Any "[A-Z]+\d+" tag is an anchor (Success criteria, In scope, ...).
+//   - a capability spec declares "**Realizes:** SC1, SC3".
+//
+// trace reports three provenance breaks: dropped intent (an anchor no spec
+// realizes), dangling realizes (a spec cites an unknown id), and untraceable
+// spec (an active spec with no Realizes: header). It is read-only; --strict
+// turns any break into a non-zero exit for CI.
+//
+// What it does NOT do (the honest ceiling, per ADR 0006): judge whether a
+// criterion faithfully encodes the intent. That semantic check is deferred to
+// a future LLM-assisted layer and is never claimed by this deterministic gate.
+
+const ANCHOR_RE = /[A-Z]+\d+/g;
+
+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 strict = flagBool(flags, "strict", false);
+
+  const anchors = collectAnchors(projectRoot); // [{ id }], in document order
+  const specs = collectSpecs(projectRoot); // [{ cap, status, realizes: [id] }]
+
+  const anchorIds = new Set(anchors.map((a) => a.id));
+  const anyRealizes = specs.some((s) => s.realizes !== null);
+
+  // The feature is unused: do not nag a project that never opted in.
+  if (anchors.length === 0 && !anyRealizes) {
+    console.log(
+      c.gray(
+        "no intent-provenance markers found — tag product.md bullets with `[SC1]` " +
+          "and add `**Realizes:** SC1` to the specs that deliver them",
+      ),
+    );
+    return 0;
+  }
+
+  // anchor id -> [capability]
+  const realizedBy = new Map();
+  const dangling = []; // { cap, id }
+  for (const s of specs) {
+    if (s.realizes === null) continue;
+    for (const id of s.realizes) {
+      if (anchorIds.has(id)) {
+        if (!realizedBy.has(id)) realizedBy.set(id, []);
+        realizedBy.get(id).push(s.cap);
+      } else {
+        dangling.push({ cap: s.cap, id });
+      }
+    }
+  }
+  // Untraceable: an active capability tied to no stated intent.
+  const untraceable = specs
+    .filter((s) => s.realizes === null && s.status === "active")
+    .map((s) => s.cap);
+
+  console.log(c.bold("Trace") + c.gray(" — product intent → capability provenance:"));
+  console.log("");
+
+  let realized = 0;
+  for (const a of anchors) {
+    const caps = realizedBy.get(a.id);
+    if (caps && caps.length > 0) {
+      realized += 1;
+      console.log(`  ${c.cyan(a.id.padEnd(6))} ${c.green("✓")} realized by: ${caps.sort().join(", ")}`);
+    } else {
+      console.log(`  ${c.cyan(a.id.padEnd(6))} ${c.red("✗")} dropped — no spec realizes this intent`);
+    }
+  }
+
+  if (dangling.length > 0 || untraceable.length > 0) console.log("");
+  for (const d of dangling) {
+    console.log(`  ${c.yellow("!")} dangling: spec "${d.cap}" realizes ${d.id} (no such anchor in product.md)`);
+  }
+  if (untraceable.length > 0) {
+    console.log(`  ${c.yellow("!")} untraceable specs (no Realizes:): ${untraceable.sort().join(", ")}`);
+  }
+
+  const dropped = anchors.length - realized;
+  console.log("");
+  const summary =
+    `${realized} of ${anchors.length} intent anchor${anchors.length === 1 ? "" : "s"} realized` +
+    `; ${dropped} dropped, ${dangling.length} dangling, ${untraceable.length} untraceable`;
+  const clean = dropped === 0 && dangling.length === 0 && untraceable.length === 0;
+  if (clean) {
+    console.log(c.green("ok") + " " + summary);
+    return 0;
+  }
+  console.log((strict ? c.red("fail") : c.yellow("gap")) + " " + summary);
+  // A report by default (exit 0); a gate under --strict (exit 1 for CI).
+  return strict ? 1 : 0;
+}
+
+// Every "[A-Z]+\d+" tag at the head of a bullet in product.md is an intent
+// anchor. Section-agnostic so Success-criteria and In-scope bullets both work.
+function collectAnchors(projectRoot) {
+  const productPath = path.join(projectRoot, ".doctrina", "product.md");
+  if (!isFile(productPath)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const line of read(productPath).split(/\r?\n/)) {
+    const m = line.match(/^\s*[-*]\s+\[([A-Z]+\d+)\]\s+/);
+    if (m && !seen.has(m[1])) {
+      seen.add(m[1]);
+      out.push({ id: m[1] });
+    }
+  }
+  return out;
+}
+
+function collectSpecs(projectRoot) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (!isDir(specsDir)) return [];
+  const out = [];
+  for (const cap of readdirSync(specsDir).sort()) {
+    const specPath = path.join(specsDir, cap, "spec.md");
+    if (!isFile(specPath)) continue;
+    const text = read(specPath);
+    const realizesRaw = specHeader(text, "Realizes");
+    const realizes = realizesRaw === null ? null : (realizesRaw.match(ANCHOR_RE) ?? []);
+    const status = (specHeader(text, "Status") ?? "active").trim().toLowerCase();
+    out.push({ cap, status, realizes });
+  }
+  return out;
+}
+
+export const help = `
+Usage: doctrina trace [--strict]
+
+Report intent provenance: how product.md intent maps to capability specs
+(ADR 0006). Tag product bullets with an anchor — \`- [SC1] ...\` — and add
+\`**Realizes:** SC1\` to the specs that deliver them.
+
+trace reports three provenance breaks:
+  dropped intent     an anchor that no spec realizes
+  dangling realizes  a spec cites an id absent from product.md
+  untraceable spec   an active spec with no Realizes: header
+
+Read-only. Exits 0 as a report; with --strict, exits 1 when any break
+exists (CI gate). It checks that the link exists and is complete — not
+that a criterion is faithful to the intent (that stays a human/LLM call).
+`;