doctrina-cli 0.15.0 → 0.16.0

package/src/lib/names.js

@@ -0,0 +1,42 @@
+// @ts-check
+// One grammar for the NAME of a spec, a contract or a skill (change 0110).
+//
+// Three commands carried their own copy of `/^[a-z][a-z0-9-]*$/`, and none
+// of them knew anything about a file system. Measured on Windows: `spec new
+// nul` created `.doctrina/specs/nul/spec.md` — a directory Node could write
+// and git could neither see nor remove (`could not open directory`, `failed
+// to remove`), gone only through a `\\?\` path. `con`, `prn`, `aux`,
+// `com1`-`com9` and `lpt1`-`lpt9` are device names on Windows, and this
+// repository's own tree is Windows/CRLF. A 120-character name passed too
+// (`Filename too long` from git), as did `trail-` and `a--b`.
+//
+// A name is a directory name on every file system the project will touch.
+// The message names the rule that failed, so the fix is the invocation.
+
+const RESERVED = new Set([
+  "con", "prn", "aux", "nul",
+  ...Array.from({ length: 9 }, (_, i) => `com${i + 1}`),
+  ...Array.from({ length: 9 }, (_, i) => `lpt${i + 1}`),
+]);
+
+const NAME_MAX = 64;
+
+/**
+ * null when `name` is a legal artifact name; otherwise the reason, ready to
+ * print after "error:".
+ *
+ * @param {string | undefined} name
+ * @param {string} kind  "capability" | "contract name" | "skill name"
+ * @returns {string | null}
+ */
+export function artifactNameError(name, kind) {
+  const value = String(name ?? "");
+  if (value === "") return `${kind} is required`;
+  if (!/^[a-z0-9-]+$/.test(value)) return `${kind} must be lowercase letters, digits, or hyphens (got "${value}")`;
+  if (!/^[a-z]/.test(value)) return `${kind} must start with a letter (got "${value}")`;
+  if (/-$/.test(value)) return `${kind} must not end with a hyphen (got "${value}")`;
+  if (/--/.test(value)) return `${kind} must not contain a doubled hyphen (got "${value}")`;
+  if (value.length > NAME_MAX) return `${kind} must be at most ${NAME_MAX} characters (got ${value.length})`;
+  if (RESERVED.has(value)) return `${kind} "${value}" is a reserved device name on Windows — a directory git cannot see or remove there; pick another`;
+  return null;
+}

package/src/lib/playbook.js

