doctrina-cli 0.21.0 → 0.22.0

package/src/commands/work.js

@@ -1,7 +1,6 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { readdirSync } from "node:fs";
 import { eolOf, exists, isDir, isFile, mkdirp, read, relPath, withEol, write } from "../lib/fs-ops.js";
 import { flagString, flagBool } from "../lib/args.js";
 import * as idx from "../lib/index-json.js";
@@ -10,17 +9,18 @@ import { assessBrief } from "../lib/clarity.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
 import { findWorkspace, projectAt, readWorkspace } from "../lib/workspace.js";
 import { readDelivery, resolveDeliveryId, sectionText } from "../lib/delivery.js";
-import { parseLedger } from "../lib/ledger.js";
 import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 import { listHeader } from "../lib/scan.js";
 import { changeNew, reindexChange, addAffectedSpec } from "../lib/change-ops.js";
-import { classify } from "../lib/triage-model.js";
+import { classify, directSignals, trackLines } from "../lib/triage-model.js";
 import { printPlaybookTemplate } from "../lib/playbook.js";
 import { specShape } from "../lib/spec-ops.js";
 import { changedFiles } from "../lib/git.js";
 import { slugFromPrompt, fold, CONFIDENT_MARGIN } from "../lib/lexicon.js";
 import { rankCapabilities, rankCapabilitiesByDiff, similarChanges, SIMILAR_CHANGE_DAYS } from "../lib/work-model.js";
 import { isChangeId, refuseChangeRef } from "../lib/project.js";
+import { nextChangeNumber } from "../lib/change-numbers.js";
+import { withProjectLock } from "../lib/lock.js";
 export { rankCapabilities, rankCapabilitiesByDiff } from "../lib/work-model.js";
 
 // `work` is the second half of the no-ceremony path (ADR 0005): a brief
@@ -176,6 +176,26 @@ export async function run(positional, flags) {
     }
   }
 
