doctrina-cli 0.21.0 → 0.22.0

package/src/lib/onboard.js

@@ -0,0 +1,197 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read } from "./fs-ops.js";
+import { checklistProgress, parseChangeTitle } from "./doc-model.js";
+import { intakeStatus } from "./intake-model.js";
+import { parseAcceptanceCriteria } from "./criteria.js";
+import { collect } from "./coverage-model.js";
+import { gitLines } from "./git.js";
+
+// THE CYCLE ONCE, ON THE REAL REPOSITORY (change 0256).
+//
+// A newcomer had the reference (2,900 lines), a getting-started page, and
+// `next`, which names one action and assumes the reader knows why. Nothing
+// walked the whole cycle once. OpenSpec's `onboard` does that with a model
+// narrating; here the CLI reads where the project stands and prints the
+// walk — what each step is for, what to run, what to tell the human, and
+// where to stop and ask — and the agent is the guide.
+//
+// Every "done" below is read from the tree, never stored: a tour that
+// remembers its own progress is a second place for a fact to go stale.
+
+const CODE_FILE = /\.(py|js|mjs|cjs|ts|tsx|jsx|go|rs|java|kt|rb|php|cs|swift|scala|c|cc|cpp|h|hpp|sh)$/i;
+const TODO_LINE = /\b(TODO|FIXME)\b[:\s-]*(.{0,90})/;
+const FILES_READ = 400;
+const FILE_BYTES = 200_000;
+export const CANDIDATES_SHOWN = 3;
+
+/**
+ * Where the project stands, read from the tree.
+ * @param {string} projectRoot
+ */
+export function onboardState(projectRoot) {
+  const dir = path.join(projectRoot, ".doctrina");
+  const installed = isDir(dir);
+  const specsDir = path.join(dir, "specs");
+  const specs = isDir(specsDir)
+    ? readdirSync(specsDir).filter((cap) => isFile(path.join(specsDir, cap, "spec.md"))).sort()
+    : [];
+  const intake = path.join(dir, "intake.md");
+  const intakePending = isFile(intake) && intakeStatus(read(intake)) === "pending";
+  const changesDir = path.join(dir, "changes");
+  const open = [];
+  if (isDir(changesDir)) {
+    for (const id of readdirSync(changesDir).filter((d) => /^\d{4}-/.test(d)).sort()) {
+      const proposal = path.join(changesDir, id, "proposal.md");
+      if (!isFile(proposal)) continue;
+      const tasksPath = path.join(changesDir, id, "tasks.md");
+      const p = isFile(tasksPath) ? checklistProgress(read(tasksPath)) : { total: 0, done: 0, placeholders: 0 };
+      open.push({
+        id,
+        title: parseChangeTitle(read(proposal)) ?? "",
+        planned: p.total > 0 && p.placeholders === 0,
+        ticked: p.total > 0 && p.placeholders === 0 && p.done === p.total,
+        tasks: { total: p.total, done: p.done },
+      });
+    }
+  }
+  const archiveDir = path.join(changesDir, "archive");
+  const archived = isDir(archiveDir)
+    ? readdirSync(archiveDir).filter((d) => /^\d{4}-\d{2}-\d{2}-\d{4}-/.test(d)).sort()
+    : [];
+  const hasCode = codeFiles(projectRoot, 1).length > 0;
+  return {
+    installed, specs, intakePending, hasCode, open,
+    closed: archived.length,
+    lastClosed: archived.length > 0 ? `.doctrina/changes/archive/${archived[archived.length - 1]}/` : null,
+  };
+}
+
+/** Tracked code files, as git lists them; none outside a repository. */
+function codeFiles(projectRoot, limit) {
+  const out = [];
+  for (const f of gitLines(projectRoot, ["ls-files", "--cached", "--others", "--exclude-standard"])) {
+    if (f.startsWith(".doctrina/") || /(^|\/)(node_modules|vendor|dist|build)\//.test(f) || !CODE_FILE.test(f)) continue;
+    out.push(f);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+/**
+ * Small, real first tasks read from this repository: a criterion with no
+ * proof yet, then a TODO somebody left in the code.
+ * @param {string} projectRoot
+ * @returns {{ kind: "criterion" | "todo", where: string, text: string, prompt: string }[]}
+ */
+export function firstTaskCandidates(projectRoot) {
+  const out = [];
+  for (const report of collect(projectRoot)) {
+    if (out.length >= CANDIDATES_SHOWN) break;
+    const criteria = parseAcceptanceCriteria(read(report.specPath));
+    for (const row of report.rows) {
+      if (out.length >= CANDIDATES_SHOWN) break;
+      const kind = "was" in row ? row.was : row.kind;
+      if (kind !== "bare" && kind !== "dangling") continue;
+      const body = String(criteria[row.n - 1]?.body ?? "").replace(/^\[[a-z]+\]\s*/i, "").replace(/\s+—\s+(verified|proven|evidenced|demonstrated) by .*$/i, "").trim();
+      if (body === "") continue;
+      out.push({
+        kind: /** @type {"criterion"} */ ("criterion"),
+        where: `${report.cap} #${row.n}`,
+        text: `${kind === "bare" ? "no proof cited" : "the proof it cites is missing"}: ${clip(body, 90)}`,
+        prompt: `prove ${report.cap} criterion ${row.n}: ${clip(body, 70)}`,
+      });
+    }
+  }
+  let read_ = 0;
+  for (const f of codeFiles(projectRoot, FILES_READ)) {
+    if (out.length >= CANDIDATES_SHOWN * 2) break;
+    const abs = path.join(projectRoot, f);
+    if (!isFile(abs)) continue;
+    let text;
+    try {
+      text = read(abs);
+    } catch {
+      continue;
+    }
+    if (text.length > FILE_BYTES || ++read_ > FILES_READ) continue;
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(TODO_LINE);
+      if (!m || m[2].trim().length < 8) continue;
+      const note = m[2].trim().replace(/\s*(\*\/|-->)\s*$/, "");
+      out.push({ kind: /** @type {"todo"} */ ("todo"), where: `${f}:${i + 1}`, text: `${m[1]} ${clip(note, 90)}`, prompt: clip(note, 70) });
+      break;
+    }
+  }
+  return out.slice(0, CANDIDATES_SHOWN * 2);
+}
+
+const clip = (/** @type {string} */ s, /** @type {number} */ n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+
+/**
+ * The walk: every step with whether the tree says it is done, what it is
+ * for, what to run and where to ask. `current` is the first one not done.
+ * @param {ReturnType<typeof onboardState>} state
+ */
+export function onboardSteps(state) {
+  const first = state.open[0] ?? null;
+  const id = first?.id ?? "<id>";
+  const ran = state.closed > 0;
+  const steps = [
+    { id: "install", title: "Install",
+      done: state.installed,
+      evidence: state.installed ? ".doctrina/ and AGENTS.md are here" : "",
+      say: "Doctrina keeps what the system should do in `.doctrina/` and tells every agent how to work in `AGENTS.md`; nothing else in the repository is touched.",
+      run: ["doctrina init"],
+      ask: "" },
+    { id: "describe", title: "Describe the project",
+      done: state.installed && state.specs.length > 0 && !state.intakePending,
+      evidence: state.specs.length > 0 ? `${state.specs.length} capability spec${state.specs.length === 1 ? "" : "s"} (${state.specs.slice(0, 4).join(", ")}${state.specs.length > 4 ? ", …" : ""})` : "",
+      say: "The specs are the current truth: one per capability, each requirement a testable sentence, each criterion citing its proof. Everything after this step changes them through a change.",
+      run: state.intakePending
+        ? ["doctrina intake    # the stored description is pending: execute the playbook it prints"]
+        : [state.hasCode ? "doctrina intake --from-code    # describe what the code does today" : 'doctrina intake --text "<what the project is, in a paragraph>"'],
+      ask: state.hasCode ? "what the code cannot tell: who uses it, and what must never break." : "for the project in a paragraph: who it is for and what it must do." },
+    { id: "first-task", title: "Pick a first task and open it",
+      done: state.open.length > 0 || ran,
+      evidence: first ? `${first.id} is open` : (ran ? "a change was opened and closed" : ""),
+      say: "A request that changes behaviour becomes a change before code is edited; the CLI scaffolds it and prints the playbook. Small and real beats a toy: the cycle is learned on work that matters.",
+      run: ['doctrina work "<the task>"'],
+      ask: "to choose one of the candidates, or to name a small task of their own — something done in under an hour." },
+    { id: "plan", title: "Write the delta and the tasks",
+      done: ran || state.open.some((ch) => ch.planned),
+      evidence: first?.planned ? `${first.id} has ${first.tasks.total} task${first.tasks.total === 1 ? "" : "s"} written` : "",
+      say: "The delta is the sentence the spec gains or loses; the tasks are how the code gets there. Nothing is implemented yet — this is the moment the human reads and corrects.",
+      run: [`doctrina work --resume ${id}    # the playbook`, `doctrina change check ${id}    # would the close pass?`],
+      ask: "whether the requirement you wrote is what they meant — show it to them before any code.",
+      askAfter: true },
+    { id: "implement", title: "Implement and prove",
+      done: ran || state.open.some((ch) => ch.ticked),
+      evidence: first?.ticked ? `every task of ${first.id} is ticked` : "",
+      say: "Each task is implemented and ticked, and each new criterion cites the test that proves it: `coverage` reads that citation, not the claim.",
+      run: [`doctrina change tick ${id} <n>`, "doctrina verify"],
+      ask: "" },
+    { id: "close", title: "Close",
+      done: ran,
+      evidence: ran ? `${state.closed} change${state.closed === 1 ? "" : "s"} closed — the last at ${state.lastClosed}` : "",
+      say: "One command merges the delta into the spec, runs every gate and archives the change. If it refuses, the change is not done — it names what is missing.",
+      run: [`doctrina close ${id}`],
+      ask: "" },
+  ];
+  const at = steps.findIndex((s) => !s.done);
+  return { steps, current: at < 0 ? null : steps[at].id };
+}
+
+/** What a project that already ran the cycle shows a newcomer. */
+export function tourLines(state) {
+  const cap = state.specs[0] ?? "<capability>";
+  return [
+    "doctrina prime                 # the state of the project in one read — every session starts here",
+    `doctrina why ${cap}${" ".repeat(Math.max(1, 17 - cap.length))}# why a capability exists: intent, proof, decisions, history`,
+    ...(state.lastClosed ? [`${state.lastClosed}proposal.md    # a finished change, start to end`] : []),
+    'doctrina work "<request>"      # the next request — it says by itself when no change is needed',
+    "doctrina hooks install         # once per clone: the commit hook and the merge drivers",
+  ];
+}

package/src/lib/preset.js

@@ -0,0 +1,177 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read, walk, write } from "./fs-ops.js";
+import { configPath } from "./config.js";
+
+// A PRESET: THE ORGANISATION'S HOUSE, IN A FOLDER (change 0253).
+//
+// Every project of one company starts from the same things — its language,
+// the rules no repository may break, the decisions that bind all of them,
+// its templates, the checks its pipeline runs — and each `doctrina init`
+// started from the CLI's defaults, so the house style was re-typed, or
+// forgotten, per repository. A preset is a folder (a repository the team
+// clones, a submodule, a path on a shared drive — the CLI makes no network
+// call) that `init --preset` and `upgrade --preset` lay over a project:
+//
+//   preset.json     { "name", "description", "config": { … } }
+//   templates/**    → .doctrina/templates/**   (per-file overrides, ADR 0019)
+//   decisions/*.md  → .doctrina/decisions/
+//   skills/*.md     → .doctrina/skills/
+//   verify.json     → .doctrina/verify.json    (only when the project has none)
+//
+// ADDITIVE, like every scaffold update: a file the project already has is
+// kept, a config key it already declares is kept, and the plan says so.
+
+export const PRESET_FILE = "preset.json";
+const NAME = /^[a-z0-9][a-z0-9-]*$/;
+const CONFIG_KEYS = ["language", "context_budget", "rules", "surface"];
+const FOLDERS = [
+  { from: "templates", to: ".doctrina/templates", only: null },
+  { from: "decisions", to: ".doctrina/decisions", only: /\.md$/ },
+  { from: "skills", to: ".doctrina/skills", only: /\.md$/ },
+];
+
+/**
+ * Read a preset folder. Throws an Error whose message says what is wrong
+ * with it — the caller prints it and exits 2.
+ * @param {string} dir
+ * @returns {{ dir: string, name: string, description: string, config: Record<string, any> }}
+ */
+export function readPreset(dir) {
+  const root = path.resolve(dir);
+  if (!isDir(root)) throw new Error(`preset ${dir} is not a folder`);
+  const file = path.join(root, PRESET_FILE);
+  if (!isFile(file)) throw new Error(`${dir} has no ${PRESET_FILE} — a preset is a folder with one: { "name": "acme", "config": { … } }`);
+  let data;
+  try {
+    data = JSON.parse(read(file));
+  } catch (err) {
+    throw new Error(`${path.join(dir, PRESET_FILE)} is not valid JSON: ${/** @type {Error} */ (err).message}`);
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data)) throw new Error(`${PRESET_FILE} must be an object`);
+  if (typeof data.name !== "string" || !NAME.test(data.name)) throw new Error(`${PRESET_FILE} needs a "name" of lowercase letters, digits and hyphens`);
+  const config = data.config ?? {};
+  if (typeof config !== "object" || Array.isArray(config)) throw new Error(`${PRESET_FILE}: "config" must be an object`);
+  const unknown = Object.keys(config).filter((k) => !CONFIG_KEYS.includes(k));
+  if (unknown.length > 0) throw new Error(`${PRESET_FILE}: config key${unknown.length === 1 ? "" : "s"} ${unknown.map((k) => `"${k}"`).join(", ")} unknown — a preset sets ${CONFIG_KEYS.join(", ")}`);
+  return { dir: root, name: data.name, description: typeof data.description === "string" ? data.description : "", config };
+}
+
+const posix = (/** @type {string} */ p) => p.split(path.sep).join("/");
+const adrNumber = (/** @type {string} */ name) => name.match(/^(\d{4})-/)?.[1] ?? null;
+
+/**
+ * What laying the preset over the project would do. Reads only.
+ * @returns {{
+ *   files: { rel: string, from: string, action: "copy" | "same" | "kept", note: string }[],
+ *   config: { key: string, value: any, action: "set" | "kept" | "same" }[],
+ *   verify: string[],
+ * }}
+ */
+export function planPreset(projectRoot, preset) {
+  /** @type {{ rel: string, from: string, action: "copy" | "same" | "kept", note: string }[]} */
+  const files = [];
+  const taken = new Map();
+  const decisions = path.join(projectRoot, ".doctrina", "decisions");
+  if (isDir(decisions)) {
+    for (const f of readdirSync(decisions)) {
+      const n = adrNumber(f);
+      if (n) taken.set(n, f);
+    }
+  }
+  const add = (/** @type {string} */ from, /** @type {string} */ rel) => {
+    const dest = path.join(projectRoot, rel);
+    if (isFile(dest)) {
+      files.push({ rel, from, action: read(dest) === read(from) ? "same" : "kept", note: "the project has its own" });
+      return;
+    }
+    // An ADR's number is its identity: a preset decision whose number the
+    // project already gave to another one is not renumbered behind its back.
+    const n = rel.startsWith(".doctrina/decisions/") ? adrNumber(path.basename(rel)) : null;
+    if (n && taken.has(n)) {
+      files.push({ rel, from, action: "kept", note: `ADR number ${n} is ${taken.get(n)} here — copy it under a free number by hand` });
+      return;
+    }
+    files.push({ rel, from, action: "copy", note: "" });
+  };
+  for (const folder of FOLDERS) {
+    const base = path.join(preset.dir, folder.from);
+    for (const from of walk(base)) {
+      if (folder.only && !folder.only.test(from)) continue;
+      add(from, `${folder.to}/${posix(path.relative(base, from))}`);
+    }
+  }
+  /** @type {string[]} */
+  let verify = [];
+  const presetVerify = path.join(preset.dir, "verify.json");
+  if (isFile(presetVerify)) {
+    add(presetVerify, ".doctrina/verify.json");
+    try {
+      verify = (JSON.parse(read(presetVerify)).checks ?? []).map((/** @type {{ run?: string }} */ ch) => String(ch.run ?? "")).filter(Boolean);
+    } catch { /* an unreadable verify.json is reported by `doctrina verify` once copied */ }
+  }
+
+  /** @type {Record<string, any>} */
+  let current = {};
+  try {
+    current = JSON.parse(read(configPath(projectRoot)));
+  } catch { /* no config.json yet, or an unreadable one: nothing is declared */ }
+  const config = Object.entries(preset.config).map(([key, value]) => ({
+    key, value,
+    action: /** @type {"set" | "kept" | "same"} */ (!(key in current) ? "set"
+      : JSON.stringify(current[key]) === JSON.stringify(value) ? "same" : "kept"),
+  }));
+  return { files, config, verify };
+}
+
+/** How many things the plan would write. */
+export function presetPending(plan) {
+  return plan.files.filter((f) => f.action === "copy").length + plan.config.filter((c) => c.action === "set").length;
+}
+
+/** Write what the plan calls for. The caller re-derives the index. */
+export function applyPreset(projectRoot, preset, plan) {
+  for (const f of plan.files) {
+    if (f.action === "copy") write(path.join(projectRoot, f.rel), read(f.from));
+  }
+  const file = configPath(projectRoot);
+  /** @type {Record<string, any>} */
+  let current = {};
+  try {
+    current = JSON.parse(read(file));
+  } catch { /* written whole below */ }
+  /** @type {Record<string, any>} */
+  const next = { ...current };
+  for (const c of plan.config) if (c.action === "set") next[c.key] = c.value;
+  next.preset = preset.name;
+  write(file, JSON.stringify(next, null, 2) + "\n", { force: true });
+}
+
+/**
+ * The plan as lines a person reads: what is copied, what is kept and why,
+ * and — said every time — the commands a preset's verify.json would run.
+ * @param {boolean} written
+ * @returns {string[]}
+ */
+export function describePreset(preset, plan, written) {
+  const verb = written ? "copied    " : "would copy";
+  const lines = [`preset ${preset.name}${preset.description ? ` — ${preset.description}` : ""}`];
+  for (const f of plan.files) {
+    if (f.action === "copy") lines.push(`  ${verb} ${f.rel}`);
+    else if (f.action === "kept") lines.push(`  kept       ${f.rel} — ${f.note}`);
+  }
+  for (const c of plan.config) {
+    const shown = Array.isArray(c.value) ? `${c.value.length} rule${c.value.length === 1 ? "" : "s"}` : JSON.stringify(c.value);
+    if (c.action === "set") lines.push(`  ${written ? "set       " : "would set "} config ${c.key} = ${shown}`);
+    else if (c.action === "kept") lines.push(`  kept       config ${c.key} — the project declares another value`);
+  }
+  const copiesVerify = plan.files.some((f) => f.rel === ".doctrina/verify.json" && f.action === "copy");
+  if (copiesVerify && plan.verify.length > 0) {
+    lines.push(`  note       the preset's verify.json declares what \`doctrina verify\` RUNS on this machine: ${plan.verify.map((r) => `\`${r}\``).join(", ")} — read it before running the gate`);
+  }
+  const same = plan.files.filter((f) => f.action === "same").length;
+  if (same > 0) lines.push(`  same       ${same} file${same === 1 ? "" : "s"} already as the preset has ${same === 1 ? "it" : "them"}`);
+  if (presetPending(plan) === 0) lines.push("  nothing to add — the project already carries the preset");
+  return lines;
+}

package/src/lib/prompt.js

@@ -25,7 +25,7 @@ export async function ask(question, { defaultValue = "" } = {}) {
 // Ask for consent. Off a terminal there is nobody to ask, so the answer is
 // `whenNonInteractive` — which callers set to false for destructive
 // operations: silence is not consent.
-export async function confirm(question, { defaultYes = false, whenNonInteractive = null } = {}) {
+export async function confirm(question, { defaultYes = false, whenNonInteractive = /** @type {boolean | null} */ (null) } = {}) {
   if (!isInteractive()) {
     return whenNonInteractive === null ? defaultYes : whenNonInteractive;
   }

package/src/lib/properties.js

@@ -0,0 +1,149 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read } from "./fs-ops.js";
+import { parseAcceptanceCriteria } from "./criteria.js";
+
+// A REQUIREMENT THAT IS AN INVARIANT ASKS FOR A PROPERTY (change 0254).
+//
+// "The system shall never return a code already in use" is a claim about
+// EVERY input, and the evidence a criterion cited for it was an example
+// test: three inputs somebody thought of. Coverage called that proven. A
+// property-based test generates the inputs — hundreds of them, the ones
+// nobody thought of — which is the kind of proof a universal claim wants.
+//
+// Kiro derives such tests from EARS requirements with a model. The CLI has
+// none and does not pretend to: it does the two deterministic halves. It
+// says WHICH requirements read as invariants (`coverage --properties`), and
+// it refuses to count a criterion marked `[property]` as proven unless the
+// test it cites really is a property-based one. Writing the property is the
+// agent's work, as writing the test always was.
+
+/** Marks a criterion whose proof must generate its inputs. */
+export const PROPERTY_MARKER = /^property\b/;
+
+/** What a property-based test looks like, per library. */
+const LIBRARIES = [
+  { name: "Hypothesis", re: /@given\s*\(|\bfrom\s+hypothesis\b|\bimport\s+hypothesis\b/ },
+  { name: "fast-check", re: /\bfc\.(assert|property|asyncProperty)\s*\(|["']fast-check["']/ },
+  { name: "jqwik", re: /@Property\b|\bnet\.jqwik\b/ },
+  { name: "proptest", re: /\bproptest!\s*\{/ },
+  { name: "quickcheck", re: /\bquickcheck!\s*\{|#\[quickcheck\]|\bquickCheck\b/ },
+  { name: "rapid", re: /\brapid\.Check\s*\(|\bquick\.Check\s*\(/ },
+  { name: "FsCheck", re: /\bProp\.ForAll\b|\[Property\b/ },
+  { name: "ScalaCheck", re: /\bforAll\s*[({]/ },
+];
+
+/** The property library a test file uses, or null when it generates nothing. */
+export function propertyLibraryIn(text) {
+  return LIBRARIES.find((lib) => lib.re.test(String(text)))?.name ?? null;
+}
+
+// The shapes a universal claim takes in a requirement, with the property
+// each one suggests. English and Portuguese, as the specs are.
+const SHAPES = [
+  { id: "round-trip",
+    re: /\b(round[- ]trip|and back\b|restor\w+ (?:the |its )?(?:original|same|previous)|revers(?:ible|ibly|es)\b|decod\w+|deserializ\w+|ida e volta|restaura\w* (?:o |a )?(?:original|mesm[oa]|anterior))/i,
+    property: "for any input x, undoing what was done to x gives x back" },
+  { id: "idempotence",
+    re: /\b(idempoten\w+|twice|a second time|more than once|applied again|run again|duas vezes|de novo|mais de uma vez|outra vez)\b/i,
+    property: "for any input x, doing it twice leaves what doing it once left" },
+  { id: "bound",
+    re: /\b(at most|at least (?!one\b)|no more than|no fewer than|not exceed|never exceed|within (?:\d|(?:\S+ ){0,3}(?:budget|limit|threshold|ratio|bound|quota|window|deadline)\b)|between \d|no máximo|pelo menos (?!um\b|uma\b)|no mínimo|não excede|entre \d)/i,
+    property: "for any input, the result stays inside the stated bound" },
+  { id: "uniqueness",
+    re: /(?<![\w-])(unique|distinct(?!ive| from)|no two|never the same|(?:not|never) .{0,40}already (?:in use|used|taken|issued|exist\w*|registered)|único|única|distint\w+|nunca .{0,20}repet\w+|já (?:em uso|usad\w+|exist\w+))/i,
+    property: "for any sequence of inputs, no two results collide" },
+  { id: "order",
+    re: /\b(sorted|ordered|in order(?! to\b)|ascending|descending|monoton\w+|ordenad\w+|em ordem|crescente|decrescente)\b/i,
+    property: "for any input, the output is in the stated order" },
+  { id: "invariant",
+    re: /\b(always|never|for every|for any|for all|whatever|sempre|nunca|para todo|para toda|para qualquer|qualquer que seja)\b/i,
+    property: "for any input, the stated condition holds" },
+];
+
+/** Every requirement bullet under `## Requirements`, with its section and ordinal. */
+export function requirementsOf(specText) {
+  const out = [];
+  let inside = false;
+  let section = null;
+  let n = 0;
+  let cur = null;
+  for (const line of String(specText).split(/\r?\n/)) {
+    if (/^##\s+/.test(line) && !/^###/.test(line)) {
+      inside = /^##\s+Requirements\b/i.test(line);
+      section = null;
+      cur = null;
+      continue;
+    }
+    if (!inside) continue;
+    const h = line.match(/^###\s+(\S+)/);
+    if (h) {
+      section = h[1].toLowerCase().replace(/[^a-z-]/g, "").split("-")[0];
+      n = 0;
+      cur = null;
+      continue;
+    }
+    if (section && /^-\s+\S/.test(line)) {
+      n += 1;
+      cur = { section, n, text: line.replace(/^-\s+/, "").trim() };
+      out.push(cur);
+    } else if (cur && /^\s+\S/.test(line)) {
+      cur.text += " " + line.trim();
+    } else if (line.trim() === "") {
+      cur = null;
+    }
+  }
+  return out;
+}
+
+/** The first shape a requirement's text takes, or null when it states no universal claim. */
+export function propertyShape(text) {
+  const prose = String(text).replace(/`[^`]*`/g, "");
+  return SHAPES.find((s) => s.re.test(prose)) ?? null;
+}
+
+/** The property library this project's manifests point at, with how sure that is. */
+export function projectPropertyLibrary(projectRoot) {
+  const text = (/** @type {string} */ rel) => (isFile(path.join(projectRoot, rel)) ? read(path.join(projectRoot, rel)) : "");
+  const py = text("pyproject.toml") + text("requirements.txt") + text("requirements-dev.txt") + text("setup.cfg") + text("Pipfile");
+  const js = text("package.json");
+  if (/\bhypothesis\b/i.test(py)) return { name: "Hypothesis", declared: true };
+  if (/"fast-check"/.test(js)) return { name: "fast-check", declared: true };
+  if (py.trim() !== "") return { name: "Hypothesis", declared: false };
+  if (js.trim() !== "") return { name: "fast-check", declared: false };
+  if (isFile(path.join(projectRoot, "pom.xml")) || isFile(path.join(projectRoot, "build.gradle")) || isFile(path.join(projectRoot, "build.gradle.kts"))) return { name: "jqwik", declared: false };
+  if (isFile(path.join(projectRoot, "Cargo.toml"))) return { name: "proptest", declared: false };
+  if (isFile(path.join(projectRoot, "go.mod"))) return { name: "rapid", declared: false };
+  return null;
+}
+
+/**
+ * Per capability: the requirements that read as invariants, and how many of
+ * its criteria are already properties.
+ * @param {string} projectRoot
+ * @param {{ only?: Set<string> | null }} [opts]
+ */
+export function propertyCandidates(projectRoot, { only = /** @type {Set<string> | null} */ (null) } = {}) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const out = [];
+  if (!isDir(specsDir)) return out;
+  for (const cap of readdirSync(specsDir).sort()) {
+    if (only && !only.has(cap)) continue;
+    const file = path.join(specsDir, cap, "spec.md");
+    if (!isFile(file)) continue;
+    const text = read(file);
+    const candidates = [];
+    for (const req of requirementsOf(text)) {
+      const shape = propertyShape(req.text);
+      if (shape) candidates.push({ ref: `${req.section} ${req.n}`, text: req.text, shape: shape.id, property: shape.property });
+    }
+    // The specific shapes first: "at most", "twice", "and back" name the
+    // property to write; a bare "always" only says that there is one.
+    const rank = (/** @type {string} */ id) => SHAPES.findIndex((s) => s.id === id);
+    candidates.sort((a, b) => rank(a.shape) - rank(b.shape));
+    const properties = parseAcceptanceCriteria(text).filter((row) => row.marker !== null && PROPERTY_MARKER.test(row.marker)).length;
+    out.push({ cap, candidates, properties });
+  }
+  return out;
+}

package/src/lib/runtime.js

@@ -203,7 +203,7 @@ export function readWorkflowEnv(text) {
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
     if (!line.trim() || /^\s*#/.test(line)) continue;
-    const indent = line.match(/^\s*/)[0].length;
+    const indent = (line.match(/^\s*/) ?? [""])[0].length;
 
     if (/^jobs:\s*$/.test(line)) {
       sawJobs = true;
@@ -681,17 +681,29 @@ function compileGlob(glob) {
  */
 export function filesMatching(projectRoot, glob) {
   const re = globToRegExp(glob);
+  const text = String(glob);
+  const segments = text.split("/");
   // Walk from the deepest literal directory prefix so a narrow glob never
-  // costs a full-tree walk.
-  const prefix = String(glob).split("/").filter((s) => !/[*?]/.test(s));
+  // costs a full-tree walk. The prefix ends at the first segment that is a
+  // pattern: taking every literal segment, wherever it stood, let
+  // `a/*/b/c.js` start from `a/b` when that directory existed.
   let base = projectRoot;
-  for (const seg of prefix) {
+  let consumed = 0;
+  for (const seg of segments) {
+    if (/[*?{]/.test(seg)) break;
     const next = path.join(base, seg);
-    if (isDir(next)) base = next;
-    else break;
+    if (!isDir(next)) break;
+    base = next;
+    consumed += 1;
   }
   if (!isDir(base)) return [];
-  return walk(base).filter((f) => re.test(relPath(projectRoot, f).replaceAll("\\", "/")));
+  // ...and no deeper than the pattern can reach (change 0249). A pattern
+  // with no `**` names a fixed number of levels; `tsconfig.json` names one.
+  // Without the bound, each root-level file a spec declared walked the whole
+  // repository — `node_modules` and `.git` included — to find it.
+  const spans = text.endsWith("/") || segments.includes("**") || /\{[^}]*\/[^}]*\}/.test(text);
+  const depth = spans ? Infinity : Math.max(1, segments.length - consumed);
+  return walk(base, { depth }).filter((f) => re.test(relPath(projectRoot, f).replaceAll("\\", "/")));
 }
 
 // ---------------------------------------------------------------------------

package/src/lib/scan.js

@@ -24,6 +24,7 @@ export function listHeader(text, name) {
   return getHeader(text, name);
 }
 
+/** @returns {string[]} */
 export function parseDependsOn(text) {
   const raw = specHeader(text, "Depends on");
   if (!raw || /^n\/a\b/i.test(raw.trim()) || raw.trim() === "—") return [];
@@ -77,6 +78,7 @@ function dirEntries(dir) {
 // The capabilities an ADR governs, from its optional "Scope:" header
 // (M4). Returns [] when absent, "n/a", or "—" — an unscoped ADR is global
 // and belongs in every pack, which is what keeps this backward compatible.
+/** @returns {string[]} */
 export function parseAdrScope(text) {
   const raw = listHeader(text, "Scope");
   if (!raw || /^n\/a\b/i.test(raw.trim()) || raw.trim() === "—") return [];
@@ -175,7 +177,7 @@ export function changeEntry(proposal, id, prev, date) {
 // carried the lane: an archived change lost the lane it was born in, so the
 // report's "Lanes" section counted the whole history as unknown (change
 // 0192), which is the question change 0042 recorded the lane to answer.
-export function archivedChangeEntry(proposal, { id, archiveName, applied, specsAffected, prev = null, title = undefined }) {
+export function archivedChangeEntry(proposal, { id, archiveName, applied, specsAffected, prev = /** @type {any} */ (null), title = /** @type {string | null | undefined} */ (undefined) }) {
   return {
     id,
     title: (title === undefined ? parseChangeTitle(proposal) : title) ?? prev?.title ?? id,
@@ -213,12 +215,12 @@ export function deriveIndex(projectRoot, current) {
         version: "0.1.0",
         last_updated: date,
       },
-      specs: [],
-      decisions: [],
-      changes: [],
-      changes_archive: [],
-      skills: [],
-      contracts: [],
+      specs: /** @type {any[]} */ ([]),
+      decisions: /** @type {any[]} */ ([]),
+      changes: /** @type {any[]} */ ([]),
+      changes_archive: /** @type {any[]} */ ([]),
+      skills: /** @type {any[]} */ ([]),
+      contracts: /** @type {any[]} */ ([]),
     },
   };
 
@@ -533,7 +535,10 @@ export function collectStagedIndexDrift(projectRoot) {
   const nothing = { ok: true, applicable: false, missing: [], unindexed: [], reason: null };
   if (!isRepo(projectRoot)) return { ...nothing, reason: "not a git repository" };
 
-  const blob = git(projectRoot, ["show", ":.doctrina/index.json"]);
+  // `:./` reads the path from the current directory. A bare `:.doctrina/…`
+  // is read from the top of the repository, so for a project in a subfolder
+  // the check answered "no staged index" for every commit (change 0250).
+  const blob = git(projectRoot, ["show", ":./.doctrina/index.json"]);
   if (blob.state !== GIT_STATE.OK || !blob.stdout.trim()) {
     // Not staged at all — this commit does not carry an index, so it cannot
     // carry one that disagrees with itself.

package/src/lib/spec-ops.js

@@ -50,7 +50,7 @@ const HEADER_RE = (name) =>
 // see ADR 0007"): only the WORD is checked.
 export const STATUS_VALUES = ["draft", "active", "deprecated"];
 export const IMPLEMENTATION_VALUES = ["planned", "partial", "implemented", "verified"];
-export const CRITERION_MARKS = ["verified", "unverified", "orchestration"];
+export const CRITERION_MARKS = ["verified", "unverified", "orchestration", "property"];
 
 /** The state word of a header/mark value: the first token, note stripped. */
 export function stateWord(value) {
@@ -440,7 +440,7 @@ function locateRequirements(text) {
     if (h) {
       if (current) current.endIndex = i;
       const token = SECTIONS[h[1].toLowerCase().replace(/[^a-z-]/g, "")] ?? null;
-      current = { headingIndex: i, endIndex: lines.length, bullets: [] };
+      current = { headingIndex: i, endIndex: lines.length, bullets: /** @type {number[]} */ ([]) };
       if (token) sections[token] = current;
       continue;
     }