@@ -0,0 +1,97 @@
+// @ts-check
+import { c } from "./colors.js";
+import { readTemplate, substitute } from "./templates.js";
+
+// Playbooks are TEMPLATES, not code (audit finding F17).
+//
+// `printPlaybook()` was ~100 lines of literal `console.log` — including the
+// documentation of the ops grammar — and the same procedure was written out
+// again in AGENTS.md and twice more in docs/{en,pt}/workflow.md. Four homes
+// for one fact, in the framework whose first design principle is that a fact
+// has exactly one.
+//
+// Worse for adopters: a team whose process differs (an extra review step, a
+// different close) had no way to say so. Every other scaffold resolves
+// project-over-bundled per file (ADR 0019); the procedure the agent actually
+// executes was the one thing hard-coded.
+//
+// So a playbook resolves through the same chain, and this module renders it.
+//
+// ---------------------------------------------------------------------------
+// The markup
+// ---------------------------------------------------------------------------
+//
+// Colour has to survive the move, or the output changes and the migration is
+// not faithful. The template marks spans inline:
+//
+//   [[c]]doctrina close 0001[[/c]]   cyan   — a command to run
+//   [[g]]...[[/g]]                   gray   — commentary
+//   [[b]]...[[/b]]                   bold   — a heading
+//   [[y]]...[[/y]]                   yellow — a warning
+//
+// Markup is expanded BEFORE token substitution, deliberately: a token's value
+// can carry a user's prompt, and a prompt must never be able to inject colour
+// into the playbook. Blocks the CLI computes (a capability ranking, a warning
+// list) arrive already coloured through `c.*`, so they need no markup.
+//
+// Everything variable is a TOKEN, and the code pre-renders it. That answers
+// the open question the change carried — extend the substituter, or
+// pre-render? — in favour of pre-rendering: `substitute` stays a plain
+// string map, and the template stays a document rather than becoming a
+// programming language with conditionals and loops in it.
+
+const MARKS = { c: c.cyan, g: c.gray, b: c.bold, y: c.yellow };
+
+/** Expand `[[x]]...[[/x]]` colour spans. Innermost first, so spans nest. */
+export function expandMarkup(text) {
+  let out = String(text);
+  let previous;
+  do {
+    previous = out;
+    out = out.replace(/\[\[([cgby])\]\]((?:(?!\[\[[cgby]\]\])[\s\S])*?)\[\[\/\1\]\]/g,
+      (_, mark, body) => MARKS[mark](body));
+  } while (out !== previous);
+  return out;
+}
+
+/**
+ * Render a named playbook, resolved project-over-bundled.
+ *
+ * Returns the text; the caller prints it. Keeping the write at the edge is
+ * what lets a test assert the rendering without capturing stdout.
+ */
+export function renderPlaybook(projectRoot, name, tokens = {}) {
+  const tpl = readTemplate(projectRoot, `playbooks/${name}.md.template`);
+  // A trailing newline in the file would print an extra blank line; the
+  // caller decides its own spacing.
+  return substitute(expandMarkup(dropEmptyBlocks(tpl.body, tokens)), tokens).replace(/\n$/, "");
+}
+
+/**
+ * A line holding NOTHING but one token, whose value is empty or absent, is
+ * removed rather than left as a blank line.
+ *
+ * That single rule is what lets the optional parts of a playbook — the
+ * thin-prompt warning, the capability hint, the backfill note — be plain
+ * tokens on their own line instead of conditionals in a template language.
+ * A block that IS present brings its own spacing in its value.
+ */
+function dropEmptyBlocks(body, tokens) {
+  return body
+    .split("\n")
+    .filter((line) => {
+      const m = line.match(/^\s*\{\{(\w+)\}\}\s*$/);
+      if (!m) return true;
+      const value = tokens[m[1]];
+      return value !== undefined && String(value) !== "";
+    })
+    .join("\n");
+}
+
+/** Render and print. The one place a playbook reaches stdout. */
+export function printPlaybookTemplate(projectRoot, name, tokens = {}) {
+  console.log(renderPlaybook(projectRoot, name, tokens));
+}
+
+/** The playbooks the CLI ships and `templates check` expects to resolve. */
+export const PLAYBOOKS = ["work", "chore", "bootstrap"];

package/src/lib/project.js

@@ -0,0 +1,57 @@
+// @ts-check
+import path from "node:path";
+import { exists } from "./fs-ops.js";
+import { notADoctrinaProject } from "./exit-codes.js";
+
+// The one precondition every command shares: this is a Doctrina project.
+// Six command modules carried an identical private copy of it; a lib
+// operation that needs it should not have to reach into a command for the
+// check (audit finding F7).
+export function ensureDoctrinaProject(projectRoot) {
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw notADoctrinaProject();
+  }
+}
+
+// The grammar a change id obeys: lowercase letters, digits and hyphens,
+// opening on a letter or a digit — `0042-short-slug` is the shape `work`
+// derives. Deliberately NOT the capability grammar, which additionally
+// requires a leading letter; two rules that look alike are not one rule.
+//
+// It exists because `change new` had NO grammar (third audit, finding 1).
+// Every other authoring command validated its argument; `change new` joined
+// whatever it was given onto a path, so `change new ../../../elsewhere/evil`
+// wrote a change folder OUTSIDE the project — against the `authoring` spec's
+// own "shall not write outside the project working directory" — and ids like
+// `0003-com espaco` reached `validate` and `index rebuild` as legitimate,
+// producing a `next` action whose command could not be run.
+export const CHANGE_ID = /^[a-z0-9][a-z0-9-]*$/;
+
+export function isChangeId(id) {
+  return typeof id === "string" && CHANGE_ID.test(id);
+}
+
+/**
+ * Resolve `segments` under `projectRoot` and refuse anything that escapes it.
+ *
+ * Defence in depth, deliberately separate from the grammar above: the
+ * grammar is what tells the USER their id is wrong, and this is what holds
+ * even when a caller forgets to ask. A path is inside when it is the root
+ * itself or sits beneath it — compared after `path.resolve`, so `..`,
+ * absolute arguments and symlink-free trickery all normalise first.
+ *
+ * Throws rather than returning a code: a caller that reached here with an
+ * escaping path has a bug, and the entrypoint's catch turns a thrown error
+ * into the gate class with the message intact.
+ */
+export function resolveWithinProject(projectRoot, ...segments) {
+  const root = path.resolve(projectRoot);
+  const target = path.resolve(root, ...segments);
+  const rel = path.relative(root, target);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new Error(
+      `refusing to write outside the project: "${path.join(...segments)}" resolves to ${target}`,
+    );
+  }
+  return target;
+}