+  // THE DIRECT TRACK (change 0255). An edit that changes nothing a spec says
+  // opens nothing: the answer is the three tracks and the two commands that
+  // remain. Only the words that cannot mean behaviour decide it, and naming
+  // a capability, a delivery or an id says the author already chose.
+  if (prompt && verdict && !fromDiff && !chore && !forced &&
+      !flags.has("capability") && !flags.has("delivery") && !flags.has("id")) {
+    const hits = directSignals(prompt, verdict);
+    if (hits.length > 0) {
+      console.log(c.green("direct:") + ` no change to open — this reads as an edit that changes nothing a spec says ${c.gray(`(signals: ${[...new Set(hits)].slice(0, 6).join(", ")})`)}`);
+      console.log(`  Edit it, run ${c.cyan("doctrina verify")}, and commit. No proposal, no delta, no close.`);
+      console.log("");
+      console.log("The tracks, by what the request changes:");
+      for (const line of trackLines()) console.log(line);
+      console.log("");
+      console.log(c.gray("If it does change behaviour, or deserves a record: ") +
+        c.cyan(`doctrina work --force "<request>"`) + c.gray("  ·  ") + c.cyan(`doctrina work --chore "<request>"`));
+      return EXIT.OK;
+    }
+  }
+
   const pinned = flagString(flags, "capability");
   if (pinned && !/^[a-z][a-z0-9-]*$/.test(pinned)) {
     console.error(c.red("error:") + ` invalid capability "${pinned}" (lowercase letters, digits, hyphens)`);
@@ -196,14 +216,19 @@ export async function run(positional, flags) {
   const slug = flags.has("title")
     ? slugify(title)
     : (prompt ? slugFromPrompt(prompt) : "backfill");
-  const id = flagString(flags, "id") ?? `${nextChangeNumber(projectRoot)}-${slug}`;
-  if (!isChangeId(id)) {
+  // The number is read and the folder created under one lock (change 0250):
+  // read apart, eight parallel `work` opened three changes numbered 0003.
+  const opened = withProjectLock(projectRoot, () => {
+    const candidate = flagString(flags, "id") ?? `${nextChangeNumber(projectRoot)}-${slug}`;
+    if (!isChangeId(candidate)) return { id: candidate, code: null };
+    return { id: candidate, code: changeNew([candidate, title], flags) };
+  });
+  const id = opened.id;
+  if (opened.code === null) {
     console.error(c.red("error:") + ` invalid change id "${id}" (lowercase letters, digits, hyphens)`);
     return 2;
   }
-
-  const code = changeNew([id, title], flags);
-  if (code !== 0) return code;
+  if (opened.code !== 0) return opened.code;
 
   // The CLI reduces a prompt to an id deterministically; it cannot write a
   // good short name, and ADR 0005 says it must not try. So it says how to get
@@ -330,7 +355,7 @@ export async function run(positional, flags) {
 // see beats a missing file nothing reports.
 //
 // Returns what was written, or null when the file already exists.
-function scaffoldDelta(projectRoot, { id, capability, guess = null, runnerUp = null }) {
+function scaffoldDelta(projectRoot, { id, capability, guess = /** @type {any} */ (null), runnerUp = /** @type {any} */ (null) }) {
   const deltaPath = path.join(projectRoot, ".doctrina", "changes", id, "specs", capability, "delta.md");
   if (exists(deltaPath)) return null;
   const tpl = read(path.join(locateTemplatesDir(), "change", "spec-delta.md.template"));
@@ -415,8 +440,8 @@ function writeLane(projectRoot, id, verdict, opts) {
   const proposalPath = path.join(projectRoot, ".doctrina", "changes", id, "proposal.md");
   if (!isFile(proposalPath)) return;
   const text = read(proposalPath);
-  // CRLF-safe: the scaffolded proposals are CRLF, and a `.*$` pattern
-  // silently matches nothing against them — the `patch-doctrina-files-as-crlf`
+  // CRLF-safe: a scaffolded proposal may be CRLF, and a `.*$` pattern
+  // silently matches nothing against one — the `check-the-line-ending-before-patching`
   // skill exists for exactly this mistake.
   const updated = text.replace(/^(-[ \t]+\*\*Lane:\*\*)[^\r\n]*/m, `$1 ${line}`);
   if (updated !== text) write(proposalPath, updated, { force: true });
@@ -424,34 +449,6 @@ function writeLane(projectRoot, id, verdict, opts) {
 
 // Next sequential NNNN across open changes and the archive, so work-driven
 // ids stay ordered no matter how earlier changes were named.
-function nextChangeNumber(projectRoot) {
-  const changesDir = path.join(projectRoot, ".doctrina", "changes");
-  let max = 0;
-  const harvest = (name) => {
-    const m = name.match(/^(\d{1,4})-/) ?? name.match(/^(\d{1,4})$/);
-    if (m) max = Math.max(max, Number(m[1]));
-  };
-  if (isDir(changesDir)) {
-    for (const entry of readdirSync(changesDir)) {
-      if (entry === "archive" || entry.startsWith(".")) continue;
-      if (isDir(path.join(changesDir, entry))) harvest(entry);
-    }
-  }
-  const archiveDir = path.join(changesDir, "archive");
-  if (isDir(archiveDir)) {
-    for (const entry of readdirSync(archiveDir)) {
-      if (!isDir(path.join(archiveDir, entry))) continue;
-      harvest(entry.replace(/^\d{4}-\d{2}-\d{2}-/, ""));
-    }
-  }
-  // An abandoned change leaves no folder, only its ledger line (third audit,
-  // change 0234): its number was handed out again, and the ledger then named
-  // two different changes by one id — the abandoned part of a delivery among them.
-  const ledger = path.join(archiveDir, "LEDGER.md");
-  if (isFile(ledger)) for (const e of parseLedger(read(ledger)).entries) harvest(e.id);
-  return String(max + 1).padStart(4, "0");
-}
-
 // Open (non-archived) changes from the index — the set `work --resume` and
 // the thin-prompt guard offer to continue.
 function openChanges(projectRoot) {
@@ -591,7 +588,7 @@ function printChorePlaybook(projectRoot, { id, prompt }) {
   printPlaybookTemplate(projectRoot, "chore", { CHANGE_ID: id, PROMPT: prompt });
 }
 
-function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, clarity, scaffolded = null, fromDiff = false, diffMatches = [] }) {
+function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, clarity, scaffolded = /** @type {any} */ (null), fromDiff = false, diffMatches = /** @type {any[]} */ ([]) }) {
   printPlaybookTemplate(projectRoot, "work", {
     TITLE: fromDiff ? "Backfill playbook" : "Work playbook",
     CHANGE_ID: id,
@@ -720,6 +717,22 @@ A request that mostly repeats a change already open, or archived in the
 last 14 days, is HELD the same way (exit 3), naming it: the same work is
 resumed, or reported as done where it is archived; --force opens it anyway.
 
+TRACKS. How much ceremony a request earns is decided by what it changes,
+not by the size of the diff:
+
+  direct   nothing a spec says — a typo, a comment, formatting, a fix that
+           makes the code do what the spec already says
+           edit · doctrina verify · commit (no change is opened)
+  chore    the build, the tooling or the docs, worth a record — no spec
+           changes: doctrina work --chore "<request>"
+  change   behaviour — a sentence in a spec becomes false, or one is
+           missing: doctrina work "<request>"
+
+A prompt whose words can only mean a direct edit (a typo, whitespace, a
+stale comment, dead code) opens nothing: work prints the tracks and exits
+0. --force opens the change anyway, --chore records it, and naming
+--capability, --delivery or --id skips the reading.
+
 A prompt that reads as a RUNTIME problem — a workflow, an env value, a run
 that executed nothing — is HELD before anything is scaffolded, and pointed
 at \`doctrina triage\` instead (exit 3: a precondition, not a bad prompt).

package/src/commands/workspace.js

@@ -5,7 +5,7 @@ import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { exists, isDir, mkdirp, relPath, write } from "../lib/fs-ops.js";
-import { flagString } from "../lib/args.js";
+import { flagString, flagGivenWithoutValue } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { EXIT, PreconditionError } from "../lib/exit-codes.js";
@@ -29,7 +29,7 @@ const CLI_ENTRY = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..
 
 export const flags = {
   boolean: ["json", "no-git", "remove"],
-  string: ["name", "mode", "role", "about", "depends-on", "agent", "path", "server", "access", "for", "purpose", "hook"],
+  string: ["name", "mode", "role", "about", "depends-on", "agent", "path", "server", "access", "for", "purpose", "only", "hook"],
 };
 
 export async function run(positional, flags) {
@@ -290,11 +290,18 @@ function workspaceTool(wsDir, name, flags) {
     console.log(c.green("removed") + ` tool ${name}`);
     return EXIT.OK;
   }
+  // `--only` with nothing after it is not "no list": taking it for one
+  // removed the list a strict tool had, with exit 0 (change 0250).
+  if (flagGivenWithoutValue(flags, "only")) {
+    console.error(c.red("error:") + " --only needs the calls it allows, e.g. --only \"getJiraIssue,search*\" — or --only none to take the list away");
+    return EXIT.USAGE;
+  }
   let entry;
   try {
     entry = toolEntry(name, {
       server: flagString(flags, "server"), access: flagString(flags, "access"),
       for: flagString(flags, "for"), purpose: flagString(flags, "purpose"),
+      only: flags.has("only") ? flagString(flags, "only") ?? "" : undefined,
     }, at >= 0 ? ws.tools[at] : null);
   } catch (err) {
     console.error(c.red("error:") + ` ${err.message}`);
@@ -304,6 +311,7 @@ function workspaceTool(wsDir, name, flags) {
   else ws.tools.push(entry);
   writeWorkspace(wsDir, ws);
   console.log(c.green(at >= 0 ? "updated" : "declared") + ` ${entry.name} → MCP server "${entry.server}", ${entry.access === "write" ? "read/write (each write asks the human)" : "read-only"}, for ${(entry.for ?? []).join(", ") || "the planner"}`);
+  if (entry.only) console.log(c.gray(`only these calls pass through "${entry.server}": ${entry.only.join(", ")} — every other call is denied`));
   console.log(c.gray(`the server itself is configured in your agent (Cursor: .cursor/mcp.json; Claude Code: .mcp.json) under the name "${entry.server}"`));
   // Said now, not only at the next validate (change 0235): a key that matches
   // no configuration is a guard that never fires.
@@ -350,6 +358,7 @@ function workspaceList(wsDir) {
     console.log(c.bold("Tools"));
     for (const t of ws.tools) {
       console.log(`  ${c.cyan(t.name.padEnd(12))} ${t.server.padEnd(12)} ${t.access.padEnd(6)} ${(t.for ?? []).join(", ").padEnd(16)} ${c.gray(t.purpose ?? "")}`);
+      if (t.only?.length) console.log(c.gray(`  ${"".padEnd(12)} only: ${t.only.join(", ")}`));
     }
   }
   // The orchestrator files carry what changes without a workspace write — a
@@ -394,12 +403,16 @@ artifacts of repositories that cannot carry .doctrina/ themselves.
       files when a project's state or workspace.json changed since.
 
   tool <name> [--server <mcp-name>] [--access read|write] [--for <roles>]
-              [--purpose "<what for>"] [--remove]
+              [--purpose "<what for>"] [--only "<calls>"] [--remove]
       Declare (or update, or --remove) a tool the work uses. Presets:
       jira, confluence, figma, playwright, datadog, databricks, sql.
       Roles: planner, executor, qa, observer, reviewer. Access defaults
       to read: the guard refuses a write through a read-only tool and
       makes a declared write wait for the human.
+      --only "getJiraIssue,search*" lists the calls the tool may make,
+      by MCP tool name (\`*\` for any run of characters): every other
+      call through its server is denied, instead of being judged by the
+      verb in its name. --only none takes the list away.
 
   guard --hook cursor|claude
       The pre-call hook the workspace installs (Cursor beforeMCPExecution,

package/src/index.js

@@ -34,6 +34,8 @@ const COMMANDS = {
   context: () => import("./commands/context.js"),
   search: () => import("./commands/search.js"),
   intake: () => import("./commands/intake.js"),
+  onboard: () => import("./commands/onboard.js"),
+  ui: () => import("./commands/ui.js"),
   work: () => import("./commands/work.js"),
   coverage: () => import("./commands/coverage.js"),
   verify: () => import("./commands/verify.js"),
@@ -110,6 +112,13 @@ async function main(argv) {
   }
 
   if (positional.length === 0) {
+    // In a terminal, `doctrina` alone opens the console (change 0257): a
+    // person who typed the name and nothing else is asking where to start.
+    // A pipe, a script or an agent still gets the help it always got.
+    if (argv.length === 0 && process.stdin.isTTY && process.stdout.isTTY) {
+      const ui = await COMMANDS.ui();
+      return ui.run([], new Map());
+    }
     process.stdout.write(TOP_HELP);
     return 0;
   }

package/src/lib/actions.js

@@ -1,5 +1,6 @@
 // @ts-check
 import path from "node:path";
+import { conflictedArtifacts } from "./conflict-markers.js";
 import { readdirSync } from "node:fs";
 import { isDir, isFile, read, relPath, walk } from "./fs-ops.js";
 import * as idx from "./index-json.js";
@@ -98,6 +99,24 @@ export function computeActions(projectRoot, gates = {}) {
   /** @type {Action[]} */
   const actions = [];
 
+  // A MERGE THAT STOPPED INSIDE AN ARTIFACT comes before everything (change
+  // 0250): every action below is computed from files that hold both halves
+  // of a conflict, and the next thing an agent does with a spec is read it.
+  try {
+    const conflicted = conflictedArtifacts(projectRoot);
+    if (conflicted.length > 0) {
+      const first = path.relative(projectRoot, conflicted[0].file).split(path.sep).join("/");
+      actions.push(action({
+        id: "merge-conflict",
+        command: "validate",
+        gate: "structure",
+        runnable: false,
+        why: `${conflicted.length} artifact${conflicted.length === 1 ? " carries" : "s carry"} git's merge conflict markers (first: ${first}:${conflicted[0].line})`,
+        text: `resolve the merge conflict in ${first} (line ${conflicted[0].line})${conflicted.length > 1 ? ` and ${conflicted.length - 1} more` : ""} — keep what both branches meant and delete the marker lines; \`doctrina validate\` names each file`,
+      }));
+    }
+  } catch { /* an unreadable tree is reported by the checks below */ }
+
   // RUNTIME FIRST (change 0029). A declared wiring that does not hold is
   // not a queue item — it is the reason the last run lied. After a job goes
   // green having executed nothing, "open a change on the observability

package/src/lib/adapters.js

@@ -148,9 +148,12 @@ export const RETIRED_ADAPTER_FILES = Object.freeze({
  * @param {Record<string, string>} tokens  as `adapter add` renders with
  * @param {string} [root]  where the files live: the shadow folder of a shadowed repository
  */
+// The core loop an adapter installs as slash commands or skills.
+const CORE_LOOP_FILE = /(^|\/)doctrina-[a-z-]+(\.md|\/SKILL\.md)$/;
+
 export function planAdapterMigration(projectRoot, tokens, root = projectRoot) {
-  /** @type {{ writes: Array<{ relativePath: string, content: string }>, removes: string[], kept: string[] }} */
-  const plan = { writes: [], removes: [], kept: [] };
+  /** @type {{ writes: Array<{ relativePath: string, content: string }>, removes: string[], kept: string[], added: Array<{ relativePath: string, content: string }> }} */
+  const plan = { writes: [], removes: [], kept: [], added: [] };
   const norm = (/** @type {string} */ s) => s.replace(/\r\n/g, "\n").trim();
   for (const [name, list] of Object.entries(RETIRED_ADAPTER_FILES)) {
     const spec = adapterFiles(projectRoot, name);
@@ -165,6 +168,23 @@ export function planAdapterMigration(projectRoot, tokens, root = projectRoot) {
       (norm(read(path.join(root, retired))) === norm(body) ? plan.removes : plan.kept).push(retired);
     }
   }
+  // A family the adapter installed gains the member a newer CLI ships
+  // (change 0256). `/doctrina-onboard` reached only the projects that ran
+  // `adapter add` again: the upgrade compared nothing but retired files. An
+  // adapter is read as installed by its own core-loop files, so one the
+  // project never added is never written. Not in a shadow, where every
+  // file is also a link the workspace owns.
+  if (root === projectRoot) {
+    for (const name of listAdapterNames(projectRoot)) {
+      const family = (adapterFiles(projectRoot, name)?.files ?? [])
+        .filter((f) => CORE_LOOP_FILE.test(f.relativePath));
+      if (!family.some((f) => isFile(path.join(root, f.relativePath)))) continue;
+      for (const f of family) {
+        if (isFile(path.join(root, f.relativePath)) || plan.writes.some((w) => w.relativePath === f.relativePath)) continue;
+        plan.added.push({ relativePath: f.relativePath, content: renderAdapterFile(f, tokens) });
+      }
+    }
+  }
   return plan;
 }
 
@@ -175,7 +195,7 @@ export function planAdapterMigration(projectRoot, tokens, root = projectRoot) {
  * @returns {Array<{ rel: string, content: string }>}
  */
 export function applyAdapterMigration(root, plan) {
-  for (const w of plan.writes) {
+  for (const w of [...plan.writes, ...(plan.added ?? [])]) {
     mkdirp(path.dirname(path.join(root, w.relativePath)));
     write(path.join(root, w.relativePath), w.content, { force: true });
   }