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

package/package.json

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

package/src/commands/analyze.js

@@ -4,6 +4,7 @@ import process from "node:process";
 import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
 import { c } from "../lib/colors.js";
 import { isUntouchedScaffold } from "./change.js";
+import { collectBudgets } from "../lib/runtime.js";
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
@@ -167,9 +168,64 @@ export function collectAnalysis(projectRoot, changeDir) {
     }
   }
 
+  // BUDGET DISCIPLINE (change 0029). A declared ceiling is a contract, not
+  // a preference — and the tempting fix for "the output blew the limit" is
+  // to raise the limit. That buys headroom by truncating what mattered
+  // instead of sending less, and it is the discussion that comes back every
+  // quarter because nothing ever recorded that it had been settled. Raising
+  // an INPUT ceiling is a normal trade-off; raising an OUTPUT ceiling to
+  // resolve an overflow is the move this refuses.
+  for (const r of checkBudgetRaises(projectRoot, changeDir)) results.push(r);
+
+  return results;
+}
+
+// Compare the ceilings a change's proposal/deltas propose against the ones
+// the contracts declare today. Text-scanned: a change states a new value in
+// prose long before any code moves, which is exactly when it should be
+// argued about.
+function checkBudgetRaises(projectRoot, changeDir) {
+  const results = [];
+  let declared;
+  try {
+    declared = collectBudgets(projectRoot);
+  } catch {
+    return results;
+  }
+  if (declared.size === 0) return results;
+
+  const texts = [];
+  for (const f of walk(changeDir)) {
+    if (f.endsWith(".md")) texts.push({ rel: relPath(projectRoot, f), text: read(f) });
+  }
+
+  for (const [name, budget] of declared) {
+    if (budget.direction !== "output") continue;
+    for (const { rel, text } of texts) {
+      // "<limit> ... <number>" on one line: the shape a proposal uses when
+      // it restates a ceiling ("raise ai-summary to 2000").
+      const re = new RegExp(`${escapeRe(name)}[^\\n]{0,60}?(\\d{2,})`, "gi");
+      for (const m of text.matchAll(re)) {
+        const proposed = Number.parseInt(m[1], 10);
+        if (!Number.isFinite(proposed) || proposed <= budget.value) continue;
+        results.push(fail(
+          `${rel} raises the OUTPUT ceiling "${name}" from ${budget.value} to ${proposed} ` +
+          `(declared in ${budget.contract}) — raising an output budget buys headroom by ` +
+          `truncating what mattered. Send less, or supersede the budget deliberately in the contract`,
+        ));
+        break;
+      }
+    }
+  }
   return results;
 }
 
+// A limit name comes from a contract table cell, so it is user text and
+// must not be spliced into a pattern unescaped.
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function pass(msg) {
   return { kind: "pass", line: c.green("✓ ") + msg };
 }

package/src/commands/context.js