package/src/lib/reproducibility.js

@@ -0,0 +1,137 @@
+// @ts-check
+// The clean-checkout reproducibility lint, as a collection rather than a
+// printout: "would a fresh clone of this repository actually build?"
+//
+// It lives here because two commands ask it — `verify --clean` renders it,
+// and `doctor` reports it as one row. `doctor` used to answer by spawning
+// the CLI again and reading its exit code, which is a second integration
+// style inside one binary and a process per row (audit finding F4).
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { read, relPath } from "./fs-ops.js";
+
+/**
+ * Static reproducibility lint: walk the project's package.json files and
+ * report the two "works on my machine" footguns the review hit — a package
+ * whose entry points live in a build-output dir with nothing that builds it
+ * on install, and a codegen dependency (Prisma) with no install hook that
+ * generates. A pure read: it returns what it found and prints nothing, so
+ * `verify --clean` renders it and `doctor` reports it as one row without
+ * spawning the CLI again to read its exit code (audit finding F4).
+ *
+ * @param {string} projectRoot
+ * @returns {{packages: number, findings: string[]}}
+ */
+export function collectReproducibility(projectRoot) {
+  const pkgPaths = findPackageJsons(projectRoot);
+  const findings = [];
+  for (const pkgPath of pkgPaths) {
+    const rel = relPath(projectRoot, pkgPath);
+    let pkg;
+    try {
+      pkg = JSON.parse(read(pkgPath));
+    } catch (err) {
+      findings.push(`${rel}: not valid JSON (${err.message})`);
+      continue;
+    }
+    const scripts = pkg.scripts ?? {};
+    const hasInstallBuild = typeof scripts.prepare === "string" || typeof scripts.prepack === "string";
+
+    // 1. Entry point into a build output with nothing to build it on install.
+    const built = entryIntoBuildDir(pkg);
+    if (built && !hasInstallBuild) {
+      findings.push(
+        `${rel}: ${built.field} → \`${built.value}\` is a build output, but no "prepare"/"prepack" ` +
+        `script builds it on install — a fresh install/clone won't have it (add a prepare script, or commit the output)`,
+      );
+    }
+
+    // 2. Codegen dependency with no install hook that generates.
+    const deps = {
+      ...pkg.dependencies, ...pkg.devDependencies,
+      ...pkg.peerDependencies, ...pkg.optionalDependencies,
+    };
+    for (const [dep, gen] of Object.entries(CODEGEN_DEPS)) {
+      if (!(dep in deps)) continue;
+      const installHook = `${scripts.postinstall ?? ""} ${scripts.prepare ?? ""}`;
+      if (!gen.test(installHook)) {
+        findings.push(
+          `${rel}: depends on "${dep}" but no "postinstall"/"prepare" runs its codegen ` +
+          `(\`${gen.source.replace(/\\s\+/g, " ")}\`) — a fresh install has no generated output`,
+        );
+      }
+    }
+  }
+
+  return { packages: pkgPaths.length, findings };
+}
+
+// Known codegen dependencies → the command an install hook must run so a
+// fresh install produces their generated output.
+const CODEGEN_DEPS = {
+  "@prisma/client": /prisma\s+generate/,
+  "prisma": /prisma\s+generate/,
+};
+
+const BUILD_DIR_RE = /(?:^|\/)(?:dist|build|out)\//;
+
+// The first entry-point field that points into a build-output directory, or
+// null. Scans main/module/types/typings, bin (string or map), and exports
+// (recursively, string leaves only).
+function entryIntoBuildDir(pkg) {
+  for (const field of ["main", "module", "types", "typings"]) {
+    if (typeof pkg[field] === "string" && BUILD_DIR_RE.test(pkg[field])) {
+      return { field, value: pkg[field] };
+    }
+  }
+  if (typeof pkg.bin === "string" && BUILD_DIR_RE.test(pkg.bin)) return { field: "bin", value: pkg.bin };
+  if (pkg.bin && typeof pkg.bin === "object") {
+    for (const v of Object.values(pkg.bin)) {
+      if (typeof v === "string" && BUILD_DIR_RE.test(v)) return { field: "bin", value: v };
+    }
+  }
+  const fromExports = scanExports(pkg.exports);
+  if (fromExports) return { field: "exports", value: fromExports };
+  return null;
+}
+
+function scanExports(node) {
+  if (typeof node === "string") return BUILD_DIR_RE.test(node) ? node : null;
+  if (node && typeof node === "object") {
+    for (const v of Object.values(node)) {
+      const hit = scanExports(v);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+
+// Bounded walk for package.json files: skip dependency, build, and VCS
+// directories so the lint stays fast and ignores vendored manifests.
+const LINT_SKIP_DIRS = new Set([
+  ".git", "node_modules", "dist", "build", "out", "vendor", ".next",
+  "coverage", ".venv", "venv", "__pycache__", "target", ".doctrina",
+]);
+
+function findPackageJsons(projectRoot) {
+  const found = [];
+  const stack = [projectRoot];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!LINT_SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) stack.push(full);
+      } else if (entry.name === "package.json") {
+        found.push(full);
+      }
+    }
+  }
+  return found.sort();
+}

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)) {
@@ -532,10 +573,77 @@ export function checkSelectors(projectRoot, decl) {
   return findings;
 }
 
-// A minimal glob: `**` spans directories, `*` stays inside one segment.
-// Enough for the "where do my selectors live" declarations, with no
-// dependency and no surprises.
+/**
+ * Expand one level of brace alternation: `a/{x,y}.js` -> [`a/x.js`, `a/y.js`],
+ * recursively, so several groups in one pattern all expand.
+ *
+ * Added for the `**Source:**` declarations (change 0077), where a capability
+ * that owns eleven sibling modules would otherwise need eleven globs on one
+ * header line. Braces have no meaning in a path, so this takes nothing away
+ * from the patterns that were already valid.
+ */
+export function expandBraces(glob) {
+  const text = String(glob);
+  const open = text.indexOf("{");
+  if (open < 0) return [text];
+
+  // The MATCHING close, by depth — `indexOf` finds the first one, which for
+  // `{a,{b,c}}` is the inner brace: the group was split at the wrong place
+  // and expanded to ["a}", "b", "c}"], matching `b`, missing `a` and `c`,
+  // and inventing `a}`. Silent, too, because SOMETHING matched, so
+  // `validate`'s dead-pattern check stayed quiet over a declaration that
+  // covered a third of what it claimed (change 0084).
+  let depth = 0;
+  let close = -1;
+  for (let i = open; i < text.length; i++) {
+    if (text[i] === "{") depth += 1;
+    else if (text[i] === "}") {
+      depth -= 1;
+      if (depth === 0) { close = i; break; }
+    }
+  }
+  // An unmatched brace expands to itself: the braces then compile as literal
+  // characters, so the pattern matches nothing and `validate` reports it
+  // rather than the caller silently covering less than it declared.
+  if (close < 0) return [text];
+
+  const head = text.slice(0, open);
+  const tail = text.slice(close + 1);
+  const out = [];
+  // Split on commas at depth zero, for the same reason: a comma inside a
+  // nested group separates that group's alternatives, not this one's.
+  const body = text.slice(open + 1, close);
+  let cur = "";
+  depth = 0;
+  const alts = [];
+  for (const ch of body) {
+    if (ch === "{") depth += 1;
+    else if (ch === "}") depth -= 1;
+    if (ch === "," && depth === 0) { alts.push(cur); cur = ""; continue; }
+    cur += ch;
+  }
+  alts.push(cur);
+  for (const alt of alts) out.push(...expandBraces(head + alt.trim() + tail));
+  return out;
+}
+
+// A minimal glob: `**` spans directories, `*` stays inside one segment, and
+// `{a,b}` alternates. Enough for the "where do my selectors live" and "which
+// code is mine" declarations, with no dependency and no surprises.
 export function globToRegExp(glob) {
+  // Always compile the EXPANSION, never the original. Using it only when it
+  // produced more than one alternative left `src/{a}.js` compiling with its
+  // braces as literal characters, so a one-element group matched nothing
+  // (change 0084).
+  const alternatives = expandBraces(glob);
+  if (alternatives.length > 1) {
+    return new RegExp(alternatives.map((g) => compileGlob(g).source).join("|"));
+  }
+  return compileGlob(alternatives[0]);
+}
+
+// One expanded, brace-free glob to a RegExp.
+function compileGlob(glob) {
   const segments = String(glob).split("/");
   const parts = [];
   for (let i = 0; i < segments.length; i++) {
@@ -558,7 +666,14 @@ export function globToRegExp(glob) {
   return new RegExp(`^${parts.join("")}$`);
 }
 
-function filesMatching(projectRoot, glob) {
+/**
+ * Every file under `projectRoot` matching one glob, project-relative.
+ *
+ * Exported since change 0077: `validate` asks the same question of a spec's
+ * `**Source:**` patterns that the selector check asks of a contract's — does
+ * this declaration point at anything that exists?
+ */
+export function filesMatching(projectRoot, glob) {
   const re = globToRegExp(glob);
   // Walk from the deepest literal directory prefix so a narrow glob never
   // costs a full-tree walk.
@@ -588,6 +703,34 @@ export function parseBudgets(decl) {
   return out;
 }
 
+/**
+ * The value this project declares for ONE budget, or `fallback` when it
+ * declares none.
+ *
+ * Every budget in this codebase has had two homes — a literal beside the
+ * check and a row in the contract's Budgets table — and every one of them
+ * drifted (change 0059, then 0072). The contract is the declaration, so it
+ * wins; the literal a caller passes is the shipped default for a project
+ * that declares nothing. A malformed contract is its own finding, never a
+ * reason for the caller to lose its check.
+ *
+ * @param {string} projectRoot
+ * @param {string} name
+ * @param {number} fallback
+ * @returns {{ value: number, declared: boolean }}
+ */
+export function declaredBudget(projectRoot, name, fallback) {
+  try {
+    const row = collectBudgets(projectRoot).get(name);
+    if (row && Number.isFinite(row.value) && row.value > 0) {
+      return { value: row.value, declared: true };
+    }
+  } catch {
+    // fall through to the shipped default
+  }
+  return { value: fallback, declared: false };
+}
+
 /** Every declared budget across every contract, keyed by limit name. */
 export function collectBudgets(projectRoot) {
   const out = new Map();
@@ -603,6 +746,88 @@ export function collectBudgets(projectRoot) {
 // The whole runtime verdict, for every contract in the project
 // ---------------------------------------------------------------------------
 
+/**
+ * The STRUCTURAL half of a contract, as findings (change 0103): port
+ * collisions, environment drift against `.env.example`, and references to
+ * capability specs that do not exist. These three lived inline in
+ * `contract check` while RT01-RT05 lived here — so `close`, which drives
+ * this collection, ran the runtime half and skipped the structural one: a
+ * contract with port 8080 claimed twice and a reference to a spec that did
+ * not exist failed `contract check` with 2 errors and passed the close's
+ * runtime step as "2 declared rows hold". One collection, every driver.
+ *
+ * @param {string} projectRoot
+ * @param {string} text  the contract's Markdown
+ * @returns {Finding[]}
+ */
+export function checkStructure(projectRoot, text) {
+  /** @type {Finding[]} */
+  const out = [];
+  const col = (headers, name) => {
+    const i = headers.findIndex((h) => h.toLowerCase() === name.toLowerCase());
+    return i < 0 ? 0 : i;
+  };
+
+  // CT01. Port collisions — two services must not claim the same port.
+  const ports = parseTable(getSection(text, "Ports"));
+  if (ports) {
+    const portCol = col(ports.headers, "port");
+    const svcCol = col(ports.headers, "service");
+    const seen = new Map();
+    for (const row of ports.rows) {
+      const port = (row[portCol] ?? "").trim();
+      if (!/^\d+$/.test(port)) continue;
+      const svc = (row[svcCol] ?? "?").trim();
+      if (seen.has(port)) {
+        out.push({
+          code: "CT01", level: "error",
+          message: `port ${port} is claimed by both "${seen.get(port)}" and "${svc}"`,
+          remedy: `give "${svc}" a port of its own in the Ports table, or drop the duplicate row`,
+        });
+      } else {
+        seen.set(port, svc);
+      }
+    }
+  }
+
+  // CT02. Environment drift — every declared variable must exist in
+  //       .env.example (when the project keeps one).
+  const envExamplePath = path.join(projectRoot, ".env.example");
+  const env = parseTable(getSection(text, "Environment"));
+  if (env && isFile(envExamplePath)) {
+    const envExample = read(envExamplePath);
+    const varCol = col(env.headers, "variable");
+    for (const row of env.rows) {
+      const name = (row[varCol] ?? "").trim();
+      if (!/^[A-Z][A-Z0-9_]*$/.test(name)) continue;
+      const declared = new RegExp(`^\\s*(export\\s+)?${name}\\s*=`, "m").test(envExample);
+      if (!declared) {
+        out.push({
+          code: "CT02", level: "warn",
+          message: `env var ${name} is in the contract but absent from .env.example`,
+          remedy: `add "${name}=" to .env.example, or drop the row from the Environment table`,
+          file: ".env.example",
+        });
+      }
+    }
+  }
+
+  // CT03. Referenced capability specs must exist.
+  for (const m of getSection(text, "References").matchAll(/specs\/([a-z][a-z0-9-]*)/g)) {
+    const refCap = m[1];
+    const specRel = `.doctrina/specs/${refCap}/spec.md`;
+    if (isFile(path.join(projectRoot, specRel))) continue;
+    if (out.some((f) => f.code === "CT03" && f.file === specRel)) continue;
+    out.push({
+      code: "CT03", level: "error",
+      message: `references spec "${refCap}" but ${specRel} does not exist`,
+      remedy: `create it with \`doctrina spec new ${refCap}\`, or correct the reference`,
+      file: specRel,
+    });
+  }
+  return out;
+}
+
 export function contractPaths(projectRoot) {
   const dir = path.join(projectRoot, ".doctrina", "contracts");
   if (!isDir(dir)) return [];
@@ -619,10 +844,12 @@ export function collectRuntimeFindings(projectRoot) {
   let declared = 0;
   const files = contractPaths(projectRoot);
   for (const file of files) {
-    const decl = parseRuntimeDeclaration(read(file));
+    const text = read(file);
+    const decl = parseRuntimeDeclaration(text);
     declared += decl.wiring.length + decl.selectors.length;
     const where = relPath(projectRoot, file).replaceAll("\\", "/");
     for (const f of [
+      ...checkStructure(projectRoot, text),
       ...checkWiring(projectRoot, decl),
       ...checkEmptySemantics(projectRoot, decl),
       ...checkEnums(projectRoot, decl),