doctrina-cli 0.20.0 → 0.21.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.20.0 — current release. Zero runtime dependencies
+**Status:** v0.21.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install
@@ -29,7 +29,7 @@ Change      triage · work · spec new|list|set · change new|apply|archive|chec
             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
-Orchestrate workspace init|add|attach|detach|list|tool|guard · delivery new|route|list|status|check|close
+Orchestrate workspace init|add|attach|detach|list|tool|guard · delivery new|route|list|status|tick|check|close
 Maintain    upgrade · index rebuild · hooks install · watch · metrics · completion · ci · templates list
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [

package/src/commands/adapter.js

@@ -2,6 +2,8 @@
 import path from "node:path";
 import process from "node:process";
 import { exists, isFile, mkdirp, pruneEmptyDirs, read, relPath, remove, write } from "../lib/fs-ops.js";
+import { applyAdapterMigration, planAdapterMigration } from "../lib/adapters.js";
+import { relinkShadow, shadowRootOf } from "../lib/workspace.js";
 import {
   ADAPTER_STATES, adapterFiles, describeAdapter, listAdapterNames, renderAdapterFile,
   isMergedConfig, mergeJson, unmergeJson, containsJson, holdsAnyOf,
@@ -137,6 +139,14 @@ function adapterAdd(projectRoot, name, cmdFlags) {
     written += 1;
   }
 
+  // An adapter installed before its files moved (change 0238): the copies
+  // the CLI wrote under the old paths go, an edited one stays and is named.
+  const filesRoot = shadowRootOf(projectRoot) ?? projectRoot;
+  const moves = planAdapterMigration(projectRoot, tokens, filesRoot);
+  const gone = applyAdapterMigration(filesRoot, moves);
+  relinkShadow(projectRoot, gone);
+  for (const g of gone) console.log(c.green("removed") + ` ${g.rel} (replaced by its skill)`);
+  for (const rel of moves.kept) console.log(c.yellow("kept   ") + ` ${rel} (edited since install — Cursor now reads the skill; remove it once your edits are moved)`);
   console.log("");
   console.log(`${c.bold("Adapter " + name)} — ${written} file${written === 1 ? "" : "s"} written` +
     (skipped > 0 ? `, ${skipped} left alone` : "") +

package/src/commands/change.js

@@ -2,16 +2,16 @@
 import { parseChecklist, getSection, getHeader, parseChangeTitle } from "../lib/doc-model.js";
 import path from "node:path";
 import process from "node:process";
-import { exists, isDir, isFile, lineCount, mkdirp, move, read, relPath, remove, walk, write } from "../lib/fs-ops.js";
+import { eolOf, exists, isDir, isFile, lineCount, mkdirp, move, read, relPath, remove, walk, withEol, write } from "../lib/fs-ops.js";
 import { diffLines, formatUnified } from "../lib/diff.js";
 import { locateTemplatesDir, loadTemplateTree, materialiseEntry } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
-import { archivedChangeEntry, deriveIndex } from "../lib/scan.js";
+import { archivedChangeEntry, deriveIndex, listHeader } from "../lib/scan.js";
 import { extractOps, applyOps } from "../lib/spec-ops.js";
 import { printAdrCheckpoint } from "../lib/adr-guard.js";
 import { GATES, TRANSITIONS, checkTransition, recordForcedGap } from "../lib/gates.js";
 import { today } from "../lib/dates.js";
-import { flagBool, flagString } from "../lib/args.js";
+import { flagAll, flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { appendLedgerLine, archivedLine, abandonedLine } from "../lib/ledger.js";
 import { suggest } from "../lib/suggest.js";
@@ -21,6 +21,7 @@ import { EXIT } from "../lib/exit-codes.js";
 import { ensureDoctrinaProject, refuseChangeRef } from "../lib/project.js";
 import { parseOperation, parseCapabilityFromDelta, isUntouchedScaffold } from "../lib/doc-model.js";
 import { changeNew, addDeltaOps } from "../lib/change-ops.js";
+import { scanText } from "../lib/clarify-scan.js";
 
 const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "abandon", "delta", "card"];
 
@@ -103,8 +104,26 @@ function changeCard(args) {
   if (card.why) {
     L.push("", "## Why the change exists", "", card.why);
   }
+  if (card.story) {
+    L.push("", `## The story (delivery ${card.delivery})`, "", card.story);
+  }
+  // What the change does to the spec — the requirement the card implements
+  // is here, not in the spec as it stands (change 0231).
+  if (card.changes.length > 0) {
+    L.push("", "## What this change does to the spec", "");
+    for (const ch of card.changes) L.push(`- ${ch.capability} ${ch.line}`);
+  }
   for (const s of card.slices) {
-    L.push("", `## Spec — ${s.capability} (cut to this task)`, "", s.text.trim());
+    L.push("", `## Spec — ${s.capability} as it stands (${s.whole ? "whole: nothing in it matched the task" : "cut to this task"})`, "", s.text.trim());
+  }
+  if (card.decisions.list.length > 0) {
+    L.push("", "## Decisions that bind it", "");
+    for (const d of card.decisions.list) {
+      L.push(`- ADR ${d.id} — ${d.title} (\`doctrina show ${d.id}\`)`);
+      if (d.decision) L.push(`  ${d.decision}`);
+    }
+    if (card.decisions.more > 0) L.push(`- … and ${card.decisions.more} more accepted global decisions — \`doctrina prime --rules\``);
+    L.push("", "Where the story or the task contradicts one of these, stop and report it: the decision stands until the planner supersedes it.");
   }
   L.push("", "## When done", "");
   L.push(card.fields.verify
@@ -417,6 +436,13 @@ async function changeCheck(id, { verbose = false } = {}) {
       opsFindings += 1;
     } else {
       console.log(c.green("✓ ") + `${rel}: ${result.applied.length} op${result.applied.length === 1 ? "" : "s"} would apply cleanly`);
+      // What clarify will say about the spec once this lands (change 0232):
+      // the smells the merged spec has and the current one does not.
+      // Advisory — clarify is not a close gate — but a project that runs
+      // `clarify --all` in its build learned about the word mid-close.
+      for (const smell of newSmells(read(targetPath), result.text, projectRoot)) {
+        console.log(c.yellow("! ") + `${rel}: writes ${smell.rule} "${smell.token}" into ${capability}'s spec — ${smell.hint} (\`clarify\` flags it after apply)`);
+      }
     }
   }
   if (deltaFiles.length === 0) console.log(c.gray("- no spec deltas"));
@@ -484,14 +510,17 @@ function changeDelta(args, flags) {
   }
   // In the order a reader expects them: requirement, criterion, any raw op,
   // and the bump last.
+  // `--requirement`, `--criterion` and `--op` repeat (change 0228): each
+  // occurrence is one op, in the order given. The parser keeps the last
+  // value of a repeated flag, so reading them with flagString wrote one op
+  // and reported success for a command line that asked for three.
   const lines = [];
-  const requirement = flagString(flags, "requirement");
-  const criterion = flagString(flags, "criterion");
-  const raw = flagString(flags, "op") ?? (rest.length > 0 ? rest.join(" ") : undefined);
+  const raw = flagAll(flags, "op");
+  if (raw.length === 0 && rest.length > 0) raw.push(rest.join(" "));
   const bump = flagString(flags, "bump");
-  if (requirement) lines.push(`append-requirement ${requirement}`);
-  if (criterion) lines.push(`append-criterion ${criterion}`);
-  if (raw) lines.push(raw);
+  for (const r of flagAll(flags, "requirement")) lines.push(`append-requirement ${r}`);
+  for (const r of flagAll(flags, "criterion")) lines.push(`append-criterion ${r}`);
+  lines.push(...raw);
   if (bump) lines.push(`bump-version ${bump}`);
 
   const r = addDeltaOps(projectRoot, id, capability, lines);
@@ -614,11 +643,12 @@ function changeTick(args, flags) {
     byPath.get(box.file.path).push(box);
   }
   for (const [filePath, hits] of byPath) {
-    const lines = read(filePath).split(/\r?\n/);
+    const before = read(filePath);
+    const lines = before.split(/\r?\n/);
     for (const box of hits) {
       lines[box.lineIndex] = lines[box.lineIndex].replace(/\[ \]/, "[x]");
     }
-    write(filePath, lines.join("\n"), { force: true });
+    write(filePath, withEol(lines.join("\n"), eolOf(before)), { force: true });
   }
   console.log(c.green("ticked ") + `${picked.length} box${picked.length === 1 ? "" : "es"} in ${byPath.size} file${byPath.size === 1 ? "" : "s"}`);
   return 0;
@@ -771,13 +801,22 @@ async function changeAbandon(args, flags) {
 
   const reason = flagString(flags, "reason") ?? "";
   const date = today();
+  // The delivery it belonged to stays on record (third audit, change 0234):
+  // the proposal that carried it is deleted, and the delivery's status went
+  // back to "no change yet", as if the planner had never decided anything.
+  const proposalFile = path.join(changeDir, "proposal.md");
+  const delivery = isFile(proposalFile) ? (listHeader(read(proposalFile), "Delivery") ?? "").trim() : "";
+  const recorded = delivery ? `${reason ? `${reason} ` : ""}(delivery ${delivery})` : reason;
 
   remove(changeDir);
   console.log(c.green("removed") + ` ${relPath(projectRoot, changeDir)}`);
 
   // Ledger line so the abandonment is part of the visible history.
-  const ledgerFile = appendLedgerLine(projectRoot, abandonedLine(id, reason, date));
+  const ledgerFile = appendLedgerLine(projectRoot, abandonedLine(id, recorded, date));
   console.log(c.green("ledger") + ` +1 line in ${relPath(projectRoot, ledgerFile)}`);
+  if (delivery) {
+    console.log(c.gray("hint: ") + `it was this repository's part of delivery ${delivery} — from the workspace, re-route the delivery without this repository (\`doctrina delivery route ${delivery} <the others>\`) or open a new change here with \`doctrina work "<title>" --delivery ${delivery}\``);
+  }
 
   // Drop the change entry; rebuild from the tree so nothing drifts.
   const current = idx.load(projectRoot);
@@ -830,6 +869,26 @@ export function printDeltaPreview(projectRoot, changeDir, deltaFiles) {
         continue;
       }
       console.log(c.yellow("MODIFIED") + ` ${targetRel}`);
+      // A delta with an ops block is previewed as the spec it produces (change
+      // 0228): the ops run in memory, as apply runs them, and the diff is the
+      // spec before against the spec after. Diffing the spec against the
+      // delta FILE printed every line of the spec as a '-' — three hundred
+      // lines of noise around the four that change.
+      const ops = extractOps(text);
+      if (ops.length > 0) {
+        const current = read(targetPath);
+        const after = applyOps(current, ops);
+        if (after.errors.length > 0) {
+          for (const e of after.errors) console.error(c.red("error:") + ` ${rel}: ${e}`);
+          errors += 1;
+          continue;
+        }
+        console.log(formatUnified(diffLines(current, after.text), {
+          aLabel: targetRel,
+          bLabel: `${targetRel} (after apply)`,
+        }));
+        continue;
+      }
       console.log(c.gray("note: the delta body is a fragment to merge — '-' lines are current"));
       console.log(c.gray("      spec content absent from the delta, not necessarily removals."));
       const out = formatUnified(diffLines(read(targetPath), body), {
@@ -850,6 +909,22 @@ function extractDeltaBody(text) {
 }
 
 
+// The smells `after` has that `before` does not, matched by rule, token and
+// the line's own text — line numbers shift when a delta inserts a line.
+function newSmells(before, after, projectRoot) {
+  const key = (/** @type {string} */ text, /** @type {{ line: number, rule: string, token: string }} */ sm) =>
+    `${sm.rule}|${sm.token.toLowerCase()}|${text.split("\n")[sm.line - 1] ?? ""}`;
+  const seen = new Map();
+  for (const sm of scanText(before, projectRoot)) seen.set(key(before, sm), (seen.get(key(before, sm)) ?? 0) + 1);
+  const out = [];
+  for (const sm of scanText(after, projectRoot)) {
+    const k = key(after, sm);
+    if ((seen.get(k) ?? 0) > 0) seen.set(k, seen.get(k) - 1);
+    else out.push(sm);
+  }
+  return out;
+}
+
 export const help = `
 Usage: doctrina change <subcommand> [args]
 
@@ -872,6 +947,7 @@ Subcommands:
                          its target + the archive gate preview + an advisory
                          list of accepted ADRs citing the touched capabilities.
                          Everything close would refuse, listed BEFORE it runs.
+                         --verbose also prints each delta as it would land.
   tick <id> [n... |--all]  List the unchecked boxes (tasks.md + proposal
                          ## Verification) with ordinals; tick the given ones,
                          or every one with --all. No args = list only.
@@ -883,7 +959,9 @@ Subcommands:
                          capability — created from the template when absent —
                          parsed by the grammar apply reads and dry-run against
                          the spec first: nothing is written unless the whole
-                         block applies. A second --bump replaces the first.
+                         block applies. --requirement, --criterion and --op
+                         repeat, one op each, in order; a second --bump
+                         replaces the first.
   card <id> [<n>]        Print task <n> (default: the next open one) as a
                          self-contained card for an executor: the task and the
                          lines indented under it (Files:, Requirement:, Verify:),

package/src/commands/clarify.js

@@ -5,112 +5,9 @@ import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
-import { detectLanguage } from "../lib/lexicon.js";
-import { loadConfig } from "../lib/config.js";
+import { scanFile } from "../lib/clarify-scan.js";
 import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 
-// Two lexicons, one linter (0.11.0 field review item 3: an English-only
-// clarify is permanently red on a PT-BR project — "some" is the verb *sumir*,
-// "TODO o pensamento" is the pronoun *todo* — which teaches people to ignore
-// the gate). The language comes from `.doctrina/config.json` ("language":
-// "pt-BR" | "en"), else a per-file stopword heuristic. Portuguese mode swaps
-// the ambiguous EN tokens for a PT lexicon; TODO only counts with a colon
-// ("TODO:") since bare TODO is the pronoun.
-const RULES_EN = [
-  {
-    // "may" is intentionally NOT in this list: EARS Optional grammar
-    // uses "the system may ..." legitimately, and a clarify pass that
-    // flags every EARS Optional is unusable on Doctrina-style specs.
-    // The remaining weasel terms are unambiguous.
-    name: "weasel",
-    re: /\b(might|could|should\s+probably|perhaps|maybe|approximately|roughly)\b/gi,
-    hint: "state explicitly with a definite verb",
-  },
-  {
-    name: "vague",
-    // Two exclusions, both structural rather than a vocabulary loosening.
-    // The lookahead was already here: `many 5` quantifies. The lookbehind is
-    // change 0079: `how many` is INTERROGATIVE, and a requirement that says
-    // "shall report how many contracts declared no rows" names exactly the
-    // number the command must print — the opposite of vague. Five of this
-    // repository's seventeen smells were that phrase, and the noise is what
-    // hid the one real finding among them ("name some of them", which said
-    // nothing about how many). A gate that cries wolf teaches people to
-    // ignore it.
-    //
-    // The quality adjectives sit here for the same reason the quantifiers do:
-    // "robust" names no threshold, so it cannot be met or missed. They were
-    // in the Portuguese lexicon and nowhere in this one, so the SAME sentence
-    // translated came back with three smells in one language and none in the
-    // other — and this project keeps its own pages in both. A smell test that
-    // answers differently per language is not testing the writing.
-    re: /(?<!\bhow\s+)\b(many|few|some|several|adequate|robust|scalable)\b(?!\s+\d)/gi,
-    hint: "quantify (use a number or a precise scope)",
-  },
-  {
-    name: "placeholder",
-    re: /\b(TBD|TODO|FIXME|XXX|\?\?\?)\b/g,
-    hint: "resolve before applying",
-  },
-];
-
-// How much of the previous line a rule may look back into. Long enough for
-// a wrapped two-word phrase, short enough that the probe stays cheap.
-const LOOKBEHIND_TAIL = 40;
-
-const RULES_PT = [
-  {
-    name: "weasel",
-    re: /\b(talvez|possivelmente|provavelmente|aproximadamente|quem sabe|eventualmente)\b/gi,
-    hint: "afirme explicitamente, com um verbo definido",
-  },
-  {
-    // ASCII-folded variants included so "varios"/"vários" both match.
-    name: "vague",
-    re: /\b(muitos|muitas|poucos|poucas|v[aá]rios|v[aá]rias|alguns|algumas|adequado|adequada|robusto|robusta|escal[aá]vel)\b(?!\s+\d)/gi,
-    hint: "quantifique (um número ou um escopo preciso)",
-  },
-  {
-    // Bare TODO is the Portuguese pronoun; only TODO: is a marker here.
-    name: "placeholder",
-    re: /\b(TBD|FIXME|XXX|\?\?\?)\b|\bTODO:/g,
-    hint: "resolva antes de aplicar",
-  },
-];
-
-// Language for a file: the project-declared `.doctrina/config.json`
-// ("language": "pt-BR" / "pt" / "en") wins; otherwise a deterministic
-// stopword count over the file text decides. Never semantic (ADR 0005).
-
-function projectLanguage(projectRoot) {
-  // One configuration reader (lib/config.js, change 0047): the key still
-  // lives in .doctrina/config.json, but `doctor` can now show what it
-  // resolved to, which is what a pt-BR project sitting red needed.
-  return loadConfig(projectRoot).language;
-}
-
-// Which lexicon a document is written in — the shared detector (change
-// 0040), so `clarify` and any future consumer count the same grammar words.
-function detectLang(text) {
-  return detectLanguage(text);
-}
-
-function rulesFor(projectRoot, text, forcedLang = null) {
-  const lang = forcedLang ?? projectLanguage(projectRoot);
-  if (lang) return lang === "pt" ? RULES_PT : RULES_EN;
-  // Detected per file, the document is scanned with BOTH lexicons (change
-  // 0107). A bilingual spec — Portuguese purpose, English EARS, or the
-  // reverse — detected as one language hid every smell written in the
-  // other: `clarify --all` found nothing where `--lang pt` found two. The
-  // two vocabularies do not overlap, so a smell in either is a smell; the
-  // detected language only decides which hint text the reader gets first.
-  const detected = detectLang(text);
-  const [first, second] = detected === "pt" ? [RULES_PT, RULES_EN] : [RULES_EN, RULES_PT];
-  // The `placeholder` rule is language-neutral and lives in both lists:
-  // one copy, or TBD is reported twice.
-  return [...first, ...second.filter((r) => r.name !== "placeholder")];
-}
-
 // --lang pt|en wins over the project config and the per-file heuristic
 // (operator review 2026-07-19 §4.8: on a PT-BR project with no config.json,
 // a file whose stopword count tips English gets the EN lexicon and "some" —
@@ -221,106 +118,6 @@ function clarifyAll(projectRoot, lang = null) {
   return 1;
 }
 
-function scanFile(fullPath, projectRoot = process.cwd(), lang = null) {
-  const text = read(fullPath);
-  const skippedRanges = collectSkippedRanges(text);
-  const rules = rulesFor(projectRoot, text, lang);
-  const smells = [];
-
-  // Per-line rules: regex pass with skip-range filter. A line carrying the
-  // inline suppression marker `<!-- clarify:ok -->` is deliberately accepted
-  // by the author — skip it entirely (the escape hatch for a false positive
-  // the lexicon cannot know about; "block, never imprison").
-  const lines = text.split("\n");
-  let cursor = 0;
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const lineStart = cursor;
-    const lineEnd = cursor + line.length;
-    if (line.includes("clarify:ok")) {
-      cursor = lineEnd + 1;
-      continue;
-    }
-    // A rule reads the previous line as CONTEXT, never as content: a match
-    // is only reported when it starts inside this line. Prose wraps, and
-    // "report per spec how / many criteria..." split the interrogative
-    // across a line break — which a line-at-a-time scanner cannot see, so
-    // the phrase came back as a smell on one line of the same document and
-    // not on the next (change 0079). The prefix is trimmed to the tail of
-    // the previous line: enough for a lookbehind, cheap on every line.
-    const prev = i > 0 ? lines[i - 1].slice(-LOOKBEHIND_TAIL) : "";
-    const probe = prev === "" ? line : `${prev}\n${line}`;
-    const offset = probe.length - line.length;
-    for (const rule of rules) {
-      rule.re.lastIndex = 0;
-      let m;
-      while ((m = rule.re.exec(probe))) {
-        if (m.index < offset) continue;   // the match belongs to the previous line
-        const absoluteStart = lineStart + m.index - offset;
-        if (isInSkippedRange(absoluteStart, skippedRanges)) continue;
-        smells.push({
-          line: i + 1,
-          rule: rule.name,
-          token: m[0],
-          hint: rule.hint,
-        });
-      }
-    }
-    cursor = lineEnd + 1; // +1 for the newline
-  }
-
-  // Section rule: empty Acceptance criteria.
-  if (hasEmptyAcceptanceCriteria(text)) {
-    smells.push({
-      line: findAcceptanceLine(text),
-      rule: "empty-section",
-      token: "Acceptance criteria",
-      hint: "fill in observable, verifiable signals",
-    });
-  }
-
-  smells.sort((a, b) => a.line - b.line);
-  return smells;
-}
-
-// Build ranges to skip: fenced code blocks, HTML comments, inline backticks.
-function collectSkippedRanges(text) {
-  const ranges = [];
-  // Fenced code blocks (``` ... ```)
-  for (const m of text.matchAll(/```[\s\S]*?```/g)) ranges.push([m.index, m.index + m[0].length]);
-  // HTML comments (<!-- ... -->)
-  for (const m of text.matchAll(/<!--[\s\S]*?-->/g)) ranges.push([m.index, m.index + m[0].length]);
-  // Inline backtick spans (`...`)
-  for (const m of text.matchAll(/`[^`\n]+`/g)) ranges.push([m.index, m.index + m[0].length]);
-  return ranges;
-}
-
-function isInSkippedRange(offset, ranges) {
-  for (const [a, b] of ranges) if (offset >= a && offset < b) return true;
-  return false;
-}
-
-function hasEmptyAcceptanceCriteria(text) {
-  const headingRe = /^##\s+Acceptance criteria\s*$/m;
-  const m = headingRe.exec(text);
-  if (!m) return false;
-  const after = text.slice(m.index + m[0].length);
-  // Find the body between this heading and the next heading of equal level.
-  const nextHeadingMatch = after.match(/^##\s+/m);
-  const body = nextHeadingMatch ? after.slice(0, nextHeadingMatch.index) : after;
-  // Strip HTML comments before checking emptiness.
-  const stripped = body.replace(/<!--[\s\S]*?-->/g, "").trim();
-  return stripped.length === 0;
-}
-
-function findAcceptanceLine(text) {
-  const lines = text.split("\n");
-  for (let i = 0; i < lines.length; i++) {
-    if (/^##\s+Acceptance criteria\s*$/.test(lines[i])) return i + 1;
-  }
-  return 1;
-}
-
 export const help = `
 Usage: doctrina clarify <path> [--lang pt|en]
        doctrina clarify --all [--lang pt|en]

package/src/commands/context.js

@@ -14,7 +14,9 @@ import { GIT_STATE, historyState, changedFiles } from "../lib/git.js";
 import { terms as queryTerms, relevance } from "../lib/lexicon.js";
 import { notADoctrinaProject, EXIT } from "../lib/exit-codes.js";
 import * as idx from "../lib/index-json.js";
-import { adrDigest, sliceSpec } from "../lib/context-slice.js";
+import { adrDigest, sliceSpec, withoutComments } from "../lib/context-slice.js";
+import { contextRouting, workspaceActions, workspaceFindings, workspaceHandoff, workspaceRootAt, workspaceSnapshot, workspaceStatus } from "../lib/workspace-view.js";
+import { cdThen, qarg } from "../lib/shell.js";
 
 // Materialise the AGENTS.md read order as a command: print the exact
 // context pack for a task, in the order an agent should read it. This is
@@ -85,6 +87,21 @@ export async function run(positional, cmdFlags) {
   const diffRef = flagString(cmdFlags, "diff");
   const query = flagString(cmdFlags, "for");
   const projectRoot = process.cwd();
+  // At a workspace root there is no one spec tree to read: the pack is per
+  // repository. Name which repositories the task is about, and the command
+  // that reads each one's pack (change 0230).
+  const wsRoot = workspaceRootAt(projectRoot);
+  if (wsRoot) {
+    const ranked = contextRouting(workspaceSnapshot(wsRoot), query ?? capability ?? "");
+    console.log(c.bold("The context pack is read inside a repository.") + c.gray(query ? ` Projects for "${query}":` : " Projects:"));
+    for (const r of ranked) {
+      const mark = r.state === "ready" ? "" : c.yellow(` (${r.state})`);
+      console.log(`  ${r.name.padEnd(16)} ${query ? c.gray(`${r.score} shared term${r.score === 1 ? "" : "s"}${r.shared.length ? ` (${r.shared.slice(0, 5).join(", ")})` : ""}`) : ""}${mark}`);
+      console.log(`    ${c.cyan(cdThen(r.path, `doctrina context ${capability ?? "<capability>"}${query ? ` --for ${qarg(query)}` : ""} --concat`))}`);
+    }
+    if (ranked.length === 0) console.log(c.gray("  none registered — `doctrina workspace add <path>`"));
+    return 0;
+  }
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
@@ -319,7 +336,17 @@ export async function run(positional, cmdFlags) {
     for (const ch of open) {
       if (ch.id === focusId) {
         // The change being worked on: every file, whole, in CORE.
-        for (const f of ch.files) pushFile(relPath(projectRoot, f), `open change: ${ch.id}`);
+        for (const f of ch.files) {
+          const item = pushFile(relPath(projectRoot, f), `open change: ${ch.id}`);
+          // Read, not written: the templates' authoring comments stay out
+          // unless --full (change 0228).
+          const bare = item && !full ? withoutComments(read(f)) : null;
+          if (item && bare !== null) {
+            item.slice = bare;
+            item.tokens = estimateTokens(bare);
+            item.note = `${item.note} — comments left out`;
+          }
+        }
         continue;
       }
       // A PARKED change is ONE entry in a queue, not three documents. It
@@ -749,6 +776,10 @@ active spec), open changes, accepted ADRs. Skills are
 listed name + description + when-trigger only — they are on-demand by
 design. The change archive is excluded.
 
+At a workspace root, where no one spec tree exists, it ranks the
+registered projects against --for and prints the command that reads
+each one's pack inside its repository.
+
 The pack is LEAN by default: AGENTS.md is not repeated (your agent
 loads it every turn), an accepted ADR is a digest — its title and the
 opening of its Decision; \`doctrina show NNNN\` reads the rest — and

package/src/commands/contract.js

@@ -278,6 +278,7 @@ the port map, the environment contract, and API/WS/event interfaces.
 
 Subcommands:
   new <name>          Scaffold .doctrina/contracts/<name>.md and index it
+                      (--force overwrites an existing contract)
   list                One line per contract: id, status, last updated
   check [<name>]      Verify the mechanically checkable parts.