@@ -235,18 +235,35 @@ export async function run(positional, cmdFlags) {
   // 6. Skills are on-demand: list name + description + trigger, never the
   //    body. The `when:` line is what lets an agent fire the right skill
   //    without loading any of them.
+  //    RANKED by the query (change 0029). Alphabetical order is the wrong
+  //    order for a list whose whole job is "fire the right one": on a
+  //    diagnostic task the agent would read four specs and still not learn
+  //    that CI injects an empty string, because the skill that says so sat
+  //    at the bottom under `z`. The TRIGGER is what a task matches against,
+  //    so it is weighted above the description — that is what `when:` is
+  //    for. A skill with no query to rank on keeps alphabetical order.
   const onDemand = [];
   const skillsDir = path.join(projectRoot, ".doctrina", "skills");
   for (const f of walk(skillsDir)) {
     if (!f.endsWith(".md")) continue;
     const text = read(f);
+    const name = parseFrontmatter(text, "name") ?? path.basename(f, ".md");
+    const description = parseFrontmatter(text, "description") ?? "<missing description>";
+    const when = parseFrontmatter(text, "when") ?? null;
     onDemand.push({
       rel: relPath(projectRoot, f),
-      name: parseFrontmatter(text, "name") ?? path.basename(f, ".md"),
-      description: parseFrontmatter(text, "description") ?? "<missing description>",
-      when: parseFrontmatter(text, "when") ?? null,
+      name,
+      description,
+      when,
+      // The trigger is the emphasis field, so a term matching `when:`
+      // outranks the same term buried in the body.
+      rank: relevance(`${when ?? ""} ${description} ${name}`, terms, `${when ?? ""} ${name}`),
     });
   }
+  if (terms.length > 0) {
+    onDemand.sort((a, b) => compareRank(b.rank, a.rank) || a.name.localeCompare(b.name));
+  }
+  const skillsMatched = onDemand.filter((s) => s.rank[1] > 0).length;
 
   // Fit the pack to the budget. This mutates items in place (degrading) and
   // returns what it had to give up, so the report can name it.
@@ -278,11 +295,21 @@ export async function run(positional, cmdFlags) {
     reportBudget(totalTokens, budget, fit, (msg) => console.log(msg));
     if (onDemand.length > 0) {
       console.log("");
-      console.log(c.bold("On-demand skills") + c.gray(" (load the body only when the trigger fires):"));
+      const heading = skillsMatched > 0
+        ? c.bold("On-demand skills") + c.gray(` — ${skillsMatched} match this task; READ THESE FIRST:`)
+        : c.bold("On-demand skills") + c.gray(" (load the body only when the trigger fires):");
+      console.log(heading);
       for (const s of onDemand) {
-        console.log(`   ${c.cyan(s.name.padEnd(26))} ${s.description}`);
+        // A skill whose trigger the task actually matches is marked, so the
+        // list stops being a uniform inventory the reader has to scan.
+        const hit = s.rank[1] > 0 ? c.green("→ ") : "  ";
+        console.log(` ${hit}${c.cyan(s.name.padEnd(26))} ${s.description}`);
         if (s.when) console.log(`   ${" ".repeat(26)} ${c.gray(`when: ${s.when}`)}`);
       }
+      if (skillsMatched > 0) {
+        console.log("");
+        console.log(c.gray("   A matching skill is procedural memory for THIS task — read it before the specs above."));
+      }
     }
   }
 

package/src/commands/contract.js

@@ -12,6 +12,10 @@ import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
+import {
+  parseTable, parseRuntimeDeclaration, checkWiring, checkEmptySemantics,
+  checkEnums, checkSelectors,
+} from "../lib/runtime.js";
 
 // Contracts are the first-class home for the integration/runtime surface
 // no single capability owns: the port map, the env/dependency contract,
@@ -82,6 +86,7 @@ function contractNew(args, flags) {
   console.log(c.green("indexed") + ` contract "${name}"`);
   console.log("");
   console.log("Fill in the Ports / Environment / Interfaces tables, then run " + c.cyan("doctrina contract check") + ".");
+  console.log(c.gray("Declaring Wiring and Selectors rows is what makes the RUNTIME half checkable — without them, check can only verify the prose."));
   return 0;
 }
 
@@ -186,6 +191,35 @@ function contractCheck(args, _flags) {
         errors += 1;
       }
     }
+
+    // 4. The RUNTIME half: a declaration is only worth what binds it to the
+    //    running system. These checks read the contract's Wiring, Selectors
+    //    and Values declarations and hold the implementation to them — the
+    //    "I set the secret in GitHub and nothing happened" class, the
+    //    default that an empty value never triggers, the enum nothing
+    //    validates, and the selector that matches zero cases and exits 0.
+    //    Every section is optional, so a contract written before they
+    //    existed checks exactly as it did before.
+    const decl = parseRuntimeDeclaration(text);
+    for (const f of [
+      ...checkWiring(projectRoot, decl),
+      ...checkEmptySemantics(projectRoot, decl),
+      ...checkEnums(projectRoot, decl),
+      ...checkSelectors(projectRoot, decl),
+    ]) {
+      const mark = f.level === "error" ? c.red("  ✗ ") : c.yellow("  ! ");
+      console.log(mark + f.message + c.gray(` [${f.code}]`));
+      console.log(`      ${c.gray(`fix: ${f.remedy}`)}`);
+      if (f.level === "error") errors += 1;
+      else warnings += 1;
+    }
+
+    if (decl.wiring.length + decl.selectors.length === 0) {
+      // Silence here is not proof of correctness — it is proof that nothing
+      // was declared. Saying so is what stops a green check from being read
+      // as "the wiring is verified".
+      console.log(c.gray("  · no Wiring or Selectors declared — the runtime surface is unchecked"));
+    }
   }
 
   console.log("");
