doctrina-cli 0.16.0 → 0.17.0

package/src/commands/status.js

@@ -2,13 +2,14 @@
 import path from "node:path";
 import process from "node:process";
 import { exists } from "../lib/fs-ops.js";
-import { flagBool, flagString } from "../lib/args.js";
+import { flagBool, flagString, parsePositiveInt } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { emitJson } from "../lib/json-out.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
-import { collectSnapshot, collectStatus } from "../lib/snapshot.js";
+import { collectSnapshot, collectStatus, collectReportWindow } from "../lib/snapshot.js";
 import { renderView, VIEWS } from "../lib/views.js";
-import { gitWindow, historyState, windowCutoff } from "../lib/git.js";
+import { draftAgentChangelog, renderDraft } from "../lib/agent-changelog.js";
+import { cliVersion } from "../lib/version.js";
 import { suggest } from "../lib/suggest.js";
 
 // One-glance project health (review 2026-06-27 passive-user feature #1): a
@@ -32,6 +33,9 @@ export const jsonNative = true;
 
 export const flags = { boolean: ["json"], string: ["view", "since"] };
 
+// The snapshot's views, plus the one draft that is not a view of it.
+const STATUS_VIEWS = [...VIEWS, "agent-changelog"];
+
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
@@ -39,10 +43,10 @@ export async function run(_positional, flags) {
   }
 
   const view = flagString(flags, "view") ?? "dashboard";
