doctrina-cli 0.15.1 → 0.17.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.15.1 — current release. Zero runtime dependencies
+**Status:** v0.17.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install
@@ -18,59 +18,31 @@ Requires Node.js 20.12 or later.
 
 ## Commands
 
+Start with `doctrina init` in your repository, then tell your AI agent to
+read `AGENTS.md` and run `doctrina next` — it drives the rest. The
+surface, by the moment you reach for it:
+
 ```
-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; 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
-doctrina skill list                        list skills with descriptions (read-only)
-doctrina skill sync                        mirror skill frontmatter descriptions into index.json
-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 (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)
-doctrina hooks install                     install pre-commit hook
-doctrina index rebuild                     regenerate index.json from the files (--check for CI)
-doctrina next                              print the recommended next workflow actions
-doctrina metrics                           local git-derived adoption metrics (no network)
-doctrina --help | -h                       print the command surface
-doctrina --version | -v                    print the package version
+Bootstrap   init · intake · adapter list|add|remove
+Orient      prime · next · status · context · show · search · why · handoff
+Change      triage · work · spec new|list|set · change new|apply|archive|check|tick|abandon
+            contract new|list|check · decision new|accept|land|supersede|list|scope
+            skill new|list|suggest · intent add|list
+Gate        clarify · validate · coverage · trace · review · verify · close · doctor
+Maintain    upgrade · index rebuild · hooks install · watch · metrics · completion · ci · templates list
 ```
 
-Per-command help is available with `doctrina <command> --help`.
+`doctrina --help` prints the same grouping with one line per command, and
+`doctrina <command> --help` the flags of each. Every command, flag and exit
+code is in the
+[CLI reference](https://github.com/GCarin1/Doctrina/blob/main/docs/en/cli-reference.md).
 
 ## `init` flags
 
 | Flag | Purpose |
 |------|---------|
 | `--project-name <name>` | Override the project name (defaults to cwd basename) |
-| `--project-description <text>` | One-sentence description (prompted if omitted) |
+| `--project-description <text>` | One-sentence description, with no intake. Without it on a terminal, `init` asks you to describe the project once and keeps the answer as the intake |
 | `--agent <name>` | Install the adapter for one of the twelve supported agents (`claude`, `codex`, `cursor`, `copilot`, `gemini`, `aider`, `windsurf`, `continue`, `amp`, `devin`, `factory`, `jules`) or `all` |
 | `--date <YYYY-MM-DD>` | Override the system date in artifacts |
 | `--force` | Overwrite existing files |
@@ -100,7 +72,8 @@ For each spec delta found under `.doctrina/changes/<id>/specs/`:
 - **REMOVED:** deletes the target spec.
 - **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
+  / `append-criterion` / `append-requirement` / `replace-requirement`),
+  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.
@@ -108,35 +81,17 @@ For each spec delta found under `.doctrina/changes/<id>/specs/`:
 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.
+the abandonment. `doctrina close <id>` runs apply together with verify,
+coverage, archive and validate in one attested pass — the definition of
+done.
 
 ## `validate` checks
 