@@ -198,21 +232,6 @@ function contractCheck(args, _flags) {
   return errors === 0 ? 0 : 1;
 }
 
-// Parse a GitHub-flavoured Markdown table into { headers, rows }.
-function parseTable(text) {
-  const lines = text.split(/\r?\n/).filter((l) => /^\s*\|/.test(l));
-  if (lines.length < 2) return null;
-  const cells = (line) => line.trim().replace(/^\||\|$/g, "").split("|").map((cl) => cl.trim());
-  const headers = cells(lines[0]);
-  const rows = [];
-  for (let i = 1; i < lines.length; i++) {
-    const row = cells(lines[i]);
-    if (row.every((cl) => /^:?-+:?$/.test(cl) || cl === "")) continue; // separator row
-    rows.push(row);
-  }
-  return { headers, rows };
-}
-
 function colIndex(headers, name) {
   const i = headers.findIndex((h) => h.toLowerCase() === name.toLowerCase());
   return i < 0 ? 0 : i;
@@ -240,8 +259,29 @@ the port map, the environment contract, and API/WS/event interfaces.
 Subcommands:
   new <name>          Scaffold .doctrina/contracts/<name>.md and index it
   list                One line per contract: id, status, last updated
-  check [<name>]      Verify the mechanically checkable parts: no two
-                      services share a port, every declared env var exists
-                      in .env.example, and every referenced spec exists.
-                      Exits 1 on errors (port collisions, missing specs).
+  check [<name>]      Verify the mechanically checkable parts.
+
+                      Structure: no two services share a port, every
+                      declared env var exists in .env.example, and every
+                      referenced spec exists.
+
+                      Runtime — the declaration held to the implementation:
+                        RT01/02  a variable declared with origin vars or
+                                 secrets must be exported by an env: block
+                                 in the workflow the Wiring row names, from
+                                 the origin and name it declares.
+                        RT03     its consumer must not give it a default
+                                 that only applies when ABSENT: CI injects
+                                 the empty string, so the default never
+                                 fires (textual lint).
+                        RT04     a declared Values enum must hold in
+                                 .env.example, and the consumer should
+                                 validate it.
+                        RT05     every declared selector must match at
+                                 least one target, or a run dispatched on
+                                 it executes nothing and still exits 0.
+
+                      No CI system or test runner is parsed natively: each
+                      check reads the glob, pattern and origin the contract
+                      declares. Exits 1 on errors, 0 on warnings only.
 `;

package/src/commands/coverage.js

@@ -71,22 +71,25 @@ export async function run(_positional, flags) {
   let totalCovered = 0;
   let totalDangling = 0;
   let totalConditional = 0;
+  let totalUnguarded = 0;
   let totalDeferred = 0;
   for (const rep of reports) {
     totalCriteria += rep.rows.length;
     totalCovered += rep.rows.filter((r) => r.kind === "covered").length;
     totalDangling += rep.rows.filter((r) => r.kind === "dangling").length;
     totalConditional += rep.rows.filter((r) => r.kind === "conditional").length;
+    totalUnguarded += rep.rows.filter((r) => r.kind === "unguarded").length;
     totalDeferred += rep.rows.filter((r) => r.kind === "deferred").length;
   }
   const jsonPct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
   // Deferred criteria are visible but never gate: declared debt ≠ hidden debt.
-  const jsonClean = totalCovered + totalDeferred === totalCriteria && totalDangling === 0 && totalConditional === 0;
+  const jsonClean = totalCovered + totalDeferred === totalCriteria && totalDangling === 0
+    && totalConditional === 0 && totalUnguarded === 0;
 
   if (json) {
     emitJson("coverage", {
       specs: reports.map((rep) => ({ capability: rep.cap, deferred: rep.deferred, criteria: rep.rows })),
-      summary: { criteria: totalCriteria, covered: totalCovered, dangling: totalDangling, conditional: totalConditional, deferred: totalDeferred, pct: jsonPct },
+      summary: { criteria: totalCriteria, covered: totalCovered, dangling: totalDangling, conditional: totalConditional, unguarded: totalUnguarded, deferred: totalDeferred, pct: jsonPct },
     });
     return jsonClean ? 0 : strict ? 1 : 0;
   }
@@ -98,10 +101,12 @@ export async function run(_positional, flags) {
     const covered = rep.rows.filter((r) => r.kind === "covered").length;
     const dangling = rep.rows.filter((r) => r.kind === "dangling").length;
     const conditional = rep.rows.filter((r) => r.kind === "conditional").length;
+    const unguarded = rep.rows.filter((r) => r.kind === "unguarded").length;
     const deferredN = rep.rows.filter((r) => r.kind === "deferred").length;
 
     const notes = [];
     if (conditional > 0) notes.push(c.yellow(`${conditional} conditional`));
+    if (unguarded > 0) notes.push(c.yellow(`${unguarded} unguarded`));
     if (dangling > 0) notes.push(c.yellow(`${dangling} dangling`));
     if (deferredN > 0) notes.push(c.gray(`${deferredN} deferred`));
     const note = notes.length > 0 ? `  (${notes.join(", ")})` : "";
@@ -114,6 +119,8 @@ export async function run(_positional, flags) {
         console.log(`    ${c.red("✗")} #${r.n}  no evidence linked — cite the file/test that proves it in backticks`);
       } else if (r.kind === "conditional") {
         console.log(`    ${c.yellow("!")} #${r.n}  evidence is a skipped test (proves nothing): ${r.skipped.map((m) => `\`${m}\``).join(", ")}`);
+      } else if (r.kind === "unguarded") {
+        console.log(`    ${c.red("✗")} #${r.n}  orchestration claim is not fail-closed: ${r.reason}`);
       } else {
         console.log(`    ${c.yellow("!")} #${r.n}  evidence not found on disk: ${r.missing.map((m) => `\`${m}\``).join(", ")}`);
       }
@@ -123,9 +130,11 @@ export async function run(_positional, flags) {
   const pct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
   console.log("");
   const summary = `${totalCovered} of ${totalCriteria} acceptance criteria across ${reports.length} spec${reports.length === 1 ? "" : "s"} have linked evidence (${pct}%)`;
-  const clean = totalCovered + totalDeferred === totalCriteria && totalDangling === 0 && totalConditional === 0;
+  const clean = totalCovered + totalDeferred === totalCriteria && totalDangling === 0
+    && totalConditional === 0 && totalUnguarded === 0;
   const extras = [];
   if (totalConditional > 0) extras.push(`${totalConditional} conditional`);
+  if (totalUnguarded > 0) extras.push(`${totalUnguarded} unguarded`);
   if (totalDangling > 0) extras.push(`${totalDangling} dangling`);
   if (totalDeferred > 0) extras.push(`${totalDeferred} deferred (not gated)`);
   const extraSummary = extras.length > 0 ? `, ${extras.join(", ")}` : "";
@@ -248,13 +257,14 @@ export function summarize(projectRoot) {
     const covered = rep.rows.filter((r) => r.kind === "covered").length;
     const dangling = rep.rows.filter((r) => r.kind === "dangling").length;
     const conditional = rep.rows.filter((r) => r.kind === "conditional").length;
+    const unguarded = rep.rows.filter((r) => r.kind === "unguarded").length;
     const deferred = rep.rows.filter((r) => r.kind === "deferred").length;
     totalCriteria += rep.rows.length;
     totalCovered += covered;
     totalDangling += dangling;
     totalConditional += conditional;
     totalDeferred += deferred;
-    perCap.push({ cap: rep.cap, total: rep.rows.length, covered, dangling, conditional, deferred });
+    perCap.push({ cap: rep.cap, total: rep.rows.length, covered, dangling, conditional, unguarded, deferred });
   }
   const pct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
   return { perCap, totalCriteria, totalCovered, totalDangling, totalConditional, totalDeferred, pct };
@@ -297,8 +307,84 @@ function extractAcceptanceCriteria(text) {
   return out.filter((s) => s.length > 0);
 }
 
+// ORCHESTRATION criteria (change 0029). Coverage measures CITATION: a
+// criterion is covered when it cites a file that exists (and, since G3, a
+// test whose suite is not skipped). That is the right test for "this
+// function behaves", and the wrong one for "the pipeline ran at all".
+//
+// A criterion like "absence of the report is explicit and the step does not
+// fail" is satisfied, on paper, by a job that executed zero cases and
+// printed a well-written empty state — the citation resolves, the suite is
+// not skipped, and the only visible signal is a tidy message saying nothing
+// happened. Coverage calls that proven.
+//
+// Marking a criterion `[orchestration]` says: the claim is that a RUN
+// happened, so the proof must be a fail-closed one. It cites a verify check
+// by name (`verify:<check>`), and that check must declare an `expect` guard
+// — the thing that turns "exit 0" into "exit 0 having actually done
+// something". A named check without a guard is UNGUARDED: the criterion is
+// not proven, and says so, instead of quietly counting as covered.
+const ORCHESTRATION_MARKER = /^orchestration\b/;
+
+function citedVerifyChecks(criterion) {
+  const out = new Set();
+  for (const m of criterion.matchAll(/`verify:([A-Za-z0-9_.-]+)`/g)) out.add(m[1]);
+  return [...out];
+}
+
+function guardedVerifyChecks(projectRoot) {
+  const configPath = path.join(projectRoot, ".doctrina", "verify.json");
+  if (!isFile(configPath)) return null;
+  let config;
+  try {
+    config = JSON.parse(read(configPath));
+  } catch {
+    return null;
+  }
+  const map = new Map();
+  for (const ch of Array.isArray(config?.checks) ? config.checks : []) {
+    if (!ch?.name) continue;
+    const exp = ch.expect;
+    const guarded = Boolean(exp && typeof exp === "object"
+      && (typeof exp.fail_if_output_matches === "string" || typeof exp.require_output_matches === "string"));
+    map.set(ch.name, guarded);
+  }
+  return map;
+}
+
+function classifyOrchestration(criterion, n, projectRoot) {
+  const named = citedVerifyChecks(criterion);
+  if (named.length === 0) {
+    return { kind: "unguarded", n, reason: "cites no verify check — an orchestration claim is proven by a fail-closed check, cited as `verify:<check>`" };
+  }
+  const checks = guardedVerifyChecks(projectRoot);
+  if (checks === null) {
+    return { kind: "dangling", n, missing: named.map((x) => `verify:${x}`) };
+  }
+  const unknown = named.filter((x) => !checks.has(x));
+  if (unknown.length > 0) {
+    return { kind: "dangling", n, missing: unknown.map((x) => `verify:${x}`) };
+  }
+  const unguarded = named.filter((x) => !checks.get(x));
+  if (unguarded.length > 0) {
+    return {
+      kind: "unguarded",
+      n,
+      reason: `verify check${unguarded.length === 1 ? "" : "s"} ${unguarded.join(", ")} declare${unguarded.length === 1 ? "s" : ""} no "expect" guard — a check that exits 0 having run nothing would still pass it`,
+    };
+  }
+  return { kind: "covered", n, evidence: [] };
+}
+
 // Decide whether a single criterion is covered, conditional, dangling, or bare.
 function classify(criterion, n, projectRoot, specDir) {
+  // An orchestration criterion is judged on its GUARD, not on whether a
+  // cited file exists — the whole point is that existence proves nothing here.
+  const marker = criterion.match(/^\[([^\]]+)\]/)?.[1]?.toLowerCase() ?? "";
+  if (ORCHESTRATION_MARKER.test(marker)) {
+    return classifyOrchestration(criterion, n, projectRoot);
+  }
+
   const cited = extractBacktickPaths(criterion);
   if (cited.length === 0) return { kind: "bare", n };
   const missing = [];
@@ -390,15 +476,31 @@ A criterion is covered when a cited path resolves to real proof,
 conditional when its only resolving proof is a test file whose suite is
 skipped (\`describe.skip\` / \`xit\` / \`@pytest.mark.skip\` — proves
 nothing), dangling when a cited path is missing on disk, and bare when
-nothing is cited. A spec that declares a deliberate deferral —
+nothing is cited.
+
+ORCHESTRATION criteria. Citation is the right proof for "this function
+behaves" and the wrong one for "the pipeline ran at all": a criterion
+like "absence of the report is explicit and the step does not fail" is
+satisfied on paper by a job that executed zero cases and printed a
+well-written empty state. Mark such a criterion [orchestration] and cite
+a verify check by name:
+
+  3. [orchestration] the e2e suite actually executes scenarios —
+     verified by \`verify:e2e\`
+
+That check must declare an "expect" guard (see \`doctrina verify --help\`).
+A cited check with no guard is reported UNGUARDED and fails --strict: a
+check that exits 0 having run nothing would otherwise satisfy the claim.
+
+A spec that declares a deliberate deferral —
 \`Implementation: planned — <why>\`, the same escape hatch validate
 honours — has its unproven criteria reported as DEFERRED: visible, but
 never a --strict failure (declared debt is not hidden debt).
 
 Flags:
-  --strict           Exit 1 when any criterion is bare, dangling, or
-                     conditional (CI gate). Deferred never fails. Without
-                     it the command always exits 0 (a report).
+  --strict           Exit 1 when any criterion is bare, dangling,
+                     conditional, or unguarded (CI gate). Deferred never
+                     fails. Without it the command always exits 0 (a report).
   --only <cap,cap>   Scope the report/gate to specific capabilities
                      (\`doctrina close\` uses this so an unrelated deferred
                      spec cannot block a change's close).

package/src/commands/doctor.js

@@ -7,6 +7,8 @@ import { exists } from "../lib/fs-ops.js";
 import { collectStatus } from "./status.js";
 import { collectFindings } from "./templates.js";
 import { c } from "../lib/colors.js";
+import { flagBool } from "../lib/args.js";
+import { collectRuntimeFindings, checkLocalEnv } from "../lib/runtime.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
 
 // Aggregate diagnostic: the one command to run when "something looks wrong"
@@ -21,7 +23,7 @@ const cliEntry = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."
 // 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"], string: [] };
+export const flags = { boolean: ["json", "env"], string: [] };
 
 export async function run(_positional, _flags) {
   const projectRoot = process.cwd();
@@ -123,7 +125,48 @@ export async function run(_positional, _flags) {
     }
   }
 
-  // 6. Verify configuration (the real build gate must exist to be run).
+  // 6. The RUNTIME surface (change 0029). Every row above reads Markdown;
+  //    this one reads what the Markdown CLAIMS about the running system and
+  //    checks it — the wiring, the empty-vs-unset default, the enum, the
+  //    selector that would match nothing. Still a driver: the checks belong
+  //    to lib/runtime.js and `contract check` renders the same verdict.
+  {
+    const runtime = collectRuntimeFindings(projectRoot);
+    const errs = runtime.findings.filter((f) => f.level === "error");
+    const warns = runtime.findings.length - errs.length;
+    if (runtime.contracts === 0) {
+      row("ok", "runtime", "no contracts — nothing declares a runtime surface");
+    } else if (runtime.declared === 0) {
+      // Silence is not proof: an undeclared surface is UNCHECKED, and a row
+      // that read "ok" here would be the exact false confidence this
+      // command exists to prevent.
+      row("warn", "runtime", `${runtime.contracts} contract${runtime.contracts === 1 ? "" : "s"}, 0 Wiring/Selectors rows — the runtime surface is unchecked`, "declare Wiring/Selectors rows, then `doctrina contract check`");
+      warningsTotal += 1;
+    } else if (errs.length > 0) {
+      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");
+      warningsTotal += 1;
+    } else {
+      row("ok", "runtime", `${runtime.declared} declared row${runtime.declared === 1 ? "" : "s"} hold`);
+    }
+  }
+
+  // 7. The local .env, opt-in. Off by default because it reads a file that
+  //    is not committed and is none of CI's business; when asked for, it
+  //    reports NAMES and enum membership only and never the value.
+  if (flagBool(_flags, "env", false)) {
+    const envFindings = checkLocalEnv(projectRoot);
+    if (envFindings.length === 0) {
+      row("ok", "local .env", "matches the declared names and enums (or no .env present)");
+    } else {
+      row("fail", "local .env", `${envFindings.length} finding${envFindings.length === 1 ? "" : "s"} — config would be rejected on boot`, "fix the named variables (values are never printed)");
+      for (const e of envFindings.slice(0, 3)) console.log(`        ${" ".repeat(16)} ${c.red("·")} ${e.message}`);
+    }
+  }
+
+  // 8. Verify configuration (the real build gate must exist to be run).
   if (s.verify.invalid) row("fail", "verify config", ".doctrina/verify.json is invalid JSON", "fix the JSON, then `doctrina verify`");
   else if (!s.verify.configured) {
     row("warn", "verify config", "no verify.json — the build gate is undeclared", "doctrina verify --init");
@@ -158,9 +201,16 @@ Usage: doctrina doctor
 
 Aggregate diagnostic: run the structural gate (validate), the index
 drift check, the coverage/trace ratios, the clean-checkout lint
-(verify --clean), the template-shape check, and the verify-config
-presence — each reported with its exact remediation command.
+(verify --clean), the template-shape check, the RUNTIME surface (the
+declared wiring, enums and selectors, checked against the code and
+workflows), and the verify-config presence — each reported with its
+exact remediation command.
+
+  --env    also check the local .env against the declared names and
+           enums. Reports membership only; a rejected value is never
+           printed, so this is safe to run and to paste.
 
-A driver over the existing commands; it adds no checks of its own.
+A driver over the existing commands and lib/runtime.js; it adds no
+checks of its own, so it can never disagree with the gates it fronts.
 Read-only. Exits 1 when any area fails, 0 otherwise (warnings allowed).
 `;