-  if (!VIEWS.includes(view)) {
+  if (!STATUS_VIEWS.includes(view)) {
     console.error(c.red("error:") + ` unknown view "${view}"`);
-    const guess = suggest(view, VIEWS);
-    console.error(c.gray("hint: ") + (guess ? `did you mean --view ${guess}?` : `available: ${VIEWS.join(", ")}`));
+    const guess = suggest(view, STATUS_VIEWS);
+    console.error(c.gray("hint: ") + (guess ? `did you mean --view ${guess}?` : `available: ${STATUS_VIEWS.join(", ")}`));
     return 2;
   }
 
@@ -53,18 +57,24 @@ export async function run(_positional, flags) {
     return 0;
   }
 
-  const options = {};
-  if (view === "report") {
-    const sinceRaw = flagString(flags, "since") ?? "7";
-    const days = Number.parseInt(sinceRaw, 10);
-    if (!Number.isFinite(days) || days <= 0) {
+  let options = {};
+  if (view === "report" || view === "agent-changelog") {
+    const sinceRaw = flagString(flags, "since");
+    const days = parsePositiveInt(sinceRaw ?? "7");
+    if (days === null) {
       console.error(c.red("error:") + ` --since expects a positive day count, got "${sinceRaw}"`);
       return 2;
     }
-    options.days = days;
-    options.cutoffIso = windowCutoff(days);
-    options.git = gitWindow(projectRoot, days);
-    options.gitState = historyState(projectRoot);
+    // A DRAFT of the block `upgrade --write` writes into AGENTS.md, proposed
+    // from what the archived changes said they touched. Not a view of the
+    // snapshot, so it renders here; authorship stays human (ADR 0005). With
+    // no --since the window is "since the last tag".
+    if (view === "agent-changelog") {
+      const draft = draftAgentChangelog(projectRoot, { days: sinceRaw === undefined ? null : days });
+      for (const line of renderDraft(draft, cliVersion())) console.log(line);
+      return 0;
+    }
+    options = collectReportWindow(projectRoot, days);
   }
 
   const snapshot = collectSnapshot(projectRoot);
@@ -85,13 +95,22 @@ Flags:
                     dashboard  the default one-glance health board
                     prime      the session primer (\`doctrina prime\`)
                     handoff    the Markdown resume note (\`doctrina handoff\`)
-                    report     the period digest (\`doctrina report\`)
-  --since <days>  With --view report: the window (default 7).
+                    report     the period digest: gates, archived changes,
+                               open work, and local git numbers
+                    rules      the standing rules (\`doctrina prime --rules\`)
+                    agent-changelog
+                               a DRAFT of the AGENTS.md "What changed" block:
+                               one bullet per archived change that touched a
+                               documented surface, newest first, at most five.
+                               It proposes; a person cuts and rewrites.
+  --since <days>  With --view report: the window (default 7). With
+                  --view agent-changelog: the window (default: since the
+                  last tag).
   --json          Emit the snapshot as JSON (stable shape for agents and CI).
 
-All four views read ONE collection of the tree, so they can never report
-different numbers; \`prime\`, \`handoff\` and \`report\` are the same views
-under their own names.
+The views read ONE collection of the tree, so they can never report
+different numbers; \`prime\` and \`handoff\` are the same views under their
+own names. \`doctrina report\` is deprecated: it is \`--view report\`.
 
 It is a fast summary, not the authoritative gate: run \`doctrina validate\`
 and \`doctrina verify\` for the full structural and build checks, and

package/src/commands/templates.js

@@ -19,6 +19,7 @@ import { collectFindings, agentsSectionCost, AGENTS_SECTIONS, PRODUCT_SECTIONS,
 // too (audit finding F7); this command renders and fixes them.
 export { collectFindings } from "../lib/templates-model.js";
 import { suggest } from "../lib/suggest.js";
+import { ensureDoctrinaProject } from "../lib/project.js";
 
 const SUBCOMMANDS = ["list", "check", "update"];
 
@@ -50,10 +51,7 @@ export async function run(positional, flags) {
 function updateTemplates(flags) {
   const writeMode = flagBool(flags, "write", false);
   const projectRoot = process.cwd();
-  if (!isDir(path.join(projectRoot, ".doctrina"))) {
-    console.error(c.red("error:") + " not a Doctrina project (no .doctrina/ in cwd)");
-    return 1;
-  }
+  ensureDoctrinaProject(projectRoot);
 
   const plan = [];
   // Updates this run declines to make, each with the reason and the number.
@@ -176,7 +174,7 @@ function updateTemplates(flags) {
           let updated = read(filePath);
           if (!updated.endsWith("\n")) updated += "\n";
           for (const h of missing) {
-            updated += `\n${h}\n\n<!-- added by doctrina templates update — fill in -->\n`;
+            updated += `\n${h}\n\n<!-- added by doctrina upgrade — fill in -->\n`;
           }
           write(filePath, updated, { force: true });
         },
@@ -287,11 +285,7 @@ function listTemplates() {
 
 function checkTemplates() {
   const projectRoot = process.cwd();
-  if (!isDir(path.join(projectRoot, ".doctrina"))) {
-    console.error(c.red("error:") + " not a Doctrina project (no .doctrina/ in cwd)");
-    console.error(c.gray("hint: ") + "run `doctrina init` first");
-    return 1;
-  }
+  ensureDoctrinaProject(projectRoot);
   const { findings, ok } = collectFindings(projectRoot);
 
   return report(findings, ok);

package/src/commands/upgrade.js

@@ -9,6 +9,7 @@ import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { today } from "../lib/dates.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { collectFindings } from "../lib/templates-model.js";
 import * as templates from "./templates.js";
 import * as validate from "./validate.js";
 
@@ -56,11 +57,23 @@ export async function run(_positional, flags) {
   // 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.
-  console.log(c.gray("──── 1/3 scaffold shape (templates update)"));
+  console.log(c.gray("──── 1/3 scaffold shape"));
   const tplFlags = writeMode ? new Map([["write", true]]) : new Map();
   const tplCode = await templates.run(["update"], tplFlags);
   if (tplCode !== 0 && !writeMode) pending += 1; // preview exits 1 when updates are pending
 
+  // What the additive update cannot fix — a drifted adapter, a broken
+  // playbook, an index schema it does not know — used to be visible only to
+  // `templates check`. Printed here, each with its own remedy, so the one
+  // command that brings a project up to date also says what is left for a
+  // person (change 0178: the check and the update became this step).
+  const manual = collectFindings(projectRoot).findings
+    .filter((f) => !/upgrade --write|index rebuild/.test(f.remedy ?? ""));
+  for (const f of manual) {
+    console.log(c.yellow("✗ ") + f.message);
+    console.log(c.gray("    fix: ") + (f.remedy ? c.cyan(f.remedy) : c.gray("manual repair — no command can fix this")));
+  }
+
   // 3. Index: rebuild from the tree, which also migrates the framework stamp.
   console.log("");
   console.log(c.gray("──── 2/3 index + framework stamp"));
@@ -101,14 +114,22 @@ export async function run(_positional, flags) {
   const vCode = await validate.run([], vFlags);
 
   console.log("");
+  if (manual.length > 0) {
+    console.log(c.yellow("manual") + ` ${manual.length} finding${manual.length === 1 ? "" : "s"} the upgrade cannot repair — see step 1`);
+  }
   if (!writeMode) {
-    if (pending > 0) {
+    if (pending > 0 || manual.length > 0) {
+      if (pending === 0) return 1;
       console.log(c.yellow("pending") + ` upgrade steps found — apply them: ${c.cyan("doctrina upgrade --write")}`);
       return 1;
     }
     console.log(c.green("ok") + " nothing to upgrade — the project matches the installed CLI");
     return vCode;
   }
+  if (vCode === 0 && manual.length > 0) {
+    console.log(c.yellow(`upgraded to ${running} with manual repairs left`) + " — each finding in step 1 names its fix.");
+    return 1;
+  }
   if (vCode === 0) {
     console.log(c.green(`✓ project upgraded to ${running}`) + c.gray(" — review any warnings above; new commands: `doctrina --help`."));
     console.log(c.gray("AGENTS.md's doctrina:surface block was regenerated from the installed catalog, so agents reading the hub now discover the current commands."));
@@ -125,16 +146,20 @@ 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
 the one command that closes the gap, orchestrating the existing pieces:
 
-  1. templates update   — regenerate the AGENTS.md doctrina:surface block
+  1. scaffold shape     — regenerate the AGENTS.md doctrina:surface block
                           from the installed command catalog (the block is
                           CLI-owned, ADR 0015 — this is how agents reading
-                          the hub discover commands added since init), and
+                          the hub discover commands added since init),
                           append missing recommended sections / index.json
-                          fields (additive-only outside the block)
+                          fields (additive-only outside the block), and
+                          list what no command can repair (a drifted
+                          adapter, a broken playbook), each with its fix
   2. index rebuild      — regenerate index.json from the tree and migrate
                           the framework_version stamp to the running CLI
   3. validate (--fix)   — surface anything the upgrade cannot fix
                           (hand-authored drift, new validate checks)
 
-Preview by default (exits 1 when steps are pending); --write applies.
+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

@@ -20,7 +20,7 @@ import { collectValidation } from "../lib/validation-model.js";
 // wrap it in the generic envelope.
 export const jsonNative = true;
 
-export const flags = { boolean: ["fix", "json", "runtime"], string: [] };
+export const flags = { boolean: ["fix", "json", "runtime", "strict"], string: [] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -34,10 +34,26 @@ export async function run(_positional, flags) {
     runtime: flagBool(flags, "runtime", false),
   });
 
+  // --strict makes a warning count against the exit code, matching what
+  // `--strict` already means on `coverage` and `trace`: fail on any gap.
+  //
+  // The default has to stay lenient — a warning is advice, and advice that
+  // blocks a commit stops being read. But that leniency left a gate that
+  // COULD NOT REPROVE: the CI step that validates the shipped examples runs
+  // this command, both examples had drifted to warnings, and the step passed
+  // green through every run. The EARS defect the retrofit example exists to
+  // teach against was reintroduced and sat there, twice, because nothing
+  // downstream of `validate` could say no.
+  //
+  // So the choice belongs to the caller. A human at a terminal wants the
+  // advice; a gate wants a verdict.
+  const strict = flagBool(flags, "strict", false);
+  const failed = errors.length > 0 || (strict && warnings.length > 0);
+
   // Output
   if (flagBool(flags, "json", false)) {
-    emitJson("validate", { errors, warnings });
-    return errors.length === 0 ? 0 : 1;
+    emitJson("validate", { errors, warnings, strict });
+    return failed ? 1 : 0;
   }
   // The repairs print first and in the order they were made: --fix changes
   // the tree, and what it changed must be visible before what it then found.
@@ -50,17 +66,21 @@ export async function run(_positional, flags) {
     console.log(c.green("ok") + " all validation checks passed");
   } else {
     const summary = `${errors.length} error${errors.length === 1 ? "" : "s"}, ${warnings.length} warning${warnings.length === 1 ? "" : "s"}`;
-    console.log((errors.length === 0 ? c.green("ok") : c.red("fail")) + " " + summary);
+    console.log((failed ? c.red("fail") : c.green("ok")) + " " + summary);
+    // Say WHY a run with no errors is failing, or the exit code reads as a bug.
+    if (strict && errors.length === 0 && warnings.length > 0) {
+      console.log(c.gray("       --strict: warnings count against the exit code"));
+    }
   }
-  return errors.length === 0 ? 0 : 1;
+  return failed ? 1 : 0;
 }
 
 export const help = `
-Usage: doctrina validate [--fix] [--runtime] [--json]
+Usage: doctrina validate [--fix] [--runtime] [--strict] [--json]
 
 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.
+(warnings allowed), 1 otherwise. With --strict, a warning fails it too.
 
 Two structural checks worth naming:
 
@@ -84,5 +104,9 @@ Flags:
               selectors checked against the workflows and code that are
               supposed to honour them (the same checks as \`contract check\`).
               Opt-in because it reads files outside .doctrina/.
-  --json      Emit { ok, errors, warnings } as JSON (stable shape for agents/CI).
+  --strict    Treat warnings as failures, the way \`coverage --strict\` and
+              \`trace --strict\` already do. The default stays lenient because
+              a warning is advice; a GATE wants a verdict, so anything that
+              must be able to reprove passes this.
+  --json      Emit { ok, errors, warnings, strict } as JSON (stable shape for agents/CI).
 `;

package/src/commands/work.js

@@ -15,7 +15,7 @@ import { printPlaybookTemplate } from "../lib/playbook.js";
 import { changedFiles } from "../lib/git.js";
 import { slugFromPrompt, fold, CONFIDENT_MARGIN } from "../lib/lexicon.js";
 import { rankCapabilities, rankCapabilitiesByDiff } from "../lib/work-model.js";
-import { isChangeId } from "../lib/project.js";
+import { isChangeId, refuseChangeRef } from "../lib/project.js";
 export { rankCapabilities, rankCapabilitiesByDiff } from "../lib/work-model.js";
 
 // `work` is the second half of the no-ceremony path (ADR 0005): a brief
@@ -29,7 +29,7 @@ export { rankCapabilities, rankCapabilitiesByDiff } from "../lib/work-model.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", "chore", "force", "from-diff", "no-spec", "quiet"], string: ["capability", "id", "resume", "title"] };
+export const flags = { boolean: ["json", "chore", "design", "force", "from-diff", "no-spec", "quiet"], string: ["capability", "id", "resume", "title"] };
 
 export async function run(positional, flags) {
   const prompt = positional.join(" ").trim();
@@ -387,6 +387,8 @@ function resumeChange(projectRoot, resumeId) {
     if (open.length) console.error(c.gray("open: ") + open.map((ch) => ch.id).join(", "));
     return 2;
   }
+  const refused = refuseChangeRef(resumeId);
+  if (refused !== null) return refused;
   const entry = open.find((ch) => ch.id === resumeId);
   if (!entry && !isDir(path.join(projectRoot, ".doctrina", "changes", resumeId))) {
     console.error(c.red("error:") + ` no open change "${resumeId}"`);
@@ -515,9 +517,10 @@ change id (NNNN-<slug>) from the prompt, opens the change folder,
 records the prompt under the proposal's "## Why", ranks existing specs
 by term overlap as a capability hint, flags a thin/under-specified prompt
 so you clarify before writing deltas (advisory), and prints the steps:
-context → spec delta → tasks → implement → analyze → apply → verify
-(verify + coverage) → archive → validate. No natural-language
-interpretation happens in the CLI.
+context, spec delta, tasks, implement, then \`doctrina change check <id>\`
+to preview the close and \`doctrina close <id>\` to finish, which runs the
+whole closing sequence in one pass. No natural-language interpretation
+happens in the CLI.
 
 The change's spec delta is scaffolded with **Operation:** prefilled
 whenever the CLI can name the capability: from --capability, or from the
@@ -542,6 +545,8 @@ Options:
                        prompt needed) and print a code-first playbook (F8)
   --chore, --no-spec   Open a spec-less chore change (infra/docs/build) with a
                        playbook that skips the spec-delta steps (F9)
+  --design             Also scaffold design.md, for a change with non-trivial
+                       choices (opt-in, as with \`change new --design\`)
   --force              Open a new change even when one is open, overwrite an
                        existing change folder, and proceed past the lane hold
                        below

package/src/index.js

@@ -5,7 +5,7 @@ import { parseArgs } from "./lib/args.js";
 import { c } from "./lib/colors.js";
 import { suggest } from "./lib/suggest.js";
 import { cliVersion } from "./lib/version.js";
-import { surfaceHelp, OPERATIONS, deprecationFor } from "./lib/commands.js";
+import { surfaceHelp, OPERATIONS, deprecationFor, removalFor } from "./lib/commands.js";
 import { GLOBAL_FLAGS } from "./lib/flag-catalog.js";
 import { EXIT, exitCodeHelp } from "./lib/exit-codes.js";
 import { recordUsage, operationOf } from "./lib/usage.js";
@@ -37,7 +37,6 @@ import * as close from "./commands/close.js";
 import * as review from "./commands/review.js";
 import * as watch from "./commands/watch.js";
 import * as why from "./commands/why.js";
-import * as constitution from "./commands/constitution.js";
 import * as prime from "./commands/prime.js";
 import * as handoff from "./commands/handoff.js";
 import * as show from "./commands/show.js";
@@ -54,15 +53,14 @@ const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
   templates, skill, index: indexCmd, next, metrics, context, search,
   intake, work, coverage, verify, contract, trace,
-  status, close, review, watch, why, constitution,
+  status, close, review, watch, why,
   prime, handoff, show, doctor, report, completion,
   intent, upgrade, adapter, triage, ci,
 };
 
 const TOP_HELP = `
-Usage: doctrina <command> [options]
+Usage: doctrina <command> [options]      (\`doctrina <command> --help\` for its flags)
 
-Commands:
 ${surfaceHelp()}
 
 Global flags:
@@ -112,6 +110,17 @@ async function main(argv) {
 
   const commandName = positional[0];
   const command = COMMANDS[commandName];
+  const removed = removalFor(positional);
+  if (removed) {
+    const name = removed === removalFor([commandName]) ? commandName : positional.slice(0, 2).join(" ");
+    console.error(c.red("error:") + ` \`doctrina ${name}\` was removed in ${removed.since}`);
+    console.error(c.gray("hint: ") + `use \`${removed.use}\` — it prints what the removed command printed`);
+    if (wantsJson(flags)) {
+      emitJson(operationName(positional), { stderr: [`error: \`doctrina ${name}\` was removed in ${removed.since}`, `hint: use \`${removed.use}\``] },
+        { ok: false, exitCode: EXIT.USAGE, args: positional.slice(1) });
+    }
+    return EXIT.USAGE;
+  }
   if (!command) {
     console.error(c.red("error:") + ` unknown command "${commandName}"`);
     const guess = suggest(commandName, Object.keys(COMMANDS));
@@ -265,5 +274,24 @@ main(process.argv.slice(2)).then((code) => {
     code,
     new Set(OPERATIONS.map((o) => o[0])),
   );
-  process.exit(code ?? 0);
+  // SET THE CODE; DO NOT CALL process.exit().
+  //
+  // When stdout is a PIPE — every `doctrina ... | less`, every agent reading
+  // this CLI, every `spawnSync` in the suite — Node may not have handed the
+  // bytes to the OS yet when this callback runs. `process.exit()` tears the
+  // process down immediately and whatever is still buffered is simply lost.
+  // Setting `exitCode` lets Node exit on its own once the work is done, and
+  // flushing stdout is part of that work.
+  //
+  // This is not theoretical. Four tests failed on macOS with Node 20.12 and
+  // on no other leg of the matrix, all of them `--concat` runs looking for
+  // content near the END of a long output. The decisive one printed exactly
+  // one section: `product.md` was on disk and in the pack listing, and the
+  // concat output stopped before reaching it. Pipe buffer sizes differ per
+  // platform, which is precisely why a truncation bug picks one and hides on
+  // the others.
+  //
+  // `--concat` even carries the comment "Keep the pack pipeable". Losing the
+  // tail of a pipe is the one way to break that promise.
+  process.exitCode = code ?? 0;
 });

package/src/lib/actions.js

@@ -155,6 +155,34 @@ export function computeActions(projectRoot, gates = {}) {
     }));
   }
 
+  // Index drift comes right after the intake (change 0193). It used to be
+  // surfaced LAST as "silent rot" — but `validate` reports it as an error,
+  // the close's index-drift step blocks on it, the fix is one runnable
+  // command, and the actions below read the very index that drifted. Ranked
+  // fifth, under advisory nudges, it told the agent to polish product.md
+  // before running the one command that unblocked everything.
+  try {
+    const current = idx.load(projectRoot);
+    if (!indexesMatch(deriveIndex(projectRoot, current), current)) {
+      actions.push(action({
+        id: "index-drift",
+        command: "index rebuild",
+        gate: "index",
+        runnable: true,
+        why: "index.json has drifted from the tree",
+      }));
+    }
+  } catch {
+    actions.push(action({
+      id: "index-unreadable",
+      command: "index rebuild",
+      gate: "index",
+      runnable: true,
+      why: "index.json is missing or unreadable",
+    }));
+  }
+
+
   // Open changes drive the loop: finish what is started before opening more.
   const changesDir = path.join(projectRoot, ".doctrina", "changes");
   if (isDir(changesDir)) {
@@ -200,12 +228,12 @@ export function computeActions(projectRoot, gates = {}) {
       if (deltas.length > 0) {
         actions.push(action({
           id: "change-apply-ready",
-          command: "analyze",
+          command: "change check",
           args: [id],
           gate: "structure",
           runnable: true,
           why: `tasks done, ${deltas.length} delta${deltas.length === 1 ? "" : "s"} ready`,
-          text: `doctrina analyze ${id}, then doctrina change apply ${id} — ` +
+          text: `doctrina change check ${id}, then doctrina close ${id} — ` +
             `tasks done, ${deltas.length} delta${deltas.length === 1 ? "" : "s"} ready`,
         }));
       } else {
@@ -377,28 +405,6 @@ export function computeActions(projectRoot, gates = {}) {
     }));
   }
 
-  // Index drift is silent rot; surface it last.
-  try {
-    const current = idx.load(projectRoot);
-    if (!indexesMatch(deriveIndex(projectRoot, current), current)) {
-      actions.push(action({
-        id: "index-drift",
-        command: "index rebuild",
-        gate: "index",
-        runnable: true,
-        why: "index.json has drifted from the tree",
-      }));
-    }
-  } catch {
-    actions.push(action({
-      id: "index-unreadable",
-      command: "index rebuild",
-      gate: "index",
-      runnable: true,
-      why: "index.json is missing or unreadable",
-    }));
-  }
-
   return actions;
 }
 