-1. `AGENTS.md` exists at root and is ≤ 200 lines (warns at > 150).
-2. `.doctrina/product.md` exists.
-3. `.doctrina/index.json` parses and matches the v0.1 shape.
-4. Every artifact referenced in `index.json` exists.
-5. Every ADR has a parseable `Status:` header.
-6. Every adapter template under `.doctrina/templates/adapters/` is ≤ 30 lines.
-7. Every open change has a `proposal.md`.
-8. Capability specs are ≤ 400 lines (warns above).
-9. ADRs are ≤ 300 lines (warns above).
-10. Spec/ADR files on disk are present in `index.json` (orphan warn).
-11. Markdown links inside specs/ADRs resolve to real files (stale ref warn).
-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. 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).
-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).
+Structure, schema, EARS grammar, index drift, size caps, links, skills,
+ADR anchoring and more — the full, numbered list with the reason for each
+check is in the
+[CLI reference](https://github.com/GCarin1/Doctrina/blob/main/docs/en/cli-reference.md#doctrina-validate).
+A second copy here fell behind it once; there is now one list.
 
 Exit code: 0 if no errors (warnings allowed), 1 otherwise. `--fix`
 regenerates `index.json` from the tree before validating.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [
@@ -15,7 +15,7 @@
   ],
   "type": "module",
   "bin": {
-    "doctrina": "./src/index.js"
+    "doctrina": "src/index.js"
   },
   "scripts": {
     "test": "node --test",
@@ -32,7 +32,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/gcarin1/doctrina.git",
+    "url": "git+https://github.com/GCarin1/Doctrina.git",
     "directory": "packages/doctrina-cli"
   },
   "publishConfig": {

package/src/commands/adapter.js

@@ -1,7 +1,7 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { exists, isFile, mkdirp, read, relPath, remove, write } from "../lib/fs-ops.js";
+import { exists, isFile, mkdirp, pruneEmptyDirs, read, relPath, remove, write } from "../lib/fs-ops.js";
 import {
   ADAPTER_STATES, adapterFiles, describeAdapter, listAdapterNames, renderAdapterFile,
 } from "../lib/adapters.js";
@@ -10,6 +10,7 @@ import { today } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { projectName } from "../lib/project.js";
 
 // `doctrina adapter` — add, remove, and inventory agent adapters (audit
 // item C1).
@@ -96,7 +97,7 @@ function adapterAdd(projectRoot, name, cmdFlags) {
 
   const force = flagBool(cmdFlags, "force", false);
   const tokens = {
-    PROJECT_NAME: path.basename(projectRoot),
+    PROJECT_NAME: projectName(projectRoot),
     PROJECT_DESCRIPTION: "",
     DATE: today(),
   };
@@ -145,9 +146,13 @@ function adapterRemove(projectRoot, name, cmdFlags) {
   // Only delete files this adapter created AND that still match what it
   // would write. A file the user edited is theirs now; --force overrides.
   const force = flagBool(cmdFlags, "force", false);
-  const tokens = { PROJECT_NAME: path.basename(projectRoot), PROJECT_DESCRIPTION: "", DATE: today() };
+  const tokens = { PROJECT_NAME: projectName(projectRoot), PROJECT_DESCRIPTION: "", DATE: today() };
   let removed = 0;
   let kept = 0;
+  // Directories a removed file lived in, innermost first. Only these are
+  // considered for pruning: a directory the adapter never wrote into is not
+  // this command's to tidy.
+  const vacated = new Set();
   for (const file of spec.files) {
     const dest = path.join(projectRoot, file.relativePath);
     if (!isFile(dest)) continue;
@@ -160,9 +165,28 @@ function adapterRemove(projectRoot, name, cmdFlags) {
     remove(dest);
     console.log(c.green("removed") + ` ${file.relativePath}`);
     removed += 1;
+    vacated.add(path.dirname(dest));
   }
+
+  // `add` calls mkdirp on the way in, so `remove` unmakes what it made on
+  // the way out. Without this the six files went and `.claude/` plus
+  // `.claude/commands/` stayed — and an empty `.claude/` is not neutral: it
+  // is a configuration root the next agent finds and treats as present.
+  // Only EMPTY directories are pruned, walking up and stopping at the first
+  // one that still holds anything, so a kept (edited) file or anything of
+  // the user's keeps its whole directory chain alive.
+  const pruned = [];
+  for (const dir of [...vacated].sort((a, b) => b.length - a.length)) {
+    for (const gone of pruneEmptyDirs(dir, projectRoot)) {
+      pruned.push(relPath(projectRoot, gone).replaceAll("\\", "/"));
+      console.log(c.green("removed") + ` ${relPath(projectRoot, gone).replaceAll("\\", "/")}/ ` +
+        c.gray("(empty)"));
+    }
+  }
+
   console.log("");
   console.log(`${c.bold("Adapter " + name)} — ${removed} file${removed === 1 ? "" : "s"} removed` +
+    (pruned.length > 0 ? `, ${pruned.length} empty director${pruned.length === 1 ? "y" : "ies"} pruned` : "") +
     (kept > 0 ? `, ${kept} kept (edited)` : ""));
   return 0;
 }

package/src/commands/analyze.js

@@ -1,10 +1,15 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
+import { isDir, relPath } from "../lib/fs-ops.js";
 import { c } from "../lib/colors.js";
-import { isUntouchedScaffold } from "./change.js";
-import { collectBudgets } from "../lib/runtime.js";
+import { collectAnalysis } from "../lib/analysis.js";
+import { EXIT } from "../lib/exit-codes.js";
+import { ensureDoctrinaProject, refuseChangeRef } from "../lib/project.js";
+
+// The findings themselves live in lib/analysis.js, where the gate map reads
+// them; this command is their renderer (audit finding F7).
+export { collectAnalysis } from "../lib/analysis.js";
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
@@ -19,10 +24,17 @@ export async function run(positional, _flags) {
   }
 
   const projectRoot = process.cwd();
+  // The project first, then the reference. Asked the other way round, a
+  // directory that is not a project at all answered `change "x" not found`
+  // — which points at creating a change somewhere there is nothing to
+  // create it in.
+  ensureDoctrinaProject(projectRoot);
+  const refused = refuseChangeRef(id);
+  if (refused !== null) return refused;
   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;
+    return EXIT.USAGE;
   }
 
   console.log(`analyzing ${relPath(projectRoot, changeDir)}/`);
@@ -41,214 +53,6 @@ export async function run(positional, _flags) {
   return failed === 0 ? 0 : 1;
 }
 
-// The structural findings for a change, as data. Exported so the shared
-// gate map (`lib/gates.js`) can enforce the SAME checks on every
-// transition that needs them, instead of each command deciding for itself
-// — `change apply` used to mutate a change that `analyze` had just
-// refused (audit item C6).
-export function collectAnalysis(projectRoot, changeDir) {
-  const results = [];
-
-  // proposal.md
-  const proposalPath = path.join(changeDir, "proposal.md");
-  if (!isFile(proposalPath)) {
-    results.push(fail("proposal.md missing"));
-  } else {
-    results.push(pass("proposal.md present"));
-    const text = read(proposalPath);
-    if (/^##\s+Why\b/m.test(text)) results.push(pass(`proposal.md has a "## Why" section`));
-    else results.push(fail(`proposal.md missing "## Why" section`));
-
-    // A section that still holds only its scaffold comment was never
-    // written. The check above only proved the HEADING survived, which is
-    // why six changes closed in one session with every rationale section
-    // empty: the planning step wrote to the file with a pattern that did
-    // not match its line endings, and nothing downstream looked inside.
-    // For a framework whose whole premise is recoverable provenance, an
-    // archived change that cannot say why it happened is the defect.
-    // Only `Why` and `What` are required. They are what makes a change
-    // recoverable a year later — the reason it exists and the shape it
-    // took. `Scope boundaries` and `Open questions` are legitimately empty
-    // on a change that has neither, and demanding the word "None." there
-    // is friction that buys nothing.
-    const hollow = [];
-    for (const m of text.matchAll(/^##\s+(.+?)[ \t]*\r?$/gm)) {
-      const heading = m[1].trim();
-      if (!/^(Why|What)$/i.test(heading)) continue;
-      const start = m.index + m[0].length;
-      const next = text.slice(start).search(/^##\s+/m);
-      const body = (next < 0 ? text.slice(start) : text.slice(start, start + next));
-      // Strip comments; anything left that is not whitespace is real prose.
-      if (body.replace(/<!--[\s\S]*?-->/g, "").trim() === "") hollow.push(heading);
-    }
-    if (hollow.length > 0) {
-      results.push(fail(
-        `proposal.md has ${hollow.length} unwritten section${hollow.length === 1 ? "" : "s"} ` +
-        `(${hollow.join(", ")}) — a heading that survived is not a section that was written`,
-      ));
-    } else {
-      results.push(pass("proposal.md states why and what"));
-    }
-  }
-
-  // tasks.md
-  const tasksPath = path.join(changeDir, "tasks.md");
-  if (!isFile(tasksPath)) {
-    results.push(fail("tasks.md missing"));
-  } else {
-    results.push(pass("tasks.md present"));
-    const text = read(tasksPath);
-    // Scaffold placeholders never replaced ("- [ ]" with no text, checked or
-    // not) mean the change was OPENED but never PLANNED — the agent went
-    // straight to implementing on a hollow change and nothing barked
-    // (operator report 2026-07-19). A hard failure here blocks `change
-    // check` and `close` until the plan is real; ticking an empty box does
-    // not help, `change tick` refuses those too.
-    const placeholders = (text.match(/^\s*-\s*\[[ xX]\]\s*$/gm) ?? []).length;
-    if (placeholders > 0) {
-      results.push(fail(`tasks.md still carries ${placeholders} scaffold placeholder task${placeholders === 1 ? "" : "s"} ("- [ ]" with no text) — plan the change before implementing: replace them with real tasks (or delete the lines)`));
-    }
-    if (/^\s*-\s*\[\s\]/m.test(text)) results.push(pass("tasks.md has at least one unchecked task"));
-    else results.push(info("tasks.md has no unchecked tasks (already done?)"));
-  }
-
-  // design.md (optional)
-  const designPath = path.join(changeDir, "design.md");
-  if (isFile(designPath)) results.push(info("design.md present"));
-  else results.push(info("design.md absent (optional)"));
-
-  // Spec deltas
-  const deltaFiles = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
-  if (deltaFiles.length === 0) {
-    results.push(info("0 spec deltas (metadata-only change)"));
-  } else {
-    results.push(pass(`${deltaFiles.length} spec delta${deltaFiles.length === 1 ? "" : "s"}:`));
-    for (const deltaPath of deltaFiles) {
-      const rel = relPath(projectRoot, deltaPath);
-      const text = read(deltaPath);
-      const opMatch = text.match(/^\*\*Operation:\*\*\s*([A-Z]+)/m);
-      const op = opMatch ? opMatch[1] : null;
-      const capMatch = text.match(/^#\s+Spec Delta\s*[—-]\s*capability:\s*([a-z][a-z0-9-]*)/m);
-      const cap = capMatch ? capMatch[1] : path.basename(path.dirname(deltaPath));
-
-      if (!op) {
-        results.push(fail(`  ${rel}: Operation header missing or malformed`));
-        continue;
-      }
-      if (!["ADDED", "MODIFIED", "REMOVED"].includes(op)) {
-        results.push(fail(`  ${rel}: Operation "${op}" is not one of ADDED|MODIFIED|REMOVED`));
-        continue;
-      }
-      const targetSpec = path.join(projectRoot, ".doctrina", "specs", cap, "spec.md");
-      const targetRel = relPath(projectRoot, targetSpec);
-      if (op === "ADDED") {
-        // Mirrors `change apply`: an existing target that is still the
-        // untouched `spec new` scaffold is the canonical flow (spec new →
-        // ADDED delta), so it passes as a replacement; only real content fails.
-        if (exists(targetSpec) && !isUntouchedScaffold(read(targetSpec), cap)) {
-          results.push(fail(`  ${cap} (ADDED) but target ${targetRel} has real content — use MODIFIED or remove it first`, "pre-apply"));
-        } else if (exists(targetSpec)) {
-          results.push(pass(`  ${cap} (ADDED) → ${targetRel} (replaces the untouched scaffold)`));
-        } else {
-          results.push(pass(`  ${cap} (ADDED) → ${targetRel} (new)`));
-        }
-      } else if (op === "MODIFIED") {
-        if (!exists(targetSpec)) {
-          results.push(fail(`  ${cap} (MODIFIED) but target ${targetRel} does not exist`, "pre-apply"));
-        } else {
-          results.push(pass(`  ${cap} (MODIFIED) → ${targetRel}`));
-        }
-      } else {
-        if (!exists(targetSpec)) {
-          results.push(fail(`  ${cap} (REMOVED) but target ${targetRel} does not exist`, "pre-apply"));
-        } else {
-          results.push(pass(`  ${cap} (REMOVED) → ${targetRel}`));
-        }
-      }
-    }
-  }
-
-  // BUDGET DISCIPLINE (change 0029). A declared ceiling is a contract, not
-  // a preference — and the tempting fix for "the output blew the limit" is
-  // to raise the limit. That buys headroom by truncating what mattered
-  // instead of sending less, and it is the discussion that comes back every
-  // quarter because nothing ever recorded that it had been settled. Raising
-  // an INPUT ceiling is a normal trade-off; raising an OUTPUT ceiling to
-  // resolve an overflow is the move this refuses.
-  for (const r of checkBudgetRaises(projectRoot, changeDir)) results.push(r);
-
-  return results;
-}
-
-// Compare the ceilings a change's proposal/deltas propose against the ones
-// the contracts declare today. Text-scanned: a change states a new value in
-// prose long before any code moves, which is exactly when it should be
-// argued about.
-function checkBudgetRaises(projectRoot, changeDir) {
-  const results = [];
-  let declared;
-  try {
-    declared = collectBudgets(projectRoot);
-  } catch {
-    return results;
-  }
-  if (declared.size === 0) return results;
-
-  const texts = [];
-  for (const f of walk(changeDir)) {
-    if (f.endsWith(".md")) texts.push({ rel: relPath(projectRoot, f), text: read(f) });
-  }
-
-  for (const [name, budget] of declared) {
-    if (budget.direction !== "output") continue;
-    for (const { rel, text } of texts) {
-      // "<limit> ... <number>" on one line: the shape a proposal uses when
-      // it restates a ceiling ("raise ai-summary to 2000").
-      const re = new RegExp(`${escapeRe(name)}[^\\n]{0,60}?(\\d{2,})`, "gi");
-      for (const m of text.matchAll(re)) {
-        const proposed = Number.parseInt(m[1], 10);
-        if (!Number.isFinite(proposed) || proposed <= budget.value) continue;
-        results.push(fail(
-          `${rel} raises the OUTPUT ceiling "${name}" from ${budget.value} to ${proposed} ` +
-          `(declared in ${budget.contract}) — raising an output budget buys headroom by ` +
-          `truncating what mattered. Send less, or supersede the budget deliberately in the contract`,
-        ));
-        break;
-      }
-    }
-  }
-  return results;
-}
-
-// A limit name comes from a contract table cell, so it is user text and
-// must not be spliced into a pattern unescaped.
-function escapeRe(s) {
-  return String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function pass(msg) {
-  return { kind: "pass", line: c.green("✓ ") + msg };
-}
-// `scope` says WHEN a failure is a real answer.
-//
-// Most of these questions are true at every point in a change's life: a
-// proposal with an unwritten `## What` is hollow before an apply and just as
-// hollow after one. A few are only meaningful BEFORE the apply — "an ADDED
-// delta's target must not already hold real content" is proof of a problem
-// beforehand and proof the apply WORKED afterwards.
-//
-// The gate map used to exclude the whole structure gate from `archive` to
-// dodge that handful, which also dropped the hollow-proposal check — the
-// exact defect this repository's own history records as having "shipped six
-// hollow proposals past every gate". Tagging the pre-apply ones lets
-// `archive` keep the rest.
-function fail(msg, scope = "always") {
-  return { kind: "fail", scope, line: c.red("✗ ") + msg };
-}
-function info(msg) {
-  return { kind: "info", line: c.gray("- ") + msg };
-}
-
 export const help = `
 Usage: doctrina analyze <change-id>