doctrina-cli 0.20.0 → 0.22.0

package/src/commands/upgrade.js

@@ -5,11 +5,15 @@ import { exists } from "../lib/fs-ops.js";
 import * as idx from "../lib/index-json.js";
 import { deriveIndex, indexesMatch } from "../lib/scan.js";
 import { cliVersion } from "../lib/version.js";
-import { flagBool } from "../lib/args.js";
+import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { today } from "../lib/dates.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
+import { applyPreset, describePreset, planPreset, presetPending, readPreset } from "../lib/preset.js";
 import { planSkillExport, applySkillExport } from "../lib/skill-export.js";
+import { applyAdapterMigration, planAdapterMigration } from "../lib/adapters.js";
+import { projectName } from "../lib/project.js";
+import { relinkShadow, shadowRootOf } from "../lib/workspace.js";
 import { collectFindings } from "../lib/templates-model.js";
 import * as templates from "./templates.js";
 import * as validate from "./validate.js";
@@ -27,7 +31,7 @@ import * as validate from "./validate.js";
 // 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", "write"], string: [] };
+export const flags = { boolean: ["json", "write"], string: ["preset"] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -55,6 +59,27 @@ export async function run(_positional, flags) {
 
   let pending = 0;
 
+  // 0. The organisation's preset, when one is named (change 0253): laid
+  //    over the project before the scaffold is measured, so the steps below
+  //    check the project as it will be.
+  const presetDir = flagString(flags, "preset");
+  if (flags.has("preset")) {
+    let preset;
+    try {
+      if (!presetDir) throw new Error("--preset needs the preset's folder");
+      preset = readPreset(presetDir);
+    } catch (err) {
+      console.error(c.red("error:") + ` ${/** @type {Error} */ (err).message}`);
+      return EXIT.USAGE;
+    }
+    const plan = planPreset(projectRoot, preset);
+    if (writeMode) applyPreset(projectRoot, preset, plan);
+    else if (presetPending(plan) > 0) pending += 1;
+    console.log(c.gray("──── preset"));
+    for (const line of describePreset(preset, plan, writeMode)) console.log(line);
+    console.log("");
+  }
+
   // 2. Additive template updates (missing recommended sections in AGENTS.md /
   //    product.md, missing index.json fields). Reuses `templates update`
   //    verbatim: preview without --write, apply with it.
@@ -78,6 +103,8 @@ export async function run(_positional, flags) {
   // The skill exports (change 0212) follow the index: regenerated by the
   // write, reported by the preview.
   const exportPlan = planSkillExport(projectRoot);
+  // Adapter files that moved (change 0238): Cursor's slash commands became skills.
+  const movePlan = planAdapterMigration(projectRoot, { PROJECT_NAME: projectName(projectRoot), PROJECT_DESCRIPTION: "", DATE: today() }, shadowRootOf(projectRoot) ?? projectRoot);
   const exportChanges = exportPlan.writes.length + exportPlan.removes.length;
 
   // 3. Index: rebuild from the tree, which also migrates the framework stamp.
@@ -96,6 +123,29 @@ export async function run(_positional, flags) {
         pending += 1;
       }
     }
+    const moves = movePlan.writes.length + movePlan.removes.length;
+    // What the installed adapters gained since this project added them.
+    if (movePlan.added.length > 0) {
+      const names = movePlan.added.map((a) => a.relativePath).join(", ");
+      if (writeMode) console.log(c.green("added  ") + ` ${movePlan.added.length} adapter file${movePlan.added.length === 1 ? "" : "s"} this CLI ships now: ${names}`);
+      else {
+        console.log(c.yellow("would  ") + `add ${movePlan.added.length} adapter file${movePlan.added.length === 1 ? "" : "s"} this CLI ships now: ${names}`);
+        pending += 1;
+      }
+    }
+    if (moves > 0 || (writeMode && movePlan.added.length > 0)) {
+      if (writeMode && moves === 0) applyAdapterMigration(shadowRootOf(projectRoot) ?? projectRoot, movePlan);
+      else if (writeMode) {
+        const gone = applyAdapterMigration(shadowRootOf(projectRoot) ?? projectRoot, movePlan);
+        relinkShadow(projectRoot, gone);
+        console.log(c.green("moved  ") + ` ${movePlan.writes.length} adapter file${movePlan.writes.length === 1 ? "" : "s"} to the skills the agent reads now` +
+          (movePlan.removes.length ? `, ${movePlan.removes.length} retired cop${movePlan.removes.length === 1 ? "y" : "ies"} removed` : ""));
+      } else {
+        console.log(c.yellow("would  ") + `move ${movePlan.removes.length || movePlan.writes.length} Cursor command${(movePlan.removes.length || movePlan.writes.length) === 1 ? "" : "s"} to .cursor/skills/ (Cursor reads skills now)`);
+        pending += 1;
+      }
+    }
+    for (const rel of movePlan.kept) console.log(c.yellow("kept   ") + ` ${rel} — edited since install; its skill replaces it, so move your edits and remove it`);
     if (!drifted && !staleStamp) {
       console.log(c.green("ok") + " index.json matches the tree and the stamp is current");
     } else if (writeMode) {
@@ -155,7 +205,7 @@ export async function run(_positional, flags) {
 }
 
 export const help = `
-Usage: doctrina upgrade [--write]
+Usage: doctrina upgrade [--write] [--preset <dir>]
 
 Bring an existing project up to the installed CLI after an npm update.
 The project keeps the scaffold of the version that init-ed it; this is
@@ -174,6 +224,14 @@ the one command that closes the gap, orchestrating the existing pieces:
   3. validate (--fix)   — surface anything the upgrade cannot fix
                           (hand-authored drift, new validate checks)
 
+--preset <dir> first lays an organisation's preset over the project: a
+folder with preset.json ({ "name", "description", "config" }) and optional
+templates/, decisions/, skills/ and verify.json. Additive — a file the
+project has is kept, a config key it declares is kept, an ADR number it
+uses is not overwritten — and the plan names each one. A preset's
+verify.json is copied only when the project has none, and the commands it
+would run are printed.
+
 Preview by default (exits 1 when steps are pending or a manual repair is
 left); --write applies. The preview is what \`templates check\` reported
 and --write what \`templates update --write\` did — both deprecated.

package/src/commands/validate.js

@@ -7,6 +7,7 @@ import { c } from "../lib/colors.js";
 import { emitJson } from "../lib/json-out.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { collectValidation } from "../lib/validation-model.js";
+import { contextRouting, workspaceActions, workspaceFindings, workspaceHandoff, workspaceRootAt, workspaceSnapshot, workspaceStatus } from "../lib/workspace-view.js";
 
 // The structural gate. The checks themselves live in lib/validation-model.js
 // so a driver can ASK for them instead of spawning this binary and parsing
@@ -27,6 +28,19 @@ export async function run(_positional, flags) {
   // Outside a Doctrina project this is a PRECONDITION, not a pile of
   // gate failures about missing files: the remedy is `doctrina init`,
   // not editing artifacts that do not exist yet (C7).
+  // At a workspace root: the workspace's own integrity — registry, shadow
+  // links, deliveries (change 0230). Each project validates inside itself.
+  const wsRoot = workspaceRootAt(projectRoot);
+  if (wsRoot) {
+    const { errors, warnings } = workspaceFindings(workspaceSnapshot(wsRoot));
+    for (const e of errors) console.log(c.red("error: ") + e);
+    for (const w of warnings) console.log(c.yellow("warn:  ") + w);
+    console.log("");
+    console.log(errors.length === 0
+      ? c.green("ok") + ` the workspace is consistent${warnings.length ? ` (${warnings.length} warning${warnings.length === 1 ? "" : "s"})` : ""} — each project validates inside itself: \`cd <path> && doctrina validate\``
+      : c.red("fail") + ` ${errors.length} workspace error${errors.length === 1 ? "" : "s"}`);
+    return errors.length > 0 || (flagBool(flags, "strict", false) && warnings.length > 0) ? 1 : 0;
+  }
   if (!isDir(path.join(projectRoot, ".doctrina"))) throw notADoctrinaProject();
 
   const { errors, warnings, fixes } = collectValidation(projectRoot, {
@@ -82,6 +96,10 @@ Run schema, artifact-existence, and structural checks against the
 .doctrina/ tree in the current working directory. Exits 0 if no errors
 (warnings allowed), 1 otherwise. With --strict, a warning fails it too.
 
+At a workspace root it checks the workspace instead — registered
+projects and their dependencies, shadow links, deliveries — and leaves
+each project's validation to \`cd <path> && doctrina validate\`.
+
 Two structural checks worth naming:
 
   Pipeline    a spec's optional "### Pipeline" block declares ordered

package/src/commands/verify.js

@@ -5,6 +5,7 @@ import { readdirSync } from "node:fs";
 import { wantsJson } from "../lib/json-out.js";
 import { spawn, spawnSync } from "node:child_process";
 import { exists, isDir, isFile, read, write, relPath } from "../lib/fs-ops.js";
+import { inventory } from "../lib/code-inventory.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { today } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
@@ -38,6 +39,16 @@ const STARTER = {
   ],
 };
 
+const SEEDED_COMMENT =
+  "doctrina verify runs each check below, in order, through your shell. " +
+  "These were seeded from the project's own manifests by the code " +
+  "inventory — confirm each one runs what its name says, and remove or add " +
+  "checks until this file is the project's executable definition of 'the " +
+  "code actually works'. A non-zero exit fails the gate. A check may add an " +
+  "\"expect\" block — {\"fail_if_output_matches\": \"<regex>\"} and/or " +
+  "{\"require_output_matches\": \"<regex>\"} — so that a run which exits 0 " +
+  "having executed NOTHING fails the gate instead of passing it.";
+
 // 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).
@@ -69,9 +80,24 @@ export async function run(_positional, flags) {
       console.error(c.red("error:") + ` ${CONFIG_REL} already exists (pass --force to overwrite)`);
       return 1;
     }
-    write(configPath, JSON.stringify(STARTER, null, 2) + "\n", { force: true });
-    console.log(c.green("created") + ` ${CONFIG_REL}`);
-    console.log(c.gray("Edit the `checks` array with your real commands, then run `doctrina verify`."));
+    // Seeded from the code inventory when it found the project's own build
+    // and test commands (change 0228): the absorb playbook says "declare the
+    // build gate from the inventory's candidate commands", and the inventory
+    // lists them under that heading — while --init wrote `exit 1` anyway,
+    // leaving the agent to copy by hand what the CLI had just read. With no
+    // candidate the starter stays fail-closed: a gate nobody declared must
+    // not pass.
+    // A check that belongs to one unit of a monorepo runs there (`cwd`).
+    const seeded = inventory(projectRoot).checks.map((ch) => ({ name: ch.name, run: ch.command, ...(ch.cwd ? { cwd: ch.cwd } : {}) }));
+    const config = seeded.length > 0
+      ? { ...STARTER, $comment: SEEDED_COMMENT, checks: seeded }
+      : STARTER;
+    write(configPath, JSON.stringify(config, null, 2) + "\n", { force: true });
+    console.log(c.green("created") + ` ${CONFIG_REL}` +
+      (seeded.length > 0 ? c.gray(` — seeded from the code inventory: ${seeded.map((s) => s.cwd ? `${s.run} (in ${s.cwd}/)` : s.run).join(", ")}`) : ""));
+    console.log(c.gray(seeded.length > 0
+      ? "Confirm each check runs what its name says (add an \"expect\" block where a run could execute nothing), then run `doctrina verify`."
+      : "Edit the `checks` array with your real commands, then run `doctrina verify`."));
     return 0;
   }
 
@@ -223,8 +249,8 @@ export async function run(_positional, flags) {
         results.push({ name, ok: true, kind: "manual", signoff: "fresh" });
       } else if (verdict.state === "expired") {
         console.log(c.yellow(`○ ${name} — sign-off expired`) +
-          c.gray(` (signed ${so.date} at ${short(so.sha)}; changed since: ${verdict.changed.slice(0, 3).join(", ")}` +
-            `${verdict.changed.length > 3 ? `, +${verdict.changed.length - 3} more` : ""})`) + resign);
+          c.gray(` (signed ${so.date} at ${short(so.sha)}; changed since: ${(verdict.changed ?? []).slice(0, 3).join(", ")}` +
+            `${(verdict.changed ?? []).length > 3 ? `, +${(verdict.changed ?? []).length - 3} more` : ""})`) + resign);
         results.push({ name, ok: false, kind: "manual", pending: true, signoff: "expired" });
       } else if (verdict.state === "unverifiable") {
         console.log(c.yellow(`○ ${name} — sign-off cannot be verified`) +
@@ -294,7 +320,7 @@ export async function run(_positional, flags) {
       const verdict = judgeOutput(expectation, output);
       if (!verdict.ok) {
         ok = false;
-        expectationNote = verdict.reason;
+        expectationNote = verdict.reason ?? null;
       }
     }
 
@@ -488,7 +514,9 @@ copy accumulates for the match. An "expect" pattern that is not a valid
 regular expression fails at config time, not silently.
 
 Flags:
-  --init     Scaffold a starter ${CONFIG_REL} (refuses to overwrite without --force)
+  --init     Scaffold a starter ${CONFIG_REL} (refuses to overwrite without --force):
+             the build and test commands the code inventory finds in the
+             project's manifests, or a fail-closed example when it finds none
   --list     Print the configured checks without running them
   --clean    Don't run checks; lint the project's package.json files for
              reproducibility footguns (entry points in a build dir with no

package/src/commands/why.js

@@ -174,7 +174,7 @@ function whyAnchor(projectRoot, id, specsDir, known) {
   for (const capName of known.sort()) {
     const text = read(path.join(specsDir, capName, "spec.md"));
     const realizesRaw = specHeader(text, "Realizes");
-    const ids = realizesRaw ? (realizesRaw.match(/[A-Z]+\d+/g) ?? []) : [];
+    const ids = realizesRaw ? (realizesRaw.match(/[A-Z]+\d+/g) ?? /** @type {string[]} */ ([])) : /** @type {string[]} */ ([]);
     if (ids.includes(id)) realizing.push({ cap: capName, text });
   }
 

package/src/commands/work.js

@@ -1,24 +1,26 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { readdirSync } from "node:fs";
-import { exists, isDir, isFile, mkdirp, read, relPath, write } from "../lib/fs-ops.js";
+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";
 import { c } from "../lib/colors.js";
 import { assessBrief } from "../lib/clarity.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
 import { findWorkspace, projectAt, readWorkspace } from "../lib/workspace.js";
-import { readDelivery, resolveDeliveryId } from "../lib/delivery.js";
+import { readDelivery, resolveDeliveryId, sectionText } from "../lib/delivery.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
@@ -67,6 +69,7 @@ export async function run(positional, flags) {
   // workspace delivery. Checked BEFORE anything is scaffolded, so a typo or a
   // repository the delivery was never routed to opens nothing.
   let delivery = null;
+  let deliveryStory = "";
   if (flags.has("delivery")) {
     const resolved = resolveDeliveryFor(projectRoot, flagString(flags, "delivery"));
     if (resolved.error) {
@@ -75,13 +78,14 @@ export async function run(positional, flags) {
       return resolved.code;
     }
     delivery = resolved.id;
+    deliveryStory = resolved.story ?? "";
   }
 
   // --resume <id>: reprint the playbook for an existing open change rather than
   // open a new one (review G1 — `work "continue"` used to slug the word and
   // fabricate a junk `NNNN-continue` change the operator had to delete).
   if (flags.has("resume")) {
-    return resumeChange(projectRoot, flagString(flags, "resume"));
+    return resumeChange(projectRoot, flagString(flags, "resume"), delivery);
   }
 
   // --from-diff backfills from code already written (review F8): the
@@ -172,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)`);
@@ -192,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
@@ -237,14 +266,17 @@ export async function run(positional, flags) {
     if (delivery) {
       updated = updated.replace(/^(-[ \t]+\*\*Lane:\*\*[^\r\n]*)/m, `$1\n- **Delivery:** ${delivery}`);
     }
-    if (updated !== txt) write(proposalPath, updated, { force: true });
+    if (updated !== txt) write(proposalPath, withEol(updated, eolOf(txt)), { force: true });
   }
 
   // Capability hint: term overlap for a prompt, changed-file overlap for a diff
   // (review F10 — rank by what the working tree touched, not just prompt words).
   const allChanged = fromDiff ? files : changedFiles(projectRoot).files;
   const diffMatches = pinned ? [] : rankCapabilitiesByDiff(projectRoot, allChanged);
-  const promptMatches = pinned || fromDiff ? [] : rankCapabilities(projectRoot, effPrompt);
+  // A delivery's change is ranked by its story too (second audit, change
+  // 0233): the title of a tracker item rarely names the capability — "lock
+  // the account after 3 wrong passwords" — while its story says "login".
+  const promptMatches = pinned || fromDiff ? [] : rankCapabilities(projectRoot, deliveryStory ? `${effPrompt}\n${deliveryStory}` : effPrompt);
   const matches = pinned ? [] : (fromDiff ? diffMatches : promptMatches);
   const capability = pinned ?? matches[0]?.id ?? null;
   const clarity = assessBrief(effPrompt, { kind: "prompt" });
@@ -323,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"));
@@ -399,7 +431,7 @@ function resolveDeliveryFor(projectRoot, ref) {
       code: EXIT.PRECONDITION,
     };
   }
-  return { id };
+  return { id, story: sectionText(d.text, "Story") ?? "" };
 }
 
 function writeLane(projectRoot, id, verdict, opts) {
@@ -408,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 });
@@ -417,29 +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}-/, ""));
-    }
-  }
-  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) {
@@ -481,7 +490,7 @@ function printResumeSuggestion(open) {
 
 // Reprint the work playbook for an already-open change, ranking capabilities
 // from its recorded title (the original prompt). Creates nothing.
-function resumeChange(projectRoot, resumeId) {
+function resumeChange(projectRoot, resumeId, delivery = null) {
   const open = openChanges(projectRoot);
   if (!resumeId || resumeId === true) {
     console.error(c.red("error:") + " --resume needs a change id");
@@ -496,6 +505,25 @@ function resumeChange(projectRoot, resumeId) {
     if (open.length) console.error(c.gray("open: ") + open.map((ch) => ch.id).join(", "));
     return 1;
   }
+  // --resume <id> --delivery <id> (change 0226): a change opened before its
+  // delivery existed — or without the flag — joins it, so the delivery's
+  // status and check see it. A change already in another delivery is not
+  // moved silently.
+  if (delivery) {
+    const proposalPath = path.join(projectRoot, ".doctrina", "changes", resumeId, "proposal.md");
+    const text = isFile(proposalPath) ? read(proposalPath) : "";
+    const current = (listHeader(text, "Delivery") ?? "").trim();
+    if (current && current !== delivery) {
+      console.error(c.red("error:") + ` ${resumeId} already belongs to delivery ${current}`);
+      return EXIT.PRECONDITION;
+    }
+    if (!current) {
+      const stamped = text.replace(/^(-[ \t]+\*\*Lane:\*\*[^\r\n]*)/m, `$1\n- **Delivery:** ${delivery}`);
+      const updated = stamped !== text ? stamped : text.replace(/^(-[ \t]+\*\*Status:\*\*[^\r\n]*)/m, `$1\n- **Delivery:** ${delivery}`);
+      write(proposalPath, withEol(updated, eolOf(text)), { force: true });
+      console.log(c.green("joined") + ` ${resumeId} to delivery ${delivery}`);
+    }
+  }
   const prompt = entry?.title ?? resumeId;
   const matches = rankCapabilities(projectRoot, prompt);
   const capability = matches[0]?.id ?? null;
@@ -560,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,
@@ -610,7 +638,9 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
 // The prompt as a `context --for` argument: one line, no double quotes, short
 // enough to read — the slicer only needs its content words.
 export function forQuery(prompt) {
-  const flat = String(prompt ?? "").replace(/["`]/g, "").replace(/\s+/g, " ").trim();
+  // `$` and `\\` too (change 0235): between the double quotes the playbook
+  // prints, `$(…)` in a prompt still ran.
+  const flat = String(prompt ?? "").replace(/["`$\\]/g, "").replace(/\s+/g, " ").trim();
   return flat.length > 80 ? flat.slice(0, 80).replace(/\s+\S*$/, "") : flat;
 }
 
@@ -667,6 +697,8 @@ Options:
                        (backlog entry; reprint later with --resume <id>)
   --id <id>            Override the derived change id
   --resume <id>        Reprint the playbook for an open change; create nothing
+  --delivery <id>      Stamp the change with the workspace delivery it is part
+                       of (ADR 0030); with --resume, join an open change to it
   --from-diff          Backfill: scaffold from the working-tree changes (no
                        prompt needed) and print a code-first playbook (F8)
   --consolidate <cap>  Open a change that consolidates <cap>'s spec — merge
@@ -685,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).