package/src/lib/args.js

@@ -74,9 +74,23 @@ export function parseArgs(argv, opts = {}) {
 function isNextTokenFlag(token) {
   if (token === undefined) return true;
   if (typeof token !== "string") return true;
+  // `--budget -5` is a value, not a flag named "5": no flag name starts with
+  // a digit, and reading it as one answered "unknown flag --5, did you mean
+  // --h?" instead of letting the command say the number is out of range.
+  if (/^-\d/.test(token)) return false;
   return token.startsWith("-");
 }
 
+// A count read off a flag: digits only, above zero, or null. `parseInt`
+// reads "7x" as 7 and "1.5" as 1, so a typo became a different request that
+// ran without a word.
+export function parsePositiveInt(raw) {
+  const s = String(raw ?? "").trim();
+  if (!/^\d+$/.test(s)) return null;
+  const n = Number(s);
+  return Number.isSafeInteger(n) && n > 0 ? n : null;
+}
+
 export function flagString(flags, name, fallback = undefined) {
   const v = flags.get(name);
   if (v === undefined || v === true) return fallback;

package/src/lib/change-ops.js

@@ -96,8 +96,10 @@ export function changeNew(args, flags) {
 
   console.log("");
   if (chore) {
+    // A chore is still a change: it closes through the one definition of
+    // done, not a hand-run apply and archive (change 0180).
     console.log(c.bold("Chore opened.") + " No spec deltas expected — implement, check the tasks, then " +
-      c.cyan(`doctrina change apply ${id}`) + " and " + c.cyan(`doctrina change archive ${id}`) + ".");
+      c.cyan(`doctrina close ${id}`) + ".");
   } else {
     console.log(c.bold("Change opened.") + " Add spec deltas under " +
       c.cyan(`.doctrina/changes/${id}/specs/<capability>/delta.md`));