doctrina-cli 0.10.0 → 0.12.0

package/src/commands/report.js

@@ -0,0 +1,142 @@
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { exists } from "../lib/fs-ops.js";
+import * as idx from "../lib/index-json.js";
+import { collectStatus } from "./status.js";
+import { openChanges } from "./prime.js";
+import { flagString } from "../lib/args.js";
+import { today } from "../lib/dates.js";
+import { c } from "../lib/colors.js";
+
+// Periodic digest in Markdown — the standup/PR-description view: what was
+// archived, where the gates stand, and what local git says about the period.
+// Read-only, no network; the git section degrades silently outside a repo.
+
+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 sinceRaw = flagString(flags, "since") ?? "7";
+  const days = Number.parseInt(sinceRaw, 10);
+  if (!Number.isFinite(days) || days <= 0) {
+    console.error(c.red("error:") + ` --since expects a positive day count, got "${sinceRaw}"`);
+    return 2;
+  }
+  const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+  const cutoffIso = cutoff.toISOString().slice(0, 10);
+
+  const s = collectStatus(projectRoot);
+
+  console.log(`# Doctrina report — ${s.project} (${cutoffIso} → ${today()})`);
+  console.log("");
+
+  // Gates.
+  console.log("## Gates");
+  console.log("");
+  console.log(`- index: ${s.indexState} · framework stamp: ${s.stamp ?? "—"} (CLI ${s.cli})`);
+  console.log(`- coverage: ${s.coverage.pct}% (${s.coverage.totalCovered}/${s.coverage.totalCriteria} criteria)` +
+    (s.coverage.totalDangling ? ` — ${s.coverage.totalDangling} dangling` : "") +
+    (s.coverage.totalConditional ? ` — ${s.coverage.totalConditional} conditional` : ""));
+  console.log(`- trace: ${s.trace.anchors === 0 ? "no anchors declared" : `${s.trace.realized}/${s.trace.anchors} anchors realized`}`);
+  console.log(`- verify: ${s.verify.configured ? `${s.verify.checks} checks declared` : "not configured"}`);
+
+  // Work shipped in the window (from the index ledger) + work in flight.
+  console.log("");
+  console.log("## Changes");
+  console.log("");
+  const archived = archivedSince(projectRoot, cutoffIso);
+  if (archived.length === 0) {
+    console.log(`- archived in period: none`);
+  } else {
+    console.log(`- archived in period: ${archived.length}`);
+    for (const ch of archived) console.log(`  - ${ch.applied} — \`${ch.id}\` ${ch.title}`);
+  }
+  const open = openChanges(projectRoot);
+  if (open.length === 0) {
+    console.log("- open now: none");
+  } else {
+    console.log(`- open now: ${open.length}`);
+    for (const ch of open) {
+      const tasks = ch.tasksTotal > 0 ? ` (tasks ${ch.tasksDone}/${ch.tasksTotal})` : "";
+      console.log(`  - \`${ch.id}\`${ch.title ? ` ${ch.title}` : ""}${tasks}`);
+    }
+  }
+
+  // Artifact counts, for trend-watching between reports.
+  console.log("");
+  console.log("## Artifacts");
+  console.log("");
+  console.log(`- specs: ${s.specs.total} · decisions: ${s.decisions.total}` +
+    (s.decisions.proposed ? ` (${s.decisions.proposed} proposed)` : "") +
+    ` · skills: ${s.skills}`);
+
+  // Local git window — commits, fix share, top churn. No network.
+  console.log("");
+  console.log("## Git (local, last " + days + " days)");
+  console.log("");
+  const git = gitWindow(projectRoot, days);
+  if (!git) {
+    console.log("- no git history available (not a repository, or git not installed)");
+  } else {
+    console.log(`- commits: ${git.commits} (${git.fixes} fix-shaped, ${git.commits ? Math.round((git.fixes / git.commits) * 100) : 0}%)`);
+    if (git.churn.length > 0) {
+      console.log(`- top-churn files:`);
+      for (const [file, n] of git.churn) console.log(`  - ${file} (${n} touches)`);
+    }
+  }
+
+  console.log("");
+  console.log(`*Generated read-only by \`doctrina report --since ${days}\`; deeper numbers: \`doctrina metrics\`.*`);
+  return 0;
+}
+
+function archivedSince(projectRoot, cutoffIso) {
+  let index;
+  try {
+    index = idx.load(projectRoot);
+  } catch {
+    return [];
+  }
+  return (index.artifacts?.changes_archive ?? [])
+    .filter((ch) => typeof ch.applied === "string" && ch.applied >= cutoffIso)
+    .sort((a, b) => String(a.applied).localeCompare(String(b.applied)));
+}
+
+function gitWindow(projectRoot, days) {
+  const log = spawnSync("git", ["log", `--since=${days} days ago`, "--pretty=%s"], {
+    cwd: projectRoot,
+    encoding: "utf8",
+  });
+  if (log.status !== 0) return null;
+  const subjects = log.stdout.split(/\r?\n/).filter((l) => l.trim().length > 0);
+  const fixes = subjects.filter((sub) => /^(fix|bug|hotfix|patch)(\(|:|!)/i.test(sub)).length;
+
+  const files = spawnSync("git", ["log", `--since=${days} days ago`, "--name-only", "--pretty=format:"], {
+    cwd: projectRoot,
+    encoding: "utf8",
+  });
+  const counts = new Map();
+  if (files.status === 0) {
+    for (const line of files.stdout.split(/\r?\n/)) {
+      const f = line.trim();
+      if (!f) continue;
+      counts.set(f, (counts.get(f) ?? 0) + 1);
+    }
+  }
+  const churn = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
+  return { commits: subjects.length, fixes, churn };
+}
+
+export const help = `
+Usage: doctrina report [--since <days>]
+
+Print a Markdown digest for the period (default: last 7 days): gate
+state, changes archived in the window (from the index ledger), open
+work with task progress, artifact counts, and a local-git summary
+(commits, fix share, top-churn files). Made for standups and PR
+descriptions. Read-only; no network. \`doctrina metrics\` has the
+deeper git-derived numbers.
+`;

package/src/commands/review.js

@@ -6,6 +6,7 @@ import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { rankCapabilitiesByDiff } from "./work.js";
+import { parseDependsOn } from "../lib/scan.js";
 import { summarize as coverageSummary } from "./coverage.js";
 import { summarize as traceSummary } from "./trace.js";
 
@@ -42,18 +43,38 @@ export async function run(_positional, flags) {
   const notes = [];  // advisory observations
 
   // 1. Code changed under a capability whose spec was NOT touched — the spec
-  //    may have drifted from the code it describes.
+  //    may have drifted from the code it describes. Touched = every capability
+  //    matched by the code diff (UNCAPPED — the top-3 hint truncation is how
+  //    this missed 5 of 8 in the 0.11.0 field session) UNIONED with every
+  //    capability whose spec.md itself changed.
   const specChanged = new Set(
     all.filter((f) => /(^|\/)\.doctrina\/specs\/[^/]+\/spec\.md$/.test(f.replace(/\\/g, "/")))
       .map((f) => f.replace(/\\/g, "/").match(/\.doctrina\/specs\/([^/]+)\/spec\.md$/)[1]),
   );
-  const ranked = rankCapabilitiesByDiff(projectRoot, sourceFiles);
+  const ranked = rankCapabilitiesByDiff(projectRoot, sourceFiles, { limit: Infinity });
+  const touched = new Set([...specChanged, ...ranked.map((m) => m.id)]);
   for (const m of ranked) {
     if (!specChanged.has(m.id)) {
       breaks.push(`code under capability "${m.id}" changed, but its spec was not updated — confirm \`.doctrina/specs/${m.id}/spec.md\` still describes the code (update it, or note why not)`);
     }
   }
 
+  // 1b. Dependents of touched capabilities (the machine-readable
+  //     **Depends on:** header): a spec that builds on something you changed
+  //     may silently no longer hold. Advisory — a pointer, not a verdict.
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (isDir(specsDir) && touched.size > 0) {
+    for (const cap of readdirSync(specsDir).sort()) {
+      if (touched.has(cap)) continue;
+      const specPath = path.join(specsDir, cap, "spec.md");
+      if (!isFile(specPath)) continue;
+      const deps = parseDependsOn(read(specPath)).filter((d) => touched.has(d));
+      if (deps.length > 0) {
+        notes.push(`capability "${cap}" depends on touched ${deps.map((d) => `"${d}"`).join(", ")} — confirm it still holds (\`doctrina why ${cap}\`)`);
+      }
+    }
+  }
+
   // 2. New source files that map to no capability at all — code with no home
   //    in any spec (a likely new, unspecced capability).
   if (ranked.length === 0 && sourceFiles.length > 0) {
@@ -83,8 +104,8 @@ export async function run(_positional, flags) {
 
   // --- Output ---
   console.log(c.gray(`${all.length} changed path(s); ${sourceFiles.length} source file(s) outside .doctrina/.`));
-  if (ranked.length > 0) {
-    console.log(c.gray("Capabilities touched: ") + ranked.map((m) => c.cyan(m.id)).join(", "));
+  if (touched.size > 0) {
+    console.log(c.gray("Capabilities touched: ") + [...touched].sort().map((id) => c.cyan(id)).join(", "));
   }
   console.log("");
 

package/src/commands/show.js

@@ -0,0 +1,173 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read, relPath } from "../lib/fs-ops.js";
+import { parseAcceptanceCriteria } from "../lib/criteria.js";
+import { suggest } from "../lib/suggest.js";
+import { c } from "../lib/colors.js";
+
+// Point reads. An agent that needs ONE requirement re-reads a whole spec —
+// hundreds of lines for a two-line fact. `show` resolves a compact reference
+// to exactly the lines that own it:
+//
+//   doctrina show cli-R12    twelfth requirement of the cli spec (file order)
+//   doctrina show gates-C3   acceptance criterion 3 (the spec's own numbering)
+//   doctrina show 0007       ADR 0007, whole decision (already a bounded read)
+//   doctrina show cli        the spec's header block + Purpose only
+//
+// R-refs are positional (file order across the EARS sections), so they shift
+// when a requirement is inserted above — cite them for point reads and
+// conversation, not as immutable identifiers. C-refs use the criteria's own
+// explicit numbers and are as stable as the spec keeps them.
+
+export async function run(positional, _flags) {
+  const ref = positional[0];
+  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.");
+  }
+  if (!ref) {
+    console.error(c.red("error:") + " show requires a reference");
+    console.error(c.gray("hint: ") + "`doctrina show cli-R12` (requirement), `doctrina show cli-C3` (criterion), `doctrina show 0007` (ADR), `doctrina show cli` (spec header + purpose)");
+    return 2;
+  }
+
+  // ADR by number.
+  if (/^\d{4}$/.test(ref)) return showAdr(projectRoot, ref);
+
+  const m = ref.match(/^([a-z][a-z0-9-]*)-([RC])(\d+)$/);
+  if (m) return showSpecItem(projectRoot, m[1], m[2], Number(m[3]));
+
+  if (/^[a-z][a-z0-9-]*$/.test(ref)) return showSpecHead(projectRoot, ref);
+
+  console.error(c.red("error:") + ` unrecognised reference "${ref}"`);
+  console.error(c.gray("hint: ") + "use <cap>-R<n>, <cap>-C<n>, an ADR number (0007), or a capability name");
+  return 2;
+}
+
+function showAdr(projectRoot, num) {
+  const dir = path.join(projectRoot, ".doctrina", "decisions");
+  const file = isDir(dir) ? readdirSync(dir).find((f) => f.startsWith(`${num}-`) && f.endsWith(".md")) : null;
+  if (!file) {
+    console.error(c.red("error:") + ` no ADR ${num} under .doctrina/decisions/`);
+    return 1;
+  }
+  const full = path.join(dir, file);
+  console.log(c.gray(`— ${relPath(projectRoot, full)} —`));
+  console.log(read(full).trimEnd());
+  return 0;
+}
+
+function loadSpec(projectRoot, cap) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const specPath = path.join(specsDir, cap, "spec.md");
+  if (isFile(specPath)) return { specPath, text: read(specPath) };
+  const known = isDir(specsDir) ? readdirSync(specsDir).filter((e) => isFile(path.join(specsDir, e, "spec.md"))) : [];
+  console.error(c.red("error:") + ` no spec for capability "${cap}"`);
+  const guess = suggest(cap, known);
+  if (guess) console.error(c.gray("hint: ") + `did you mean "${guess}"?`);
+  else if (known.length) console.error(c.gray("known: ") + known.sort().join(", "));
+  return null;
+}
+
+function showSpecHead(projectRoot, cap) {
+  const spec = loadSpec(projectRoot, cap);
+  if (!spec) return 1;
+  const lines = spec.text.split(/\r?\n/);
+  const out = [];
+  let mode = "head"; // header block -> seek Purpose -> purpose body -> stop
+  for (const line of lines) {
+    const isH2 = /^##\s+/.test(line);
+    if (mode === "head" && isH2) mode = /^##\s+Purpose\b/i.test(line) ? "purpose" : "seek";
+    else if (mode === "seek" && isH2 && /^##\s+Purpose\b/i.test(line)) mode = "purpose";
+    else if (mode === "purpose" && isH2) break;
+
+    if (mode === "head" || (mode === "purpose")) out.push(line);
+  }
+  console.log(c.gray(`— ${relPath(projectRoot, spec.specPath)} (header + purpose; \`doctrina context ${cap}\` for the full spec) —`));
+  console.log(out.join("\n").trimEnd());
+  return 0;
+}
+
+function showSpecItem(projectRoot, cap, kind, n) {
+  const spec = loadSpec(projectRoot, cap);
+  if (!spec) return 1;
+
+  if (kind === "C") {
+    const criteria = parseAcceptanceCriteria(spec.text);
+    const crit = criteria.find((r) => r.n === n);
+    if (!crit) {
+      console.error(c.red("error:") + ` ${cap} has no acceptance criterion #${n} (it declares ${criteria.length})`);
+      return 1;
+    }
+    console.log(c.gray(`— ${cap}-C${n} · ${relPath(projectRoot, spec.specPath)} · ## Acceptance criteria —`));
+    console.log(`${n}. ${crit.body}`);
+    if (crit.proofPaths.length > 0) {
+      console.log(c.gray(`   evidence: ${crit.proofPaths.join(", ")}`));
+    }
+    return 0;
+  }
+
+  const reqs = parseRequirements(spec.text);
+  const req = reqs[n - 1];
+  if (!req) {
+    console.error(c.red("error:") + ` ${cap} has no requirement R${n} (it declares ${reqs.length})`);
+    return 1;
+  }
+  console.log(c.gray(`— ${cap}-R${n} · ${relPath(projectRoot, spec.specPath)} · ${req.section} —`));
+  console.log(req.text);
+  return 0;
+}
+
+// Top-level bullets of the "## Requirements (EARS)" section, in file order,
+// each with its `### <grammar>` sub-section name and continuation lines.
+export function parseRequirements(text) {
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let inSection = false;
+  let sub = "";
+  let cur = null;
+  const flush = () => {
+    if (cur) out.push({ section: cur.section, text: cur.lines.join("\n").trimEnd() });
+    cur = null;
+  };
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      flush();
+      inSection = /^##\s+Requirements\b/i.test(line);
+      sub = "";
+      continue;
+    }
+    if (!inSection) continue;
+    const subMatch = line.match(/^###\s+(.+)$/);
+    if (subMatch) {
+      flush();
+      sub = subMatch[1].trim();
+      continue;
+    }
+    if (/^-\s+/.test(line)) {
+      flush();
+      cur = { section: sub || "Requirements", lines: [line] };
+    } else if (cur && (line.startsWith("  ") || line.trim() === "")) {
+      cur.lines.push(line);
+    } else {
+      flush();
+    }
+  }
+  flush();
+  return out;
+}
+
+export const help = `
+Usage: doctrina show <ref>
+
+Point-read one artifact fragment instead of a whole file:
+
+  doctrina show cli-R12    requirement 12 of the cli spec (file order)
+  doctrina show cli-C3     acceptance criterion 3 (the spec's numbering)
+  doctrina show 0007       ADR 0007 (the whole decision)
+  doctrina show cli        the spec's header block + Purpose only
+
+R-refs are positional (they shift when a requirement is inserted above);
+C-refs use the criteria's own numbers. Read-only.
+`;

package/src/commands/skill.js

@@ -61,9 +61,23 @@ function skillSuggest(args, flags) {
   const since = flagString(flags, "since");
 
   const skillsDir = path.join(projectRoot, ".doctrina", "skills");
-  const existing = new Set(
-    isDir(skillsDir) ? walk(skillsDir).filter((f) => f.endsWith(".md")).map((f) => path.basename(f, ".md")) : [],
-  );
+  const existingFiles = isDir(skillsDir) ? walk(skillsDir).filter((f) => f.endsWith(".md")) : [];
+  const existing = new Set(existingFiles.map((f) => path.basename(f, ".md")));
+  // A lesson may already be captured under a DIFFERENT slug (0.11.0 field
+  // review item 11: the human names the skill after the lesson, not after the
+  // change id — "tela-preta-crash-de-render..." for change 0049). Two extra
+  // dedup signals: an existing skill whose body cites the candidate's change
+  // id / commit hash, and token-overlap similarity between the slugs.
+  const existingBodies = existingFiles.map((f) => ({ slug: path.basename(f, ".md"), body: read(f) }));
+  const captured = (cand) => {
+    if (existing.has(cand.slug)) return true;
+    for (const sk of existingBodies) {
+      if (cand.id && sk.body.includes(cand.id)) return true;
+      if (cand.from && sk.body.includes(cand.from)) return true;
+      if (slugSimilarity(cand.slug, sk.slug) >= 0.5) return true;
+    }
+    return false;
+  };
 
   // Two deterministic sources, deduped by slug. `seen` guards against a lesson
   // appearing twice (e.g. a fix committed and later archived as a change).
@@ -78,18 +92,20 @@ function skillSuggest(args, flags) {
       const id = name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
       if (!FIX_SHAPED.test(id)) continue;
       const slug = skillSlug(id);
-      if (existing.has(slug) || seen.has(slug)) continue; // captured or already queued
+      if (seen.has(slug)) continue;
+      const cand = { id, slug, source: "change", from: name };
+      if (captured(cand)) continue; // captured (any slug) or cited by an existing skill
       const proposal = path.join(archiveDir, name, "proposal.md");
-      const why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
+      cand.why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
       seen.add(slug);
-      candidates.push({ id, slug, why, source: "change", from: name });
+      candidates.push(cand);
     }
   }
 
   // Source 2 — fix-shaped commits in the git history (ADR 0013). Archive wins a
   // slug collision: a `## Why` paragraph is a richer seed than a subject line.
   for (const cand of gitFixCommits(projectRoot, { since, limit: GIT_LOG_LIMIT })) {
-    if (existing.has(cand.slug) || seen.has(cand.slug)) continue;
+    if (seen.has(cand.slug) || captured(cand)) continue;
     seen.add(cand.slug);
     candidates.push(cand);
   }
@@ -216,6 +232,29 @@ function skillSlug(id) {
   return slug.length > 40 ? slug.slice(0, 40).replace(/-+$/g, "") : (slug || "lesson");
 }
 
+// Token-overlap similarity between two kebab slugs (Jaccard over meaningful
+// tokens). "0049-fix-tela-preta-render" vs "tela-preta-crash-de-render-sem-
+// error-boundary" share tela/preta/render → high overlap even though the
+// human renamed the skill after the lesson. Deterministic; never semantic.
+function slugSimilarity(a, b) {
+  const toks = (s) => new Set(
+    String(s).split("-").filter((t) => t.length >= 3 && !/^\d+$/.test(t) && !SLUG_NOISE.has(t)),
+  );
+  const A = toks(a);
+  const B = toks(b);
+  if (A.size === 0 || B.size === 0) return 0;
+  let inter = 0;
+  for (const t of A) if (B.has(t)) inter += 1;
+  return inter / (A.size + B.size - inter);
+}
+
+// Fix-shaped verbs and connectives carry no lesson identity — without this,
+// every "fix-..." candidate looks 30% similar to every "fix-..." skill.
+const SLUG_NOISE = new Set([
+  "fix", "bug", "hotfix", "patch", "the", "and", "for", "with", "sem", "com",
+  "que", "nao", "por", "para", "una", "uma", "dos", "das",
+]);
+
 function firstWhyLine(proposalText) {
   const m = proposalText.match(/##\s*Why\s*\r?\n+([^\r\n][^\r\n]*)/i);
   if (!m) return "";

package/src/commands/spec.js

@@ -134,9 +134,10 @@ function specSet(args, flags) {
   const impl = flagString(flags, "implementation");
   const status = flagString(flags, "status");
   const bump = flagString(flags, "bump");
+  const versionExplicit = flagString(flags, "version");
   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");
+  if (impl === undefined && status === undefined && bump === undefined && versionExplicit === undefined && criterion === undefined) {
+    console.error(c.red("error:") + " spec set needs at least one of --implementation, --status, --bump, --version, --criterion");
     console.error(c.gray("hint: ") + `example: doctrina spec set ${capability} --implementation "verified — \`src/x.js\`" --bump minor`);
     return 2;
   }
@@ -156,6 +157,10 @@ function specSet(args, flags) {
     if (!["major", "minor", "patch"].includes(bump)) errors.push(`--bump needs major|minor|patch (got "${bump}")`);
     else apply(bumpVersion(text, bump));
   }
+  if (versionExplicit !== undefined) {
+    if (!/^\d+\.\d+\.\d+$/.test(versionExplicit)) errors.push(`--version needs semver X.Y.Z (got "${versionExplicit}")`);
+    else apply(setHeader(text, "Version", versionExplicit));
+  }
   if (criterion !== undefined) {
     const m = String(criterion).match(/^(\d+)\s*:\s*(.+)$/);
     if (!m) errors.push(`--criterion needs "<n>:<mark>" (got "${criterion}")`);
@@ -183,7 +188,10 @@ function specSet(args, flags) {
   const derived = deriveIndex(projectRoot, index);
   derived.last_updated = date;
   idx.save(projectRoot, derived);
-  console.log(c.green("indexed") + ` spec "${capability}" synced`);
+  // Echo the SPEC's resulting version, not the framework's — the two look
+  // identical in output and the ambiguity was a field-review papercut.
+  const specVersion = specHeader(text, "Version") ?? "—";
+  console.log(c.green("indexed") + ` spec "${capability}" synced (spec version ${specVersion})`);
   return 0;
 }
 
@@ -214,6 +222,8 @@ Options:
   --implementation "..." With \`set\`: set the Implementation header.
   --status "..."         With \`set\`: set the Status header.
   --bump major|minor|patch  With \`set\`: bump the spec Version.
+  --version X.Y.Z        With \`set\`: set the spec Version explicitly
+                         (the output echoes the SPEC version, not the CLI's).
   --criterion "<n>:<mark>"  With \`set\`: set criterion n's [mark]
                          (e.g. --criterion "2:verified").
 `;