package/src/commands/next.js

@@ -8,6 +8,7 @@ import { deriveIndex, indexesMatch, listHeader } from "../lib/scan.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { emitJson } from "../lib/json-out.js";
+import { collectRuntimeFindings } from "../lib/runtime.js";
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
@@ -55,6 +56,26 @@ export async function run(_positional, flags) {
 export function computeActions(projectRoot) {
   const actions = [];
 
+  // RUNTIME FIRST (change 0029). A declared wiring that does not hold is
+  // not a queue item — it is the reason the last run lied. After a job goes
+  // green having executed nothing, "open a change on the observability
+  // capability" sends the agent to polish the Markdown of an empty-state
+  // message while the cause sits in a file no other action names. A broken
+  // declaration outranks every artifact chore below it.
+  try {
+    const runtime = collectRuntimeFindings(projectRoot);
+    const errs = runtime.findings.filter((f) => f.level === "error");
+    if (errs.length > 0) {
+      actions.push(
+        `doctrina triage — ${errs.length} runtime declaration${errs.length === 1 ? " does" : "s do"} not hold ` +
+        `(first: ${errs[0].code} ${errs[0].message.slice(0, 80)}${errs[0].message.length > 80 ? "…" : ""})`,
+      );
+    }
+  } catch {
+    // A malformed contract is `validate`'s finding to make, not a reason
+    // for `next` to fall over.
+  }
+
   // A pending intake is the very first thing to resolve: until it is
   // converted, product.md and the specs are still empty scaffolding.
   const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
@@ -178,7 +199,9 @@ export const help = `
 Usage: doctrina next [--json]
 
 Inspect the .doctrina/ tree and print the recommended next workflow
-actions in priority order: open changes (missing proposal, unchecked
+actions in priority order: runtime declarations that no longer hold
+(a broken wiring outranks every artifact chore — it is why the last
+run lied), open changes (missing proposal, unchecked
 tasks, deltas ready to apply, applied-but-unarchived), ADRs still in
 proposed status, accepted ADRs with nothing proving them (cite Evidence
 or run "decision land"), a skill-capture nudge when a past fix went