doctrina-cli 0.15.0 → 0.15.1

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.15.0 — current release. Zero runtime dependencies
+**Status:** v0.15.1 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install

package/package.json

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

package/src/commands/analyze.js

@@ -146,7 +146,7 @@ export function collectAnalysis(projectRoot, changeDir) {
         // untouched `spec new` scaffold is the canonical flow (spec new →
         // ADDED delta), so it passes as a replacement; only real content fails.
         if (exists(targetSpec) && !isUntouchedScaffold(read(targetSpec), cap)) {
-          results.push(fail(`  ${cap} (ADDED) but target ${targetRel} has real content — use MODIFIED or remove it first`));
+          results.push(fail(`  ${cap} (ADDED) but target ${targetRel} has real content — use MODIFIED or remove it first`, "pre-apply"));
         } else if (exists(targetSpec)) {
           results.push(pass(`  ${cap} (ADDED) → ${targetRel} (replaces the untouched scaffold)`));
         } else {
@@ -154,13 +154,13 @@ export function collectAnalysis(projectRoot, changeDir) {
         }
       } else if (op === "MODIFIED") {
         if (!exists(targetSpec)) {
-          results.push(fail(`  ${cap} (MODIFIED) but target ${targetRel} does not exist`));
+          results.push(fail(`  ${cap} (MODIFIED) but target ${targetRel} does not exist`, "pre-apply"));
         } else {
           results.push(pass(`  ${cap} (MODIFIED) → ${targetRel}`));
         }
       } else {
         if (!exists(targetSpec)) {
-          results.push(fail(`  ${cap} (REMOVED) but target ${targetRel} does not exist`));
+          results.push(fail(`  ${cap} (REMOVED) but target ${targetRel} does not exist`, "pre-apply"));
         } else {
           results.push(pass(`  ${cap} (REMOVED) → ${targetRel}`));
         }
@@ -229,8 +229,21 @@ function escapeRe(s) {
 function pass(msg) {
   return { kind: "pass", line: c.green("✓ ") + msg };
 }
-function fail(msg) {
-  return { kind: "fail", line: c.red("✗ ") + msg };
+// `scope` says WHEN a failure is a real answer.
+//
+// Most of these questions are true at every point in a change's life: a
+// proposal with an unwritten `## What` is hollow before an apply and just as
+// hollow after one. A few are only meaningful BEFORE the apply — "an ADDED
+// delta's target must not already hold real content" is proof of a problem
+// beforehand and proof the apply WORKED afterwards.
+//
+// The gate map used to exclude the whole structure gate from `archive` to
+// dodge that handful, which also dropped the hollow-proposal check — the
+// exact defect this repository's own history records as having "shipped six
+// hollow proposals past every gate". Tagging the pre-apply ones lets
+// `archive` keep the rest.
+function fail(msg, scope = "always") {
+  return { kind: "fail", scope, line: c.red("✗ ") + msg };
 }
 function info(msg) {
   return { kind: "info", line: c.gray("- ") + msg };

package/src/commands/doctor.js

@@ -146,10 +146,10 @@ export async function run(_positional, _flags) {
       row("fail", "runtime", `${errs.length} declaration${errs.length === 1 ? "" : "s"} do not hold`, "doctrina triage   (each finding names its own fix)");
       for (const e of errs.slice(0, 3)) console.log(`        ${" ".repeat(16)} ${c.red("·")} ${e.code} ${e.message}`);
     } else if (warns > 0) {
-      row("warn", "runtime", `${runtime.declared} declared rows hold; ${warns} advisory finding${warns === 1 ? "" : "s"}`, "doctrina triage");
+      row("warn", "runtime", `${runtime.declared} declared row${runtime.declared === 1 ? " holds" : "s hold"}; ${warns} advisory finding${warns === 1 ? "" : "s"}`, "doctrina triage");
       warningsTotal += 1;
     } else {
-      row("ok", "runtime", `${runtime.declared} declared row${runtime.declared === 1 ? "" : "s"} hold`);
+      row("ok", "runtime", `${runtime.declared} declared row${runtime.declared === 1 ? " holds" : "s hold"}`);
     }
   }
 

package/src/commands/triage.js

@@ -60,6 +60,16 @@ const CHORE_SIGNALS = [
 const PRODUCT_SIGNALS = [
   [3, /\b(add|introduce|support|allow|enable|implement|build)\b/i],
   [3, /\b(should|shall|must|requirement|acceptance|criteri)\b/i],
+  // AUTHORING VERBS. Both lanes above match domain NOUNS, which turned out
+  // to misread work ON the machinery as an incident IN it: "declare the
+  // release workflow wiring in a contract" scored RUNTIME on "workflow" and
+  // "wiring", and "so an intentional rename stops warning" scored CHORE on
+  // "rename" — a noun, not the act. Neither prompt was a diagnosis; both
+  // were someone sitting down to write an artifact.
+  //
+  // These are the verbs of authoring. A prompt whose verb is "declare" or
+  // "document" is describing work on the tree, whatever nouns surround it.
+  [3, /\b(declare|declaring|document|documenting|record|recording|specify|specifying|define|defining)\b/i],
   [2, /\b(new (feature|capability|command|endpoint|screen|flow))\b/i],
   [2, /\b(users? (can|should|want)|so that|in order to)\b/i],
   [1, /\b(change|behaviour|behavior|spec)\b/i],
@@ -202,7 +212,7 @@ function renderRuntime(runtime, envFindings, withEnv, hadLane) {
 
   const all = [...runtime.findings, ...envFindings];
   if (all.length === 0) {
-    console.log(c.green("  ok") + `  ${runtime.declared} declared row${runtime.declared === 1 ? "" : "s"} across ${runtime.contracts} contract${runtime.contracts === 1 ? "" : "s"} hold` + (withEnv ? " (including local .env)" : ""));
+    console.log(c.green("  ok") + `  ${runtime.declared} declared row${runtime.declared === 1 ? " holds" : "s hold"} across ${runtime.contracts} contract${runtime.contracts === 1 ? "" : "s"}` + (withEnv ? " (including local .env)" : ""));
     console.log("");
     return;
   }

package/src/commands/verify.js

@@ -2,7 +2,7 @@
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { exists, isDir, isFile, read, write, relPath } from "../lib/fs-ops.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { today } from "../lib/dates.js";
@@ -198,24 +198,20 @@ export async function run(_positional, flags) {
     // monorepo target a sub-package, e.g. { run: "node --test", cwd:
     // "packages/api" } — the multi-service shape the contract artifact
     // also serves.
-    // A check that declares OUTPUT EXPECTATIONS must have its output read,
-    // so it runs piped and is echoed straight through — the operator still
-    // sees everything, just at the end of the check rather than streaming.
-    // Only checks that opt in pay that cost.
+    // A check that declares OUTPUT EXPECTATIONS must have its output READ,
+    // which is not the same as withholding it. The first cut ran such a
+    // check piped and echoed the whole buffer at the end — forty seconds of
+    // blank terminal on this project's own suite, and worse on anything
+    // slower. Reading and showing are independent: the tee streams every
+    // chunk as it arrives AND accumulates it for the match.
     const expectation = parseExpectation(ch);
-    const res = spawnSync(ch.run, {
-      cwd: ch.cwd ? path.resolve(projectRoot, ch.cwd) : projectRoot,
-      shell: true,
-      stdio: expectation ? "pipe" : "inherit",
-      encoding: expectation ? "utf8" : undefined,
-      // A suite's output can be large; the default 1MB cap would truncate
-      // the very line an expectation is looking for.
-      maxBuffer: expectation ? 64 * 1024 * 1024 : undefined,
-    });
-    if (expectation) {
-      if (res.stdout) process.stdout.write(res.stdout);
-      if (res.stderr) process.stderr.write(res.stderr);
-    }
+    const res = expectation
+      ? await runTee(ch.run, ch.cwd ? path.resolve(projectRoot, ch.cwd) : projectRoot)
+      : spawnSync(ch.run, {
+        cwd: ch.cwd ? path.resolve(projectRoot, ch.cwd) : projectRoot,
+        shell: true,
+        stdio: "inherit",
+      });
 
     let ok = !res.error && res.status === 0;
     /** @type {string | null} */
@@ -226,7 +222,9 @@ export async function run(_positional, flags) {
       // matched nothing prints "0 scenarios" and exits 0, and every gate
       // above this one calls that a pass. An expectation makes the run's
       // own output part of the verdict.
-      const output = `${res.stdout ?? ""}\n${res.stderr ?? ""}`;
+      // The tee already interleaves both streams in the order they arrived,
+      // which is the order a human read them in.
+      const output = res.output ?? `${res.stdout ?? ""}\n${res.stderr ?? ""}`;
       const verdict = judgeOutput(expectation, output);
       if (!verdict.ok) {
         ok = false;
@@ -266,6 +264,47 @@ export async function run(_positional, flags) {
   return 1;
 }
 
+// Run a command, streaming its output to the terminal AS IT ARRIVES while
+// accumulating a copy for an expectation to match against.
+//
+// `spawnSync` cannot do this: it either inherits the streams (visible,
+// unreadable) or pipes them (readable, invisible until it exits). The async
+// spawn gives both, at the cost of this function existing.
+//
+// Both streams accumulate into ONE buffer in arrival order, so a pattern
+// spanning them matches the same text the operator saw, and stderr is
+// echoed to stderr so redirection still behaves.
+//
+// @returns {Promise<{status: number|null, output: string, error?: Error}>}
+function runTee(command, cwd) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, { cwd, shell: true, stdio: ["inherit", "pipe", "pipe"] });
+    } catch (err) {
+      resolve({ status: null, output: "", error: /** @type {Error} */ (err) });
+      return;
+    }
+
+    let output = "";
+    const tee = (stream, sink) => {
+      if (!stream) return;
+      stream.setEncoding("utf8");
+      stream.on("data", (chunk) => {
+        output += chunk;
+        sink.write(chunk);
+      });
+    };
+    tee(child.stdout, process.stdout);
+    tee(child.stderr, process.stderr);
+
+    child.on("error", (err) => resolve({ status: null, output, error: err }));
+    // "close" rather than "exit": it fires once the streams are drained, so
+    // no trailing output is dropped from the match or the terminal.
+    child.on("close", (status) => resolve({ status, output }));
+  });
+}
+
 // An `expect` block, normalised and compiled, or null when the check does
 // not declare one. Runner-agnostic by construction: Doctrina supplies no
 // patterns of its own and knows nothing about what the output means — the
@@ -476,10 +515,10 @@ verdict:
 
 Doctrina supplies no patterns of its own and knows nothing about what the
 output means — the project declares the line that proves its run was real,
-so this works for any runner in any language. A check with an "expect"
-block runs piped (its output is echoed through when it finishes, rather
-than streaming); every other check still streams. An "expect" pattern that
-is not a valid regular expression fails at config time, not silently.
+so this works for any runner in any language. An expect-carrying check
+still streams: its output is teed to the terminal as it arrives while a
+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)

package/src/lib/commands.js

@@ -402,6 +402,12 @@ export const AGENT_CHANGELOG_END = "<!-- doctrina:changed:end -->";
 // introduced it. Only entries that alter what an agent should DO belong
 // here — a bug fix nobody's behaviour depends on does not.
 export const AGENT_CHANGELOG = {
+  // Each entry lists only ITS OWN delta. The series carries the rest
+  // forward (see agentChangelogEntries), so a patch never has to restate
+  // the minor that introduced the commands, and never silently erases it.
+  "0.15.1": [
+    "Exporting a variable under a name that is not its source's is routine — declare it in the Wiring row's Origin cell as `<origin>:<source>` (e.g. `secrets:NPM_TOKEN`) and RT02 stays silent until either side moves.",
+  ],
   "0.15.0": [
     "`doctrina triage \"<prompt>\"` — classify a request as PRODUCT / RUNTIME / CHORE BEFORE scaffolding. `work` now holds a runtime-shaped prompt with exit 3 and points here; `--force` opens the change anyway.",
     "`contract check` now holds the declared wiring to the implementation: a `vars`/`secrets` variable no workflow exports, a default an empty CI value never triggers, an unvalidated enum, a selector matching zero targets (RT01-RT05).",
@@ -420,9 +426,54 @@ export const AGENT_CHANGELOG = {
 
 // The block written into AGENTS.md for a given version. Empty string when
 // that version has no agent-visible changes.
+// How many bullets the block may carry. Not a style preference: AGENTS.md
+// is always-loaded context under a hard 150-line budget, and at the current
+// template size five bullets is exactly what fits. Raising this means
+// cutting elsewhere — see the `agents-md-lines` budget in the contract.
+export const AGENT_CHANGELOG_MAX_BULLETS = 5;
+
+/**
+ * The bullets an agent arriving at `version` needs, newest first.
+ *
+ * Keyed per version, but rendered per MINOR SERIES. The block REPLACES its
+ * predecessor in AGENTS.md rather than accumulating, so rendering only the
+ * current version's own entry meant every patch silently erased the minor
+ * that introduced the commands: an agent upgrading 0.14.0 -> 0.15.1 would
+ * read one bug fix and never learn `triage` exists. The alternative —
+ * making each patch author restate the whole minor by hand — worked once
+ * and does not scale, because the restating is invisible and the third
+ * patch quietly drops a line to fit the cap.
+ *
+ * So the series carries itself, newest first, and the cap truncates the
+ * OLDEST. A fact that must outlive its series does not belong here: it
+ * belongs in the surface block or the docs, which is the honest place for
+ * something permanent.
+ */
+export function agentChangelogEntries(version) {
+  const series = String(version).split(".").slice(0, 2).join(".");
+  const versions = Object.keys(AGENT_CHANGELOG)
+    .filter((v) => v.split(".").slice(0, 2).join(".") === series && compareVersions(v, version) <= 0)
+    .sort((a, b) => compareVersions(b, a));
+  const out = [];
+  for (const v of versions) out.push(...(AGENT_CHANGELOG[v] ?? []));
+  return out.slice(0, AGENT_CHANGELOG_MAX_BULLETS);
+}
+
+// Numeric semver comparison — "0.15.10" must sort above "0.15.9", which a
+// string compare gets wrong.
+function compareVersions(a, b) {
+  const pa = String(a).split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => Number.parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
 export function agentChangelogMarkdown(version) {
-  const entries = AGENT_CHANGELOG[version];
-  if (!entries || entries.length === 0) return "";
+  const entries = agentChangelogEntries(version);
+  if (entries.length === 0) return "";
   return [
     `## What changed in ${version}`,
     "",

package/src/lib/gates.js

@@ -34,6 +34,28 @@ export const GATES = {
     },
   },
 
+  // Integrity: the subset of the structural questions that are true at
+  // EVERY point in a change's life — the proposal says why and what, the
+  // tasks are real, the deltas parse. Everything `structure` asks except
+  // the handful that only mean something before an apply.
+  //
+  // This exists because excluding `structure` wholesale from `archive` (to
+  // dodge the post-apply false positive documented below) also excluded the
+  // hollow-proposal check, which has no such problem. A change could then be
+  // archived — and stamped "applied" — with `## What` still holding nothing
+  // but its scaffold comment, after `apply` had refused it for exactly that.
+  // Observed on change 0030 of this repository, one release after the
+  // history recorded six hollow proposals reaching the archive.
+  integrity: {
+    label: "integrity",
+    rerun: (id) => `doctrina analyze ${id}`,
+    blockers(projectRoot, changeDir) {
+      return collectAnalysis(projectRoot, changeDir)
+        .filter((r) => r.kind === "fail" && r.scope !== "pre-apply")
+        .map((r) => stripAnsi(r.line).replace(/^✗\s*/, "").trim());
+    },
+  },
+
   // Verification: the work is claimed complete. Every checkbox in
   // tasks.md (closing steps included) and in the proposal's
   // "## Verification" section.
@@ -72,9 +94,15 @@ export const GATES = {
 // content the delta just wrote, so re-asking at archive time reports a
 // conflict that is the proof the apply worked. A gate must be asked at the
 // point its question is meaningful.
+//
+// `archive` therefore requires INTEGRITY — that same structural question
+// set minus the pre-apply-only checks — rather than nothing structural at
+// all. Excluding the whole gate to dodge three checks also excluded the
+// hollow-proposal check, and a change refused by `apply` for an unwritten
+// `## What` could still be archived and stamped "applied".
 export const TRANSITIONS = {
   apply: { label: "change apply", gates: ["structure"] },
-  archive: { label: "change archive", gates: ["verification"] },
+  archive: { label: "change archive", gates: ["integrity", "verification"] },
 };
 
 // Evaluate a transition's gates. Returns { ok, blockers, gates } where

package/src/lib/runtime.js

@@ -38,6 +38,31 @@ import { isDir, isFile, read, relPath, walk } from "./fs-ops.js";
 /** Origins whose value CI can inject as an EMPTY STRING rather than unset. */
 const INJECTABLE_ORIGINS = new Set(["vars", "secrets"]);
 
+/**
+ * Split an Origin cell into its origin and the OPTIONAL source name it
+ * declares: `secrets` -> {origin: "secrets", source: null}, and
+ * `secrets:NPM_TOKEN` -> {origin: "secrets", source: "NPM_TOKEN"}.
+ *
+ * Exporting a variable under a name that is not the source's is routine and
+ * often unavoidable — npm reads its credential from `NODE_AUTH_TOKEN`, so a
+ * repository whose secret is `NPM_TOKEN` has no choice but to rename in the
+ * `env:` line. RT02 is right to flag that (rename the secret and the
+ * expression resolves to the empty string, so the publish fails on a blank
+ * credential with nothing pointing at the cause) and was wrong to make it
+ * unanswerable: its remedy said "record the intentional rename in the Wiring
+ * row" while the row had nowhere to put it. A permanent warning nobody can
+ * clear teaches people to ignore warnings.
+ */
+export function parseOrigin(cell) {
+  const raw = String(cell ?? "").trim();
+  const colon = raw.indexOf(":");
+  if (colon < 0) return { origin: raw.toLowerCase(), source: null };
+  return {
+    origin: raw.slice(0, colon).trim().toLowerCase(),
+    source: raw.slice(colon + 1).trim() || null,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Declaration parsing
 // ---------------------------------------------------------------------------
@@ -255,7 +280,10 @@ export function checkWiring(projectRoot, decl) {
   const cache = new Map();
 
   for (const row of decl.wiring) {
-    const origin = row.origin.toLowerCase();
+    const { origin, source } = parseOrigin(row.origin);
+    // The name the workflow is expected to read FROM: the declared source
+    // when the row gives one, otherwise the variable's own name.
+    const expectedSource = source ?? row.name;
     if (!INJECTABLE_ORIGINS.has(origin)) continue;
     if (!row.workflow) {
       findings.push({
@@ -303,7 +331,9 @@ export function checkWiring(projectRoot, decl) {
         code: "RT01",
         level: "error",
         message: `${row.name} is declared with origin "${origin}" but no env: block in ${row.workflow} exports it${where} — the value exists in CI and never reaches the process`,
-        remedy: `add "${row.name}: \${{ ${origin}.${row.name} }}" to the env: block of the ${row.job || "relevant"} job in ${row.workflow}`,
+        // Quote the DECLARED source, so the line this tells you to paste is
+        // the one that actually works when the names differ.
+        remedy: `add "${row.name}: \${{ ${origin}.${expectedSource} }}" to the env: block of the ${row.job || "relevant"} job in ${row.workflow}`,
         file: row.workflow,
       });
       continue;
@@ -320,12 +350,19 @@ export function checkWiring(projectRoot, decl) {
           remedy: `align the Origin column with ${row.workflow}:${e.line} (a value set as ${origin} is not visible as ${ref.origin})`,
           file: row.workflow,
         });
-      } else if (ref.name !== row.name && ref.origin === origin) {
+      } else if (ref.name !== expectedSource && ref.origin === origin) {
+        // Silent when the workflow reads exactly the source the row
+        // declares: the rename is documented, and documentation is the
+        // answer this warning was asking for.
         findings.push({
           code: "RT02",
           level: "warn",
-          message: `${row.workflow}:${e.line} exports ${row.name} from ${ref.origin}.${ref.name} — the names differ, so renaming one silently empties the other`,
-          remedy: `use \${{ ${origin}.${row.name} }}, or record the intentional rename in the Wiring row`,
+          message: source
+            ? `${row.workflow}:${e.line} exports ${row.name} from ${ref.origin}.${ref.name}, but the contract declares it comes from ${origin}.${source} — one of the two moved`
+            : `${row.workflow}:${e.line} exports ${row.name} from ${ref.origin}.${ref.name} — the names differ, so renaming one silently empties the other`,
+          remedy: source
+            ? `align them: either export \${{ ${origin}.${source} }}, or update the Origin cell to "${origin}:${ref.name}"`
+            : `use \${{ ${origin}.${row.name} }}, or declare the rename in the Origin cell as "${origin}:${ref.name}"`,
           file: row.workflow,
         });
       }
@@ -371,7 +408,11 @@ export function checkEmptySemantics(projectRoot, decl) {
   const cache = new Map();
 
   for (const row of decl.wiring) {
-    const origin = row.origin.toLowerCase();
+    // Through parseOrigin, so a row declaring its source (`secrets:NPM_TOKEN`)
+    // is still recognised as CI-injectable. Reading the cell raw here would
+    // make declaring a source silently switch this check off — the same
+    // class of defect being fixed, wearing a different hat.
+    const { origin } = parseOrigin(row.origin);
     if (!INJECTABLE_ORIGINS.has(origin) || !row.consumer) continue;
     const full = path.join(projectRoot, row.consumer);
     if (!isFile(full)) {

package/templates/contract.md.template

@@ -56,6 +56,13 @@ program, because no `env:` line ever exports it.
             vars and secrets are CI-injected, and CI injects the EMPTY
             STRING for one that is unset — not "absent". That is why a
             `getenv(NAME, default)` default silently never applies.
+
+            Exporting under a name that is not the source's is routine
+            (npm reads its credential from NODE_AUTH_TOKEN whatever your
+            secret is called). Declare it as `<origin>:<source>` — e.g.
+            `secrets:NPM_TOKEN` — and RT02 stays silent while the two
+            agree, and speaks the moment either side moves. A bare origin
+            keeps warning on any rename, which is the right default.
   Workflow  repo-relative path to the workflow/pipeline file.
   Job/Step  the job (or step) whose env: block must export it.
   Consumer  the file that reads it.