doctrina-cli 0.15.1 → 0.17.0

package/src/commands/handoff.js

@@ -2,12 +2,10 @@
 import path from "node:path";
 import process from "node:process";
 import { exists } from "../lib/fs-ops.js";
-import { collectStatus } from "./status.js";
-import { computeActions } from "./next.js";
-import { openChanges } from "./prime.js";
-import { today } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { collectSnapshot } from "../lib/snapshot.js";
+import { renderView } from "../lib/views.js";
 
 // Session handoff note: everything the NEXT session (a fresh agent, a
 // teammate, tomorrow's you) needs to resume without re-reading the tree —
@@ -17,6 +15,10 @@ import { notADoctrinaProject } from "../lib/exit-codes.js";
 // change. It is a VIEW derived from the tree at call time, deliberately not
 // a stored file: a saved note goes stale the moment work continues, the
 // tree never does (no new home for facts).
+//
+// Since change 0037 that word "view" is literal: the note is rendered by
+// lib/views.js from the one snapshot lib/snapshot.js collects, and is equally
+// reachable as `doctrina status --view handoff`.
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
@@ -28,59 +30,7 @@ export async function run(_positional, _flags) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
-
-  const s = collectStatus(projectRoot);
-  const open = openChanges(projectRoot);
-  const actions = computeActions(projectRoot);
-
-  console.log(`# Doctrina handoff — ${s.project} (${today()})`);
-  console.log("");
-
-  // Gate digest — the red ones are what the resuming session fixes first.
-  console.log("## Where things stand");
-  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` : "") + ")");
-  const tr = s.trace.anchors === 0 ? "no anchors declared" : `${s.trace.realized}/${s.trace.anchors} anchors realized`;
-  console.log(`- trace: ${tr}` + (s.trace.untraceable ? ` (${s.trace.untraceable} untraceable)` : ""));
-  console.log(`- verify: ${s.verify.configured ? `${s.verify.checks} checks declared — run \`doctrina verify\`` : "not configured"}`);
-
-  // The in-flight work, task by task.
-  console.log("");
-  if (open.length === 0) {
-    console.log("## Open work");
-    console.log("");
-    console.log("- none — the tree is at rest; start with `doctrina work \"<prompt>\"`");
-  } else {
-    for (const ch of open) {
-      console.log(`## Open change \`${ch.id}\`${ch.title ? ` — ${ch.title}` : ""}`);
-      console.log("");
-      console.log(`- proposal status: ${ch.status}`);
-      if (ch.tasksTotal > 0) {
-        console.log(`- tasks: ${ch.tasksDone}/${ch.tasksTotal} checked`);
-        for (const t of ch.unchecked.slice(0, 8)) console.log(`  - [ ] ${t}`);
-        if (ch.unchecked.length > 8) console.log(`  - … ${ch.unchecked.length - 8} more in tasks.md`);
-      } else {
-        console.log("- tasks: no tasks.md checklist found");
-      }
-      console.log(`- resume with: \`doctrina work --resume ${ch.id}\` · close with: \`doctrina close ${ch.id}\``);
-      console.log("");
-    }
-  }
-
-  // What to do, in priority order.
-  console.log("## Next actions");
-  console.log("");
-  if (actions.length === 0) {
-    console.log("1. nothing pending — `doctrina next` will confirm; pick up new work");
-  } else {
-    actions.forEach((a, i) => console.log(`${i + 1}. ${a}`));
-  }
-
-  console.log("");
-  console.log("*Generated read-only from the tree — regenerate anytime with `doctrina handoff`.*");
+  for (const line of renderView("handoff", collectSnapshot(projectRoot))) console.log(line);
   if (process.stdout.isTTY) {
     console.log("");
     console.log(c.gray("tip: pipe it — `doctrina handoff > note.md` — or paste it as the first message of the next session"));
@@ -96,6 +46,9 @@ with its task-by-task progress and the exact resume command, and the
 prioritised next actions. Made to be pasted as the first message of the
 next agent session (or piped to a file).
 
+The same view as \`doctrina status --view handoff\`; both render one
+collection of the tree.
+
 Deliberately a derived view, not a stored file — the tree is the truth
 and never goes stale; regenerate on demand. Read-only; always exits 0.
 `;

package/src/commands/hooks.js

@@ -3,10 +3,14 @@ import path from "node:path";
 import process from "node:process";
 import { chmodSync } from "node:fs";
 import { exists, mkdirp, read, relPath, write } from "../lib/fs-ops.js";
-import { locateTemplatesDir } from "../lib/templates.js";
+import { locateTemplatesDir, substitute } from "../lib/templates.js";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
+import { EXIT } from "../lib/exit-codes.js";
 
 const SUBCOMMANDS = ["install"];
 
@@ -30,8 +34,12 @@ export async function run(positional, flags) {
   const projectRoot = process.cwd();
 
   if (!exists(path.join(projectRoot, ".git"))) {
+    // A PRECONDITION, not a gate: nothing was measured and found wanting,
+    // the place to put the hook simply does not exist yet. Class 1 told an
+    // agent to fix its work and retry the same command, which never clears.
     console.error(c.red("error:") + " not a git repository (no .git/ in cwd)");
-    return 1;
+    console.error(c.gray("hint: ") + "run `git init` here, then `doctrina hooks install`");
+    return EXIT.PRECONDITION;
   }
 
   const hooksDir = path.join(projectRoot, ".git", "hooks");
@@ -45,7 +53,13 @@ export async function run(positional, flags) {
 
   const templatesDir = locateTemplatesDir();
   const tplPath = path.join(templatesDir, "hooks", "pre-commit.sample");
-  const body = read(tplPath);
+  // The hook pins the CLI that installed it (change 0116). `.git/hooks/` is
+  // local to the clone, so an absolute path is the right thing to write;
+  // a bare `doctrina` ran whichever release was on the PATH — a global
+  // 0.15.0 under a 0.15.1 tree rewrote the stamp backwards on every commit.
+  // `DOCTRINA=` in the environment overrides it.
+  const entry = path.resolve(here, "..", "index.js").replaceAll("\\", "/");
+  const body = substitute(read(tplPath), { DOCTRINA_BIN: `node \"${entry}\"` });
   write(target, body, { force: true });
   chmodSync(target, 0o755);
   console.log(c.green("installed") + ` ${relPath(projectRoot, target)}`);

package/src/commands/index-rebuild.js

@@ -3,8 +3,7 @@ import path from "node:path";
 import process from "node:process";
 import { exists } from "../lib/fs-ops.js";
 import * as idx from "../lib/index-json.js";
-import { deriveIndex, indexesMatch, stableStringify } from "../lib/scan.js";
-import { cliVersion } from "../lib/version.js";
+import { collectIndexDrift, collectStagedIndexDrift } from "../lib/scan.js";
 import { today } from "../lib/dates.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
@@ -16,7 +15,7 @@ const SUBCOMMANDS = ["rebuild"];
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
 // let six flags ship undeclared and silently swallow a positional (C3).
-export const flags = { boolean: ["json", "check"], string: [] };
+export const flags = { boolean: ["json", "check", "staged"], string: [] };
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -33,44 +32,45 @@ export async function run(positional, flags) {
 
 function rebuild(flags) {
   const check = flagBool(flags, "check", false);
+  const staged = flagBool(flags, "staged", false);
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
 
-  let current = null;
-  try {
-    current = idx.load(projectRoot);
-  } catch (err) {
+  if (staged) {
+    if (!check) {
+      console.error(c.red("error:") + " --staged reads the commit, so it can only check; it never writes");
+      console.error(c.gray("hint: ") + "run `doctrina index rebuild --check --staged`");
+      return 2;
+    }
+    return checkStaged(projectRoot);
+  }
+
+  const state = collectIndexDrift(projectRoot);
+  if (state.unreadable) {
     if (check) {
-      console.error(c.red("error:") + ` ${err.message}`);
+      console.error(c.red("error:") + ` ${state.unreadable}`);
       return 1;
     }
-    console.log(c.yellow("warn:") + ` ${err.message} — rebuilding from scratch`);
+    console.log(c.yellow("warn:") + ` ${state.unreadable} — rebuilding from scratch`);
   }
 
-  const derived = deriveIndex(projectRoot, current);
-  // Migrate the framework stamp to the running CLI (3.6). deriveIndex carries
-  // the old value over (so `next` does not nag on a version-only difference);
-  // overriding it here lets a stale stamp count as drift, so `index rebuild`
-  // both reports and fixes it instead of short-circuiting on "nothing to do".
-  derived.framework_version = cliVersion();
-
-  if (indexesMatch(derived, current)) {
+  if (state.ok) {
     console.log(c.green("ok") + " index.json matches the tree (nothing to do)");
     return 0;
   }
 
-  const drift = describeDrift(current, derived);
-  for (const line of drift) console.log((check ? c.yellow("drift: ") : c.gray("sync:  ")) + line);
+  for (const line of state.drift) console.log((check ? c.yellow("drift: ") : c.gray("sync:  ")) + line);
 
   if (check) {
     console.log("");
-    console.log(c.red("fail") + ` index.json has drifted from the tree (${drift.length} difference${drift.length === 1 ? "" : "s"})`);
+    console.log(c.red("fail") + ` index.json has drifted from the tree (${state.drift.length} difference${state.drift.length === 1 ? "" : "s"})`);
     console.log(c.gray("hint: ") + "run `doctrina index rebuild` to regenerate it");
     return 1;
   }
 
+  const derived = state.derived;
   derived.last_updated = today();
   idx.save(projectRoot, derived);
   const a = derived.artifacts;
@@ -80,33 +80,37 @@ function rebuild(flags) {
   return 0;
 }
 
-// Human-readable category-level drift between the on-disk index and the
-// derived one: added / removed / changed entry ids.
-function describeDrift(current, derived) {
-  const lines = [];
-  if (!current) return ["index.json missing or unreadable"];
-  if ((current.framework_version ?? null) !== (derived.framework_version ?? null)) {
-    lines.push(`framework_version: ${current.framework_version ?? "unset"} -> ${derived.framework_version}`);
+// 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
+// not carry. Every other gate reads the working tree, where those artifacts
+// are still sitting, so none of them can see it.
+function checkStaged(projectRoot) {
+  const state = collectStagedIndexDrift(projectRoot);
+  if (!state.applicable) {
+    console.log(c.green("ok") + ` nothing to check — ${state.reason}`);
+    return 0;
   }
-  const categories = ["specs", "decisions", "changes", "changes_archive", "skills"];
-  for (const cat of categories) {
-    const cur = new Map((current.artifacts?.[cat] ?? []).map((e) => [e.id, e]));
-    const der = new Map((derived.artifacts?.[cat] ?? []).map((e) => [e.id, e]));
-    for (const id of der.keys()) {
-      if (!cur.has(id)) lines.push(`${cat}: "${id}" on disk but not in index`);
-      else if (stableStringify(cur.get(id)) !== stableStringify(der.get(id))) {
-        lines.push(`${cat}: "${id}" metadata differs from the files`);
-      }
-    }
-    for (const id of cur.keys()) {
-      if (!der.has(id)) lines.push(`${cat}: "${id}" in index but not on disk`);
-    }
+  if (state.ok) {
+    console.log(c.green("ok") + " the staged index matches the staged tree");
+    return 0;
+  }
+  if (state.reason) {
+    console.error(c.red("error:") + ` ${state.reason}`);
+    return 1;
+  }
+  for (const p of state.missing) {
+    console.log(c.yellow("staged: ") + `${p} — named by the staged index, absent from the commit`);
   }
-  if (stableStringify(current.artifacts?.product ?? null) !== stableStringify(derived.artifacts.product)) {
-    lines.push("product: metadata differs");
+  for (const p of state.unindexed) {
+    console.log(c.yellow("staged: ") + `${p} — in the commit, absent from the staged index`);
   }
-  if (lines.length === 0) lines.push("structural difference (key order or missing category)");
-  return lines;
+  const n = state.missing.length + state.unindexed.length;
+  console.log("");
+  console.log(c.red("fail") + ` the staged index does not describe this commit (${n} difference${n === 1 ? "" : "s"})`);
+  console.log(c.gray("hint: ") + "stage the artifacts above with the index, or unstage the index — "
+    + "index.json is derived from the whole tree, so a partial commit of .doctrina/ cannot carry a matching one");
+  return 1;
 }
 
 export const help = `
@@ -119,6 +123,13 @@ Subcommands:
                     source of truth; the index is derived.
   rebuild --check   Write nothing; exit 1 with a drift summary when the
                     index no longer matches the tree. CI-friendly.
+  rebuild --check --staged
+                    Ask the same question of the COMMIT rather than the
+                    disk: every artifact the staged index names must be in
+                    the commit, and every staged artifact must be in the
+                    index. A partial commit of .doctrina/ cannot satisfy
+                    both, because the index is derived from the whole tree.
+                    Exits 0 when nothing relevant is staged.
 
 Fields with no on-disk source (project name, framework_version, product
 metadata) are carried over from the existing index.

package/src/commands/init.js

@@ -7,13 +7,14 @@ import {
   surfaceBlock, findSurfaceBlock, agentChangelogBlock, findAgentChangelogBlock,
 } from "../lib/commands.js";
 import * as idx from "../lib/index-json.js";
+import { scaffoldConfig } from "../lib/config.js";
 import { today } from "../lib/dates.js";
 import { cliVersion } from "../lib/version.js";
-import { flagBool, flagString } from "../lib/args.js";
+import { flagBool, flagString, flagGivenWithoutValue } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { EXIT } from "../lib/exit-codes.js";
 import { ask, isInteractive } from "../lib/prompt.js";
-import { writeIntakeFile, printBootstrapPlaybook, warnIfThinIntake } from "./intake.js";
+import { looksLikePath, writeIntakeFile, printBootstrapPlaybook, warnIfThinIntake, nextStepAfterInit } from "../lib/intake-model.js";
 
 const SUPPORTED_AGENTS = [
   "claude",
@@ -32,7 +33,7 @@ const SUPPORTED_AGENTS = [
 
 export const flags = {
   boolean: ["json", "force", "non-interactive", "overwrite-content"],
-  string: ["project-name", "project-description", "agent", "intake", "from", "date"],
+  string: ["project-name", "project-description", "agent", "intake", "intake-text", "from", "date"],
 };
 
 export async function run(_positional, flags) {
@@ -45,17 +46,56 @@ export async function run(_positional, flags) {
   // --intake hands over the FULL description up front (ADR 0005); the
   // one-line summary is then derived instead of prompted for.
   const intakeFile = flagString(flags, "intake");
+  const intakeText = flagString(flags, "intake-text");
   let intakeBody = null;
+  let intakeSource = null;
+  // Onboarding is ONE moment, so it gets one command (change 0051). The
+  // separation between `init` and `intake` is an architectural fact — `init`
+  // refuses to read language, ADR 0005 — and it was being charged to the
+  // user as two steps of setup. Both commands stay: `intake` is still the
+  // door for converting a description in a project that already exists.
+  if (intakeFile && intakeText !== undefined) {
+    console.error(c.red("error:") + " pass --intake <file> or --intake-text \"<text>\", not both");
+    return EXIT.USAGE;
+  }
+  // A flag written without a value is a usage error, never a silent fallback
+  // to "no intake": the operator asked for one and would get a project
+  // without it, and nothing would say so.
+  for (const name of ["intake", "intake-text"]) {
+    if (flagGivenWithoutValue(flags, name)) {
+      console.error(c.red("error:") + ` --${name} needs a value`);
+      console.error(c.gray("hint: ") + (name === "intake"
+        ? "doctrina init --intake ./description.md"
+        : "doctrina init --intake-text \"<the whole project description>\""));
+      return EXIT.USAGE;
+    }
+  }
+  if (typeof intakeText === "string" && intakeText.trim() !== "") {
+    intakeBody = intakeText;
+    intakeSource = "inline (--intake-text)";
+  }
   if (intakeFile) {
     const intakeAbs = path.resolve(projectRoot, intakeFile);
-    if (!isFile(intakeAbs)) {
+    if (isFile(intakeAbs)) {
+      intakeBody = read(intakeAbs);
+      intakeSource = relPath(projectRoot, intakeAbs);
+      if (intakeBody.trim().length === 0) {
+        console.error(c.red("error:") + ` --intake file is empty: ${intakeFile}`);
+        return 1;
+      }
+    } else if (looksLikePath(intakeFile)) {
       console.error(c.red("error:") + ` --intake file not found: ${intakeFile}`);
+      console.error(c.gray("hint: ") +
+        'to pass the description itself, use `--intake-text "<description>"`');
       return 1;
-    }
-    intakeBody = read(intakeAbs);
-    if (intakeBody.trim().length === 0) {
-      console.error(c.red("error:") + ` --intake file is empty: ${intakeFile}`);
-      return 1;
+    } else {
+      // The same rule `intake` applies to its positional (change 0071): the
+      // two commands answer the same input shape the same way, so an agent
+      // that learned one is not surprised by the other.
+      intakeBody = intakeFile;
+      intakeSource = "inline";
+      console.error(c.gray("note:  ") +
+        'read as the description itself, not as a file — `--intake-text "<description>"` says so explicitly');
     }
   }
 
@@ -67,9 +107,20 @@ export async function run(_positional, flags) {
   // isTTY check the adapter prompt already had. A non-interactive caller
   // that forgot --non-interactive read EOF, got an empty answer, and
   // scaffolded a project with a blank description — silently (C9).
+  // At a terminal, ONE question, and its answer is the intake (change 0173):
+  // it was asked as a one-line description, written into product.md, and
+  // then `next` asked for the same thing again as an intake. A person
+  // describes the project once.
+  let intakeFromTty = false;
   if (!description && !nonInteractive) {
     if (isInteractive()) {
-      description = await ask("One-sentence project description:");
+      const answer = await ask("Describe the project — what it is, who it is for, what it must do:");
+      if (answer && answer.trim() !== "") {
+        intakeBody = answer.trim();
+        intakeSource = "typed at `doctrina init`";
+        intakeFromTty = true;
+        description = firstLineSummary(intakeBody);
+      }
     }
     if (!description) {
       console.error(c.red("error:") + " no project description given and no terminal to ask on");
@@ -214,6 +265,20 @@ export async function run(_positional, flags) {
     console.log(c.green("created") + ` ${relPath(projectRoot, written)}`);
   }
 
+  // config.json, written from the module that READS it (lib/config.js) for
+  // the same reason index.json is written from its schema: a template copy
+  // is how a project is born already needing a scaffold update. Before this
+  // the file was created by nothing, named in no surface block and reported
+  // by no command — it existed only for someone who had read the source, and
+  // a pt-BR project sat permanently red under `clarify` with no clue why.
+  {
+    const dest = path.join(doctrinaDir, "config.json");
+    if (!isFile(dest) || force) {
+      write(dest, scaffoldConfig(), { force });
+      console.log(c.green("created") + ` ${relPath(projectRoot, dest)}`);
+    }
+  }
+
   // Adapters
   if (agentSelector) {
     const agents = agentSelector === "all" ? SUPPORTED_AGENTS : [agentSelector];
@@ -229,7 +294,7 @@ export async function run(_positional, flags) {
   if (intakeBody) {
     const intakePath = writeIntakeFile(projectRoot, {
       body: intakeBody,
-      source: relPath(projectRoot, path.resolve(projectRoot, intakeFile)),
+      source: intakeSource,
       projectName,
       date,
       force,
@@ -239,7 +304,11 @@ export async function run(_positional, flags) {
 
   console.log("");
   console.log(c.bold("Doctrina initialised."));
-  if (intakeBody) {
+  if (intakeFromTty) {
+    // A person at a terminal gets the one instruction, not the agent's
+    // playbook: the agent reprints it with `doctrina intake`.
+    for (const line of nextStepAfterInit("tty")) console.log(line);
+  } else if (intakeBody) {
     console.log(`Next: execute the bootstrap playbook below — it converts the intake into`);
     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")}.`);
@@ -247,7 +316,7 @@ export async function run(_positional, flags) {
     warnIfThinIntake(intakeBody);
     printBootstrapPlaybook(projectRoot);
   } else {
-    console.log(`Next: edit ${c.cyan("AGENTS.md")} and ${c.cyan(".doctrina/product.md")} for your project.`);
+    for (const line of nextStepAfterInit(null)) console.log(line);
   }
   return 0;
 }
@@ -361,9 +430,12 @@ Options:
   --project-description <text>   One-sentence description
   --agent <name>                 Install adapter for one agent
                                  (claude|codex|cursor|copilot|gemini|aider|windsurf|continue|amp|devin|factory|jules|all)
-  --intake <file>                Full project description; stored verbatim at .doctrina/intake.md
-                                 and used to derive the one-line description when absent.
-                                 Follow up with \`doctrina intake\` for the bootstrap playbook
+  --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
+  --intake-text "<text>"         The same, inline, with no file to write first. Mutually
+                                 exclusive with --intake; either one written without a value
+                                 is a usage error, not a project scaffolded without an intake
   --from <path>                  Local conventions directory; if it contains AGENTS.md and/or
                                  .doctrina/product.md, the content is folded into the new project
   --date <YYYY-MM-DD>            Override the system date