doctrina-cli 0.21.0 → 0.22.0

package/src/lib/code-inventory.js

@@ -57,6 +57,7 @@ const JS_SIGNALS = {
 const PY_SIGNALS = {
   django: "Django", djangorestframework: "Django REST framework", flask: "Flask", fastapi: "FastAPI",
   sqlmodel: "SQLModel", pydantic: "Pydantic", pytest: "pytest", behave: "Behave", robotframework: "Robot Framework",
+  ruff: "Ruff", mypy: "mypy",
   selenium: "Selenium", playwright: "Playwright", requests: "requests", httpx: "HTTPX", sqlalchemy: "SQLAlchemy",
   alembic: "Alembic", pandas: "pandas", pyspark: "PySpark", locust: "Locust", celery: "Celery", grpcio: "gRPC",
   streamlit: "Streamlit", langchain: "LangChain", openai: "OpenAI SDK", anthropic: "Anthropic SDK", uvicorn: "Uvicorn",
@@ -144,7 +145,7 @@ function walk(root) {
   let truncated = false;
   const stack = [""];
   while (stack.length && !truncated) {
-    const rel = stack.pop();
+    const rel = stack.pop() ?? "";
     let entries;
     try {
       entries = readdirSync(path.join(root, rel), { withFileTypes: true });
@@ -300,14 +301,14 @@ function readUnits(root, files) {
     const kind = MANIFESTS.find(([re]) => re.test(baseOf(f)))?.[1];
     if (!kind) continue;
     if (!byDir.has(dir)) byDir.set(dir, new Set());
-    byDir.get(dir).add(kind);
+    byDir.get(dir)?.add(kind);
     manifestsOf.set(dir, [...(manifestsOf.get(dir) ?? []), baseOf(f)]);
   }
   const rootPkg = isFile(path.join(root, "package.json")) ? readJson(path.join(root, "package.json")) : null;
   const units = [];
   for (const dir of [...byDir.keys()].sort((a, b) => depth(a) - depth(b) || a.localeCompare(b))) {
-    const kinds = [...byDir.get(dir)].sort();
-    const manifests = manifestsOf.get(dir).sort();
+    const kinds = [...(byDir.get(dir) ?? [])].sort();
+    const manifests = (manifestsOf.get(dir) ?? []).sort();
     const signals = new Set();
     let runner = null;
     let scripts = {};
@@ -396,6 +397,22 @@ function unitCommands(root, unit, units, workspaces, files) {
       }
     } else if (kind === "python") {
       const own = files.filter((f) => unitOf(units, f) === unit);
+      const from = `${unit.dir ? unit.dir + "/" : ""}${unit.manifests.join(", ")}`;
+      const pyproject = readText(root, unit.dir ? `${unit.dir}/pyproject.toml` : "pyproject.toml");
+      const setupCfg = readText(root, unit.dir ? `${unit.dir}/setup.cfg` : "setup.cfg");
+      const locked = (/** @type {string} */ f) => at(f) || isFile(path.join(root, f));
+      const via = locked("uv.lock") ? "uv run " : locked("poetry.lock") ? "poetry run " : locked("Pipfile.lock") ? "pipenv run " : "";
+      // The linter and the type checker the project DECLARES (seventh audit,
+      // change 0250): a Python project was seeded with its tests and nothing
+      // else, where a Node one gets `lint` and `typecheck` from its scripts.
+      // Python has no scripts table, so the declaration is the dependency or
+      // the tool's own configuration.
+      if (unit.signals.includes("Ruff") || at("ruff.toml") || at(".ruff.toml") || /\[tool\.ruff/.test(pyproject)) {
+        out.push({ name: `lint${tag}`, command: `${via}ruff check .`, cwd, from, seed: true });
+      }
+      if (unit.signals.includes("mypy") || at("mypy.ini") || /\[tool\.mypy/.test(pyproject) || /^\[mypy\]/m.test(setupCfg)) {
+        out.push({ name: `typecheck${tag}`, command: `${via}mypy .`, cwd, from, seed: true });
+      }
       const hasTests = own.some((f) => /(^|\/)(test_[^/]*|[^/]*_test)\.py$/.test(f));
       if (!hasTests) continue; // pytest declared with nothing to run is not a gate
       // Seed the runner the project DECLARES. Test files alone say nothing
@@ -479,7 +496,7 @@ export function inventory(root) {
   // Languages, counted by file extension — what is actually written here.
   const languages = new Map();
   for (const f of files) {
-    const ext = baseOf(f).includes(".") ? baseOf(f).split(".").pop().toLowerCase() : "";
+    const ext = baseOf(f).includes(".") ? (baseOf(f).split(".").pop() ?? "").toLowerCase() : "";
     const lang = LANG_BY_EXT[ext];
     if (lang) languages.set(lang, (languages.get(lang) ?? 0) + 1);
   }

package/src/lib/commands.js

@@ -12,7 +12,7 @@
 // Keep this sorted by the workflow order used in `--help`, not alphabetically.
 export const COMMAND_NAMES = [
   // bootstrap / day-to-day
-  "init", "intake", "triage", "work",
+  "init", "ui", "onboard", "intake", "triage", "work",
   // authoring
   "spec", "change", "contract", "decision", "skill", "intent", "adapter",
   // read / orient
@@ -37,6 +37,8 @@ export const COMMAND_NAMES = [
 // every op.
 export const OPERATIONS = [
   ["init", "Scaffold AGENTS.md and .doctrina/ in the current directory"],
+  ["ui", "The console: type requests, run commands, watch the agent work"],
+  ["onboard", "Walk the whole cycle once on this repository, step by step"],
   ["intake", "Store the full project description; print the bootstrap playbook"],
   ["triage", "Classify a request into a lane, and check the runtime surface"],
   ["work", "Brief prompt -> scaffolded change + guided work playbook"],
@@ -49,6 +51,7 @@ export const OPERATIONS = [
   ["change check", "Pre-close dry-run: everything close would refuse, listed first"],
   ["change tick", "List/tick the unchecked boxes (tasks + verification; --all)"],
   ["change abandon", "Discard an open change cleanly (recorded in the ledger)"],
+  ["change renumber", "Give an open change the next free number (two branches took the same one)"],
   ["change delta", "Add a requirement/criterion/bump to a change's delta (ops written for you)"],
   ["change card", "One task as an executor receives it: the task, its why, the spec cut to it"],
   ["contract new", "Own the integration surface (ports, env, interfaces)"],
@@ -104,6 +107,7 @@ export const OPERATIONS = [
   ["templates update", "Additive fixer for check findings (preview; --write applies)"],
   ["hooks install", "Install the pre-commit hook"],
   ["index rebuild", "Regenerate index.json from the artifacts on disk"],
+  ["index merge", "The merge driver git runs for index.json (set up by hooks install)"],
   ["next", "Print the recommended next workflow actions"],
   ["watch", "Re-run validate --fix + next on every change (--once for one pass)"],
   ["metrics", "Local git-derived adoption metrics (no network)"],
@@ -132,6 +136,8 @@ export const OPERATIONS = [
 // `templates check` fails when either is missing.
 export const COMMAND_META = {
   init:         { moment: "Bootstrap",  when: "starting a project that has no AGENTS.md yet", purpose: "scaffold AGENTS.md and .doctrina/" },
+  ui:           { moment: "Bootstrap",  when: "a human wants to drive the project from one window instead of typing commands", purpose: "the interactive console: requests to the agent, commands, the project's state" },
+  onboard:      { moment: "Bootstrap",  when: "the first session in a project, or showing it to someone new", purpose: "walk the whole cycle once, step by step, on this repository" },
   intake:       { moment: "Bootstrap",  when: "you have a full project description and no specs yet", purpose: "store the intent and print the bootstrap playbook" },
   adapter:      { moment: "Bootstrap",  when: "adding or removing an agent's pointer files", purpose: "install/remove agent adapters (additive)" },
 
@@ -351,7 +357,40 @@ const COMPACT_MOMENTS = new Set(["Orchestrate", "Maintain"]);
 // trigger: an agent scanning it learns WHEN to reach for a command, which
 // a name index never told it. Same shape `context` prints for skills —
 // description plus `when:`, body on demand.
-export function surfaceMarkdown() {
+// TWO PROFILES OF THE SAME CATALOG (change 0251).
+//
+// `full` names every command, by moment. It is what this block has always
+// been, and it costs 37 lines of a file capped at 150 that an agent reads
+// on every turn — for 39 commands, most of which a session never reaches
+// for. `core` names the loop a session actually runs and defers the rest to
+// `doctrina --help`, which is where the playbook a command prints already
+// sends the agent for the next step. A project chooses in
+// `.doctrina/config.json` ("surface"); `init` writes `core` for a new one.
+export const SURFACE_PROFILES = Object.freeze(["full", "core"]);
+export const CORE_SURFACE = Object.freeze(["prime", "work", "context", "close", "next", "validate", "doctor", "handoff"]);
+
+function coreSurfaceMarkdown() {
+  const lines = [
+    "## Doctrina command surface (generated — reach for these, don't hand-author)",
+    "",
+    "The loop a session runs. Each command prints the next step; the CLI",
+    "scaffolds from canonical templates and syncs `index.json`.",
+  ];
+  for (const cmd of CORE_SURFACE) {
+    const meta = COMMAND_META[cmd];
+    const hint = SURFACE_HINTS[cmd] ? ` ${SURFACE_HINTS[cmd]}` : "";
+    lines.push(`- \`doctrina ${cmd}${hint}\` — ${meta.purpose}. *When:* ${meta.when}.`);
+  }
+  lines.push("**Everything else** — specs, changes by hand, decisions, contracts, skills, the single gates, " +
+    "workspaces and deliveries: `doctrina --help` lists every command with its moment, and " +
+    "`doctrina <command> --help` its flags. (`\"surface\": \"full\"` in `.doctrina/config.json`, then " +
+    "`doctrina upgrade --write`, lists them all here.)");
+  return lines.join("\n");
+}
+
+/** @param {string} [profile] "full" (every command) or "core" (the session loop) */
+export function surfaceMarkdown(profile = "full") {
+  if (profile === "core") return coreSurfaceMarkdown();
   // A deprecated operation stays in the catalog — `--help` and the shell
   // completions must still know the name someone types — but leaves this
   // block: it is the list of commands to REACH FOR, and pointing an agent at
@@ -400,8 +439,8 @@ export function surfaceMarkdown() {
 }
 
 // The block as written to AGENTS.md: markers wrapping the generated section.
-export function surfaceBlock() {
-  return `${SURFACE_BEGIN}\n${surfaceMarkdown()}\n${SURFACE_END}`;
+export function surfaceBlock(profile = "full") {
+  return `${SURFACE_BEGIN}\n${surfaceMarkdown(profile)}\n${SURFACE_END}`;
 }
 
 // The block's CANONICAL POSITION, defined once — by the shipped template,
@@ -543,6 +582,13 @@ export const AGENT_CHANGELOG = {
   // Each entry lists only ITS OWN delta. The series carries the rest
   // forward (see agentChangelogEntries), so a patch never has to restate
   // the minor that introduced the commands, and never silently erases it.
+  "0.22.0": [
+    "An edit that changes nothing a spec says opens no change: `doctrina work` answers `direct` and exits 0 — edit, run `doctrina verify`, commit. `--force` only when a sentence of a spec does change.",
+    "Run `doctrina hooks install` once in each clone and commit the `.gitattributes` it writes: `index.json` and the ledger then merge across branches. Two open changes with one number: `doctrina change renumber <id>`.",
+    "A requirement that claims something of every input is proven by a property-based test: claim it with `doctrina change delta <id> <cap> --property \"…\"`; an example test cited for `[property]` fails `coverage --strict`. `doctrina coverage --properties` lists the candidates.",
+    "A request \"sent by the Doctrina console <name>\" is done in this repository and your last message is its report — never hand it on. Told other consoles are open, `doctrina ui --send <name> \"<self-contained task>\"` hands one a task and waits for the report.",
+    "A new project's AGENTS.md lists the session loop only (`surface: core`); `doctrina --help` has every command. `doctrina onboard` walks a newcomer through the cycle; `init --preset <dir>` lays an organisation's preset.",
+  ],
   "0.21.0": [
     "At a workspace root, `next`, `handoff`, `status`, `validate`, `context`, `doctor` and `metrics` answer for the workspace; never `doctrina init` there or in a shadowed repository's clone — the commands name `doctrina workspace attach` instead.",
     "A task card carries the delta, the delivery's story and every binding decision, global ones included: as an executor, stop and report when the story or the task contradicts one; a card on placeholder tasks means the planner writes them first (`doctrina work --resume <id>`).",

package/src/lib/config.js

@@ -20,6 +20,8 @@ import { isFile, read } from "./fs-ops.js";
 
 export const CONFIG_REL = ".doctrina/config.json";
 export const RULES_REL = ".doctrina/rules.json";
+/** The values `surface` takes — the profiles of lib/commands.js, named here so the config has no import to cycle on. */
+const SURFACE_VALUES = ["full", "core"];
 
 // The built-in default for every option. `language: null` means "detect per
 // file", which is what the absence of a declaration has always meant.
@@ -27,6 +29,7 @@ export const DEFAULTS = Object.freeze({
   language: null,
   context_budget: 15000,
   rules: [],
+  surface: "full",
 });
 
 // Where a value came from, most authoritative first. The strings are printed
@@ -53,8 +56,8 @@ export function configPath(projectRoot) {
  *
  * @param {string} projectRoot
  * @returns {{
- *   language: string|null, context_budget: number, rules: any[],
- *   sources: {language: string, context_budget: string, rules: string},
+ *   language: string|null, context_budget: number, rules: any[], surface: string,
+ *   sources: {language: string, context_budget: string, rules: string, surface: string},
  *   errors: string[],
  *   unknown: string[]
  * }}
@@ -65,12 +68,12 @@ export function loadConfig(projectRoot) {
   // Keys the CLI does not know (change 0115). `{"context_budjet": 10}` was
   // silence at every door, and the author believed the budget was set.
   // Reported, never rejected: the effective values are unchanged.
-  const KNOWN_KEYS = new Set(["language", "context_budget", "rules", "$comment", "$schema"]);
+  const KNOWN_KEYS = new Set(["language", "context_budget", "rules", "surface", "preset", "$comment", "$schema"]);
   const unknown = cfg && typeof cfg === "object" && !Array.isArray(cfg)
     ? Object.keys(cfg).filter((k) => !KNOWN_KEYS.has(k))
     : [];
-  /** @type {{language: string, context_budget: string, rules: string}} */
-  const sources = { language: SOURCES.default, context_budget: SOURCES.default, rules: SOURCES.default };
+  /** @type {{language: string, context_budget: string, rules: string, surface: string}} */
+  const sources = { language: SOURCES.default, context_budget: SOURCES.default, rules: SOURCES.default, surface: SOURCES.default };
 
   // language — config.json has always been its only home.
   //
@@ -79,6 +82,7 @@ export function loadConfig(projectRoot) {
   // "default" would tell a reader the file does not say what it plainly
   // says. Only a key that is absent, or one whose value is rejected, falls
   // back to the default.
+  /** @type {string | null} */
   let language = DEFAULTS.language;
   if (cfg && "language" in cfg) {
     const rawLang = cfg.language;
@@ -130,7 +134,18 @@ export function loadConfig(projectRoot) {
     }
   }
 
-  return { language, context_budget, rules, sources, errors, unknown };
+  // surface — which commands AGENTS.md lists (change 0251).
+  let surface = DEFAULTS.surface;
+  if (cfg && "surface" in cfg) {
+    if (SURFACE_VALUES.includes(cfg.surface)) {
+      surface = cfg.surface;
+      sources.surface = SOURCES.config;
+    } else {
+      errors.push(`${CONFIG_REL}: unknown surface ${JSON.stringify(cfg.surface)} (use "core" or "full")`);
+    }
+  }
+
+  return { language, context_budget, rules, surface, sources, errors, unknown };
 }
 
 /**
@@ -148,6 +163,7 @@ export function configRows(projectRoot) {
     { option: "language", value: show(cfg.language), source: cfg.sources.language, configured: cfg.sources.language !== SOURCES.default },
     { option: "context_budget", value: `${cfg.context_budget} tokens`, source: cfg.sources.context_budget, configured: cfg.sources.context_budget !== SOURCES.default },
     { option: "rules", value: `${cfg.rules.length} rule${cfg.rules.length === 1 ? "" : "s"}`, source: cfg.sources.rules, configured: cfg.sources.rules !== SOURCES.default },
+    { option: "surface", value: cfg.surface === "core" ? "core (the session loop)" : "full (every command)", source: cfg.sources.surface, configured: cfg.sources.surface !== SOURCES.default },
   ];
 }
 
@@ -193,14 +209,17 @@ function readJson(file, rel, errors) {
  *
  * @returns {string} the file's contents, newline-terminated
  */
-export function scaffoldConfig() {
+export function scaffoldConfig({ surface = /** @type {string | null} */ (null) } = {}) {
   return JSON.stringify({
     $comment:
-      "Doctrina project configuration. Nothing is declared here yet — add a key to " +
+      "Doctrina project configuration — add a key to " +
       "change it. Options: \"language\" (\"en\" | \"pt\", or null to detect per file); " +
+      "\"surface\" (\"core\": AGENTS.md lists the session loop and defers the rest to `doctrina --help`; " +
+      "\"full\": it lists every command; then `doctrina upgrade --write`); " +
       `"context_budget" (positive integer, default ${DEFAULTS.context_budget}); ` +
       "\"rules\" (array of { id, forbid, paths, message } — permanent project " +
       "constraints enforced by `doctrina validate`). Run `doctrina doctor` to see the " +
       "effective value of each option and where it came from.",
+    ...(surface ? { surface } : {}),
   }, null, 2) + "\n";
 }

package/src/lib/conflict-markers.js

@@ -0,0 +1,61 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read, walk } from "./fs-ops.js";
+
+// A MERGE THAT STOPPED INSIDE AN ARTIFACT (seventh audit, change 0250).
+//
+// Two branches each added a requirement to the same section of a spec, the
+// merge stopped with `<<<<<<<` / `=======` / `>>>>>>>` in the file, and
+// `validate` answered "0 errors": the markers are not headers, bullets or
+// criteria, so no check had a reason to look at them. A spec is read as
+// written — by the agent, by `context`, by `apply` — markers and both
+// halves included.
+
+/**
+ * The line of the first conflict marker, or null. A file is conflicted when
+ * it holds an opening AND a closing marker at the start of a line, outside a
+ * fenced block (a document may show the markers as an example).
+ */
+export function conflictMarkerLine(text) {
+  let fenced = false;
+  let opened = null;
+  const lines = String(text).split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    if (/^[ \t]*(```|~~~)/.test(lines[i])) fenced = !fenced;
+    if (fenced) continue;
+    if (opened === null && /^<{7}( |$)/.test(lines[i])) opened = i + 1;
+    else if (opened !== null && /^>{7}( |$)/.test(lines[i])) return opened;
+  }
+  return null;
+}
+
+/** The Markdown a session reads as current truth: the hub, the product, specs, decisions, skills, contracts, open changes. */
+export function livingArtifacts(projectRoot) {
+  const root = path.join(projectRoot, ".doctrina");
+  const out = [path.join(projectRoot, "AGENTS.md"), path.join(root, "product.md")].filter(isFile);
+  for (const dir of ["specs", "decisions", "skills", "contracts"]) {
+    out.push(...walk(path.join(root, dir)).filter((f) => f.endsWith(".md")));
+  }
+  const changes = path.join(root, "changes");
+  if (isDir(changes)) {
+    for (const entry of readdirSync(changes)) {
+      if (entry === "archive" || entry.startsWith(".")) continue;
+      out.push(...walk(path.join(changes, entry)).filter((f) => f.endsWith(".md")));
+    }
+  }
+  return out;
+}
+
+/**
+ * Every living artifact a merge stopped in.
+ * @returns {{ file: string, line: number }[]}
+ */
+export function conflictedArtifacts(projectRoot) {
+  const out = [];
+  for (const file of livingArtifacts(projectRoot)) {
+    const line = conflictMarkerLine(read(file));
+    if (line !== null) out.push({ file, line });
+  }
+  return out;
+}