doctrina-cli 0.21.0 → 0.22.0

package/src/commands/index-rebuild.js

@@ -10,8 +10,10 @@ import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { planSkillExport, applySkillExport } from "../lib/skill-export.js";
+import { mergeIndex } from "../lib/index-merge.js";
+import { readFileSync, writeFileSync } from "node:fs";
 
-const SUBCOMMANDS = ["rebuild"];
+const SUBCOMMANDS = ["rebuild", "merge"];
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
@@ -20,6 +22,7 @@ export const flags = { boolean: ["json", "check", "staged"], string: [] };
 
 export async function run(positional, flags) {
   const sub = positional[0];
+  if (sub === "merge") return merge(positional.slice(1));
   if (sub !== "rebuild") {
     console.error(c.red("error:") + ` unknown index subcommand "${sub ?? ""}"`);
     const guess = suggest(sub, SUBCOMMANDS);
@@ -98,6 +101,43 @@ function rebuild(flags) {
   return 0;
 }
 
+// The merge driver git calls for `.doctrina/index.json` (change 0242):
+// `doctrina index merge %O %A %B`. It writes the merged index over <ours>
+// and exits 0, which is how a driver tells git there is nothing to resolve.
+// A side that is not JSON is the one case it leaves to git, with exit 1.
+function merge(args) {
+  const [basePath, oursPath, theirsPath] = args;
+  if (!basePath || !oursPath || !theirsPath) {
+    console.error(c.red("error:") + " index merge takes three files: <base> <ours> <theirs>");
+    console.error(c.gray("hint: ") + "git calls it as a merge driver — `doctrina hooks install` sets it up");
+    return 2;
+  }
+  const load = (/** @type {string} */ file, /** @type {string} */ side) => {
+    let text = "";
+    try {
+      text = readFileSync(file, "utf8");
+    } catch {
+      if (side === "base") return {};
+      throw new Error(`cannot read the ${side} index at ${file}`);
+    }
+    if (text.trim() === "") return {};
+    try {
+      return JSON.parse(text);
+    } catch (err) {
+      throw new Error(`the ${side} index is not valid JSON (${err.message})`);
+    }
+  };
+  let merged;
+  try {
+    merged = mergeIndex(load(basePath, "base"), load(oursPath, "ours"), load(theirsPath, "theirs"));
+  } catch (err) {
+    console.error(c.red("error:") + ` ${err.message} — left for a manual merge; \`doctrina index rebuild\` derives it from the tree afterwards`);
+    return 1;
+  }
+  writeFileSync(oursPath, JSON.stringify(merged, null, 2) + "\n");
+  return 0;
+}
+
 // The drift check, asked of what git will record. `index.json` is derived
 // from the WHOLE tree, so it cannot describe a subset of it: stage part of
 // `.doctrina/` and the index riding along names artifacts the commit does
@@ -135,6 +175,12 @@ export const help = `
 Usage: doctrina index <subcommand>
 
 Subcommands:
+  merge <base> <ours> <theirs>
+                    The merge driver git runs for index.json once
+                    \`doctrina hooks install\` has set it up: two branches
+                    that each closed a change merge as lists of artifacts,
+                    so the file never stops a merge with conflict markers.
+                    Writes the result over <ours>.
   rebuild           Regenerate .doctrina/index.json from the artifacts on
                     disk (spec headers, ADR headers, change proposals,
                     archive folders, skill frontmatter). The files are the

package/src/commands/init.js

@@ -5,10 +5,12 @@ 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 {
-  surfaceBlock, findSurfaceBlock, agentChangelogBlock, findAgentChangelogBlock,
+  surfaceBlock, findSurfaceBlock, agentChangelogBlock, findAgentChangelogBlock, SURFACE_PROFILES,
 } from "../lib/commands.js";
 import * as idx from "../lib/index-json.js";
 import { scaffoldConfig } from "../lib/config.js";
+import { applyPreset, describePreset, planPreset, readPreset } from "../lib/preset.js";
+import { deriveIndex } from "../lib/scan.js";
 import { today } from "../lib/dates.js";
 import { cliVersion } from "../lib/version.js";
 import { flagBool, flagString, flagGivenWithoutValue } from "../lib/args.js";
@@ -31,11 +33,12 @@ const SUPPORTED_AGENTS = [
   "devin",
   "factory",
   "jules",
+  "kiro",
 ];
 
 export const flags = {
   boolean: ["json", "force", "non-interactive", "overwrite-content"],
-  string: ["project-name", "project-description", "agent", "intake", "intake-text", "from", "date"],
+  string: ["project-name", "project-description", "agent", "intake", "intake-text", "from", "date", "surface", "preset"],
 };
 
 export async function run(_positional, flags) {
@@ -142,6 +145,30 @@ export async function run(_positional, flags) {
     }
   }
 
+  // Which commands AGENTS.md lists (change 0251). A new project is born with
+  // the session loop only — `core` — and the rest one `--help` away; the
+  // choice is written into config.json, where `upgrade` reads it.
+  // The organisation's preset (change 0253), read BEFORE anything is
+  // written: a folder that is not one stops the init with nothing scaffolded.
+  let preset = null;
+  if (flags.has("preset")) {
+    try {
+      const dir = flagString(flags, "preset");
+      if (!dir) throw new Error("--preset needs the preset's folder");
+      preset = readPreset(dir);
+    } catch (err) {
+      console.error(c.red("error:") + ` ${/** @type {Error} */ (err).message}`);
+      return 2;
+    }
+  }
+  // The preset's surface is the default when the flag names none: the block
+  // is generated once, from the profile the project will keep.
+  const surface = flagString(flags, "surface") ?? preset?.config.surface ?? "core";
+  if (!SURFACE_PROFILES.includes(surface) || flagGivenWithoutValue(flags, "surface")) {
+    console.error(c.red("error:") + ` --surface takes ${SURFACE_PROFILES.join(" or ")}${flagGivenWithoutValue(flags, "surface") ? "" : ` (got "${surface}")`}`);
+    return 2;
+  }
+
   let agentSelector = flagString(flags, "agent");
   // Interactive wizard step: when no --agent was given and we are on a real
   // terminal, offer the adapter install instead of silently skipping it —
@@ -202,7 +229,7 @@ export async function run(_positional, flags) {
   // if the static template lags a release (ADR 0015).
   const agentsTemplatePath = path.join(templatesDir, "AGENTS.md.template");
   const agentsTemplateBody = read(agentsTemplatePath);
-  const projectAgents = refreshSurfaceBlock(substitute(agentsTemplateBody, tokens));
+  const projectAgents = refreshSurfaceBlock(substitute(agentsTemplateBody, tokens), surface);
 
   // --force used to mean "overwrite everything", which made it a content
   // shredder: the only way to add an adapter to an existing project was
@@ -285,11 +312,21 @@ export async function run(_positional, flags) {
   {
     const dest = path.join(doctrinaDir, "config.json");
     if (!isFile(dest) || force) {
-      write(dest, scaffoldConfig(), { force });
+      write(dest, scaffoldConfig({ surface }), { force });
       console.log(c.green("created") + ` ${relPath(projectRoot, dest)}`);
     }
   }
 
+  // The preset, over the scaffold: what it adds is indexed with the rest.
+  if (preset) {
+    const plan = planPreset(projectRoot, preset);
+    applyPreset(projectRoot, preset, plan);
+    for (const line of describePreset(preset, plan, true)) console.log(line);
+    const derived = deriveIndex(projectRoot, idx.load(projectRoot));
+    derived.last_updated = date;
+    idx.save(projectRoot, derived);
+  }
+
   // Adapters
   if (agentSelector) {
     const agents = agentSelector === "all" ? SUPPORTED_AGENTS : [agentSelector];
@@ -384,10 +421,10 @@ function normaliseScaffold(text) {
 // Replace the template's doctrina:surface span with the one generated from
 // the running CLI's catalog; pass the text through untouched when the
 // template carries no markers (older custom templates).
-function refreshSurfaceBlock(text) {
+function refreshSurfaceBlock(text, profile = "full") {
   const block = findSurfaceBlock(text);
   if (!block) return text;
-  let out = text.slice(0, block.start) + surfaceBlock() + text.slice(block.end);
+  let out = text.slice(0, block.start) + surfaceBlock(profile) + text.slice(block.end);
 
   // The agent-facing changelog is version-specific, so it is GENERATED at
   // init like the surface block — not carried in the template. Writing it
@@ -453,8 +490,15 @@ Scaffold AGENTS.md and the .doctrina/ skeleton in the current directory.
 Options:
   --project-name <name>          Override the project name (default: basename of cwd)
   --project-description <text>   One-sentence description
+  --surface core|full            Which commands AGENTS.md lists: core (default) is the session
+                                 loop, with the rest deferred to \`doctrina --help\`; full lists
+                                 every command. Stored in .doctrina/config.json.
+  --preset <dir>                 Lay an organisation's preset over the scaffold: a folder with
+                                 preset.json (name, config) and optional templates/, decisions/,
+                                 skills/ and verify.json. Additive — see \`doctrina upgrade --preset\`
+                                 for a project that already exists.
   --agent <name>                 Install adapter for one agent
-                                 (claude|codex|cursor|copilot|gemini|aider|windsurf|continue|amp|devin|factory|jules|all)
+                                 (claude|codex|cursor|copilot|gemini|aider|windsurf|continue|amp|devin|factory|jules|kiro|all)
   --intake <file>                Full project description; stored verbatim at .doctrina/intake.md,
                                  used to derive the one-line description when absent, and the
                                  bootstrap playbook is printed inline — no second command

package/src/commands/metrics.js

@@ -54,7 +54,7 @@ export async function run(_positional, flags) {
   if (flagBool(flags, "trend", false)) return printTrend(projectRoot);
   // The window is the invocation's: refused the same with or without history.
   const sinceRaw = flagString(flags, "since", "90");
-  const since = sinceWindow(sinceRaw);
+  const since = sinceWindow(sinceRaw ?? "90");
   if (since === null) {
     console.error(c.red("error:") + ` --since expects a day count, a date (YYYY-MM-DD) or "<n> <unit>s ago", got "${sinceRaw}"`);
     console.error(c.gray("hint: ") + "examples: --since 30 · --since 2026-01-01 · --since \"3 months ago\"");

package/src/commands/onboard.js

@@ -0,0 +1,113 @@
+// @ts-check
+import process from "node:process";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { emitJson } from "../lib/json-out.js";
+import { EXIT } from "../lib/exit-codes.js";
+import { TRACKS } from "../lib/triage-model.js";
+import { firstTaskCandidates, onboardState, onboardSteps, tourLines } from "../lib/onboard.js";
+
+// `onboard` walks the whole cycle once, on this repository (change 0256).
+// It reads where the project stands and prints the walk; the agent is the
+// guide and the human the one being shown. It writes nothing and works
+// before `init`, because the first step is the install.
+
+export const jsonNative = true;
+
+export const flags = { boolean: ["json"], string: [] };
+
+export async function run(_positional, cmdFlags) {
+  const projectRoot = process.cwd();
+  const state = onboardState(projectRoot);
+  const { steps, current } = onboardSteps(state);
+  const wantsCandidates = current === "first-task" && state.installed;
+  const candidates = wantsCandidates ? firstTaskCandidates(projectRoot) : [];
+
+  if (flagBool(cmdFlags, "json", false)) {
+    emitJson("onboard", {
+      current,
+      steps: steps.map((s) => ({ id: s.id, title: s.title, done: s.done, run: s.run, ask: s.ask || null })),
+      candidates,
+      closed: state.closed,
+    });
+    return EXIT.OK;
+  }
+
+  console.log(c.bold("Doctrina onboarding") + c.gray(" — the whole cycle once, on this repository"));
+  console.log("");
+  console.log("You are the guide. Do the step marked →, say in one sentence what it did,");
+  console.log("stop where it says ASK, then run `doctrina onboard` again: it reads the tree.");
+  console.log("");
+  steps.forEach((s, i) => {
+    const mark = s.done ? c.green("✓") : (s.id === current ? c.cyan("→") : " ");
+    console.log(`  ${mark} ${i + 1}. ${s.done ? s.title.padEnd(31) + c.gray(s.evidence) : s.title}`);
+  });
+  console.log("");
+
+  if (current === null) {
+    console.log(c.bold("The cycle has run here") + c.gray(` — ${state.closed} change${state.closed === 1 ? "" : "s"} closed. For someone new to the project:`));
+    console.log("");
+    for (const line of tourLines(state)) console.log(`  ${line}`);
+    console.log("");
+    printTracks();
+    return EXIT.OK;
+  }
+
+  const at = steps.findIndex((s) => s.id === current);
+  const step = steps[at];
+  console.log(c.bold(`Step ${at + 1} — ${step.title}`));
+  console.log(`  ${c.gray("Tell the human:")} ${step.say}`);
+  if (wantsCandidates) {
+    console.log("");
+    if (candidates.length === 0) {
+      console.log(c.gray("  No candidate stands out in this repository (every criterion cites proof, no TODO in the code)."));
+    } else {
+      console.log("  Candidates read from this repository:");
+      for (const cand of candidates) console.log(`    - ${cand.where.padEnd(24)} ${cand.text}`);
+    }
+  }
+  const after_ = "askAfter" in step && step.askAfter === true;
+  if (step.ask && !after_) console.log(`  ${c.yellow("ASK")} the human ${step.ask}`);
+  console.log(step.ask && !after_ ? "  Then run:" : "  Run:");
+  for (const cmd of step.run) console.log(`    ${c.cyan(cmd)}`);
+  if (step.ask && after_) console.log(`  Then ${c.yellow("ASK")} the human ${step.ask}`);
+  if (current === "first-task") {
+    console.log("");
+    printTracks();
+  }
+  const after = steps[at + 1];
+  if (after) console.log(c.gray(`\nAfter it: step ${at + 2}, ${after.title.toLowerCase()} — \`doctrina onboard\` shows it.`));
+  return EXIT.OK;
+}
+
+function printTracks() {
+  console.log(c.gray("Not every edit is a change — the tracks, by what a request changes:"));
+  for (const t of TRACKS) console.log(c.gray(`  ${t.id.padEnd(7)} ${t.changes}`));
+}
+
+export const help = `
+Usage: doctrina onboard [--json]
+
+Walk the whole Doctrina cycle once, on this repository. Prints the six
+steps — install, describe the project, pick a first task and open it,
+write the delta and the tasks, implement and prove, close — each marked
+done when the tree says so, and for the first one that is not: what to
+tell the human, where to stop and ask, and the commands to run. Run it
+again after each step; it stores nothing and reads the tree every time.
+
+At "pick a first task" it lists candidates read from the repository: an
+acceptance criterion that cites no proof (or a proof that is missing),
+then a TODO or FIXME left in the code. They are suggestions; the human
+chooses, or names a task of their own.
+
+In a project that already closed a change, every step is done and it
+prints the tour for someone new to the project instead: the commands to
+read the project with, and the last closed change as a worked example.
+
+It works before \`doctrina init\` (the first step is the install) and
+writes nothing.
+
+Options:
+  --json    Machine-readable: the steps with their state, the current
+            step, and the first-task candidates
+`;

package/src/commands/review.js

@@ -116,7 +116,7 @@ export async function run(_positional, flags) {
   //    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]),
+      .map((f) => f.replace(/\\/g, "/").match(/\.doctrina\/specs\/([^/]+)\/spec\.md$/)?.[1] ?? ""),
   );
   const ranked = rankCapabilitiesByDiff(projectRoot, sourceFiles, { limit: Infinity, pending });
   const touched = new Set([...specChanged, ...ranked.map((m) => m.id)]);

package/src/commands/search.js

@@ -59,8 +59,8 @@ export async function run(positional, flags) {
   for (const cat of categories) {
     const files = cat.file
       ? [path.join(projectRoot, cat.file)].filter(exists)
-      : isDir(path.join(projectRoot, cat.dir))
-        ? walk(path.join(projectRoot, cat.dir)).filter((f) => f.endsWith(".md"))
+      : isDir(path.join(projectRoot, cat.dir ?? ""))
+        ? walk(path.join(projectRoot, cat.dir ?? "")).filter((f) => f.endsWith(".md"))
         : [];
 
     const findings = [];

package/src/commands/templates.js

@@ -1,5 +1,6 @@
 // @ts-check
 import path from "node:path";
+import { loadConfig } from "../lib/config.js";
 import process from "node:process";
 import { exists, isDir, isFile, lineCount, read, relPath, walk, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, listResolvedTemplates } from "../lib/templates.js";
@@ -71,7 +72,7 @@ function updateTemplates(flags) {
   if (isFile(agentsMdPath)) {
     const text = read(agentsMdPath);
     const block = findSurfaceBlock(text);
-    const fresh = surfaceBlock();
+    const fresh = surfaceBlock(loadConfig(projectRoot).surface);
     if (block) {
       if (normalizeBlock(text.slice(block.start, block.end)) !== normalizeBlock(fresh)) {
         plan.push({

package/src/commands/triage.js

@@ -4,7 +4,7 @@ import process from "node:process";
 import { exists } from "../lib/fs-ops.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
-import { classify } from "../lib/triage-model.js";
+import { classify, directSignals, trackOf } from "../lib/triage-model.js";
 
 // The classifier is shared with `work`; see lib/triage-model.js.
 export { classify } from "../lib/triage-model.js";
@@ -67,6 +67,7 @@ export async function run(positional, cmdFlags) {
     emitJson("triage", {
       lane: verdict?.lane ?? null,
       confident: verdict?.confident ?? null,
+      track: verdict ? trackOf(prompt, verdict) : null,
       contracts: runtime.contracts,
       declared: runtime.declared,
       findings,
@@ -87,6 +88,20 @@ function renderLane(prompt, verdict) {
     runtime: c.yellow("RUNTIME"),
     chore: c.cyan("CHORE"),
   };
+  // The track first (change 0255): an edit that changes nothing a spec says
+  // needs neither a lane's playbook nor a change.
+  const direct = directSignals(prompt, verdict);
+  if (direct.length > 0) {
+    console.log(c.bold("Track") + c.gray(" — deterministic term match; a hint, not a decision"));
+    console.log("");
+    console.log(`  ${c.green("DIRECT")}${c.gray("  nothing a spec says changes")}`);
+    console.log(c.gray(`  signals: ${[...new Set(direct)].slice(0, 6).join(", ")}`));
+    console.log("");
+    console.log(`Edit it, run ${c.cyan("doctrina verify")}, and commit: no change is opened.`);
+    console.log(c.gray("  If it does change behaviour: ") + c.cyan(`doctrina work --force "${truncate(prompt)}"`));
+    console.log("");
+    return;
+  }
   console.log(c.bold("Lane") + c.gray(" — deterministic term match; a hint, not a decision"));
   console.log("");
   console.log(`  ${LABEL[verdict.lane]}${verdict.confident ? "" : c.gray("  (weak signal — read the playbook and override if it is wrong)")}`);