doctrina-cli 0.15.1 → 0.17.0

package/src/lib/commands.js

@@ -16,11 +16,11 @@ export const COMMAND_NAMES = [
   // authoring
   "spec", "change", "contract", "decision", "skill", "intent", "adapter",
   // read / orient
-  "prime", "context", "show", "search", "status", "next", "why", "handoff", "constitution",
+  "prime", "context", "show", "search", "status", "next", "why", "handoff",
   // gates
   "analyze", "clarify", "validate", "coverage", "trace", "review", "verify", "close", "doctor",
   // maintenance
-  "templates", "hooks", "index", "watch", "metrics", "report", "completion", "upgrade",
+  "templates", "hooks", "index", "watch", "metrics", "report", "completion", "upgrade", "ci",
 ];
 
 // The full operation surface — every `doctrina <command> [<subcommand>]` a
@@ -46,7 +46,6 @@ export const OPERATIONS = [
   ["change archive", "Archive an applied change (batch ids ok)"],
   ["change check", "Pre-close dry-run: everything close would refuse, listed first"],
   ["change tick", "List/tick the unchecked boxes (tasks + verification; --all)"],
-  ["change diff", "Preview spec deltas (line diff for MODIFIED)"],
   ["change abandon", "Discard an open change cleanly (recorded in the ledger)"],
   ["contract new", "Own the integration surface (ports, env, interfaces)"],
   ["contract list", "List contracts with status and last-updated date"],
@@ -82,7 +81,6 @@ export const OPERATIONS = [
   ["status", "One-glance project health dashboard"],
   ["why", "Explain provenance: a capability's chain, or an anchor's (SC1)"],
   ["handoff", "Markdown handoff note: open work, task state, resume command"],
-  ["constitution", "Print the standing rules: accepted ADRs + product non-goals"],
   ["templates list", "List the templates shipped by the installed CLI"],
   ["templates check", "Compare the project against the recommended template shape"],
   ["templates update", "Additive fixer for check findings (preview; --write applies)"],
@@ -93,6 +91,7 @@ export const OPERATIONS = [
   ["metrics", "Local git-derived adoption metrics (no network)"],
   ["report", "Markdown digest for a period: changes, gates, git summary"],
   ["completion", "Print bash/zsh/pwsh completions (generated from the catalog)"],
+  ["ci", "Emit the CI pipeline for the declared gate sequence (--emit github)"],
   ["upgrade", "Bring an existing project up to the installed CLI (--write applies)"],
 ];
 
@@ -118,20 +117,19 @@ export const COMMAND_META = {
   intake:       { moment: "Bootstrap",  when: "you have a full project description and no specs yet", purpose: "store the intent and print the bootstrap playbook" },
   adapter:      { moment: "Bootstrap",  when: "adding or removing an agent's pointer files", purpose: "install/remove agent adapters (additive)" },
 
-  prime:        { moment: "Orient",     when: "at the START of every session", purpose: "gates, standing rules, and open work in one read" },
+  prime:        { moment: "Orient",     when: "at the START of every session", purpose: "gates, open work and next steps in one read (--rules for the full standing rules)" },
   status:       { moment: "Orient",     when: "you need the health of the tree at a glance", purpose: "index, coverage, trace, and artifact counts" },
   next:         { moment: "Orient",     when: "you finished something and do not know what follows", purpose: "the recommended next workflow action" },
   context:      { moment: "Orient",     when: "before working on any task, to load the right files", purpose: "the read pack, assembled to fit a token budget" },
   show:         { moment: "Orient",     when: "you need one requirement, criterion, or ADR, not a file", purpose: "point-read a single artifact by reference" },
   search:       { moment: "Orient",     when: "you do not know which artifact mentions a term", purpose: "search the artifact tree, grouped by category" },
   why:          { moment: "Orient",     when: "you need to justify or trace a capability's existence", purpose: "provenance: intent, proof, ADRs, and history" },
-  constitution: { moment: "Orient",     when: "you need the standing rules before deciding something", purpose: "accepted ADRs and product non-goals" },
   handoff:      { moment: "Orient",     when: "BEFORE compaction or handing over to another session", purpose: "a resume note: open work, task state, next command" },
 
   triage:       { moment: "Change",     when: "a request arrives — BEFORE scaffolding, especially if it smells like an incident", purpose: "classify the lane (product/runtime/chore) and check the declared runtime surface" },
   work:         { moment: "Change",     when: "a request arrives that changes behaviour (triage says PRODUCT)", purpose: "scaffold a change and print the playbook to execute" },
   spec:         { moment: "Change",     when: "a capability needs creating or its headers advancing", purpose: "create, list, and edit capability specs" },
-  change:       { moment: "Change",     when: "driving a change through its lifecycle by hand", purpose: "new / apply / archive / check / tick / diff / abandon" },
+  change:       { moment: "Change",     when: "driving a change through its lifecycle by hand", purpose: "drive a change by hand — check --verbose previews every delta" },
   decision:     { moment: "Change",     when: "the change decides something a later session must not relitigate", purpose: "record, accept, land, scope, and supersede ADRs" },
   contract:     { moment: "Change",     when: "the change touches ports, env vars, or public endpoints", purpose: "own and verify the integration surface" },
   intent:       { moment: "Change",     when: "new product intent appears after the intake", purpose: "append and list product intent anchors" },
@@ -147,7 +145,7 @@ export const COMMAND_META = {
   close:        { moment: "Gate",       when: "a change is implemented and ready to finish", purpose: "the whole closing sequence in one attested pass" },
   doctor:       { moment: "Gate",       when: "something looks wrong and you do not know which gate to ask", purpose: "aggregate diagnostic with per-finding remedies" },
 
-  templates:    { moment: "Maintain",   when: "after upgrading the CLI, or to customise a scaffold", purpose: "inspect, check, and refresh the template shape" },
+  templates:    { moment: "Maintain",   when: "customising a scaffold, to see which template file wins", purpose: "where each shipped template resolves from" },
   upgrade:      { moment: "Maintain",   when: "you just updated the doctrina-cli package", purpose: "bring this project up to the installed CLI" },
   index:        { moment: "Maintain",   when: "the index drifted from the tree", purpose: "regenerate index.json from the artifacts on disk" },
   hooks:        { moment: "Maintain",   when: "setting up a repo so drift cannot be committed", purpose: "install the pre-commit gate" },
@@ -155,6 +153,7 @@ export const COMMAND_META = {
   metrics:      { moment: "Maintain",   when: "reporting adoption over a period", purpose: "local git-derived adoption metrics" },
   report:       { moment: "Maintain",   when: "summarising a period for a human", purpose: "a Markdown digest of changes, gates, and git" },
   completion:   { moment: "Maintain",   when: "setting up a human's shell", purpose: "print shell completions from the catalog" },
+  ci:           { moment: "Maintain",   when: "the declared gate sequence changed and CI must follow", purpose: "emit the CI pipeline from the gate declaration" },
 };
 
 // The order moments appear in the generated block.
@@ -162,10 +161,49 @@ export const MOMENTS = ["Bootstrap", "Orient", "Change", "Gate", "Maintain"];
 
 // The Commands block of `doctrina --help`, generated from OPERATIONS so the
 // printed surface can never omit an operation the catalog knows about.
+//
+// Grouped by the MOMENT an operation is reached for, in the same order as
+// the AGENTS.md block, and opened by the two lines a newcomer needs: a flat
+// list of sixty operations, deprecated ones mixed in, answered "where do I
+// start?" with the whole catalog (change 0174). Deprecated operations stay
+// listed — someone types those names — but last, each pointing at its
+// replacement.
 export function surfaceHelp() {
-  return OPERATIONS.map(([op, summary]) => `  ${op.padEnd(21)}${summary}`).join("\n");
+  // A name longer than the column puts its text on the next line, aligned,
+  // so the summaries stay one scannable column at 80 characters.
+  const line = (op, text) => op.length < 20
+    ? `  ${op.padEnd(21)}${text}`
+    : `  ${op}\n  ${"".padEnd(21)}${text}`;
+  const out = [
+    "Start here:",
+    line("doctrina init", "set up this repository (asks for a one-line description)"),
+    line("doctrina next", "what to do now — your agent runs the rest from AGENTS.md"),
+  ];
+  // One line per COMMAND, its subcommands joined: the summary a newcomer
+  // scans; `doctrina <command> --help` has each subcommand's detail.
+  const live = OPERATIONS.filter(([op]) => !DEPRECATED[op]);
+  for (const moment of MOMENTS) {
+    const cmds = [...new Set(live.map(([op]) => op.split(" ")[0]))]
+      .filter((cmd) => COMMAND_META[cmd]?.moment === moment);
+    if (cmds.length === 0) continue;
+    out.push("", `${moment}:`);
+    for (const cmd of cmds) {
+      const ops = live.filter(([op]) => op.split(" ")[0] === cmd);
+      const subs = ops.map(([op]) => op.split(" ")[1]).filter(Boolean);
+      const text = ops.length === 1 ? ops[0][1] : capitalise(COMMAND_META[cmd].purpose);
+      out.push(line(subs.length > 0 ? `${cmd} ${subs.join("|")}` : cmd, text));
+    }
+  }
+  const old = OPERATIONS.filter(([op]) => DEPRECATED[op]);
+  if (old.length > 0) {
+    out.push("", "Deprecated (still run, with a notice on stderr):",
+      ...old.map(([op]) => line(op, `→ ${DEPRECATED[op].use}`)));
+  }
+  return out.join("\n");
 }
 
+const capitalise = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+
 // ---------------------------------------------------------------------------
 // The CLI-owned AGENTS.md command-surface block (operator review 2026-07-19,
 // meta-conclusion): for an agent, AGENTS.md IS the discovery interface — it
@@ -195,10 +233,78 @@ const SURFACE_HINTS = {
   clarify: "--all (--lang pt|en)",
   close: "<id...>",
   upgrade: "--write",
+  ci: "--emit github",
   prime: "(session start)",
   handoff: "(before compaction/handover)",
 };
 
+// ---------------------------------------------------------------------------
+// Deprecations (change 0049).
+//
+// The surface has a hard 40-line budget precisely so that adding a command
+// forces the question "what comes off?" — and for two releases the answer was
+// "nothing", while the budget was met by compressing a whole moment onto one
+// line (audit finding F23). These are the first two removals, and both are
+// MERGES: the surviving command already does everything the retired one did,
+// which is why they can go without waiting for usage evidence. Usage counts
+// can tell you a command is unloved; only redundancy can tell you it is
+// unnecessary, and an unloved command that does something nothing else does
+// has to stay.
+//
+// A deprecated operation keeps working, warns once on the way through, and
+// leaves the surface block — an agent should not reach for it, and the block
+// is the list of things to reach for. Removal is a later, separate change.
+export const DEPRECATED = Object.freeze({
+  "analyze": {
+    since: "0.17.0",
+    use: "doctrina change check",
+    why: "check reports the same structural checks first, then the ops dry-run and the archive-gate preview — it answers 'would the close pass?', so it also exits 1 while a Verification box is open; `change apply` still refuses what analyze refused",
+  },
+  "report": {
+    since: "0.17.0",
+    use: "doctrina status --view report",
+    why: "status renders the same digest from the same collector; --agent-changelog is status --view agent-changelog",
+  },
+  "skill sync": {
+    since: "0.17.0",
+    use: "doctrina index rebuild",
+    why: "the rebuild registers every skill and mirrors its description, keeping a written one over a scaffold placeholder",
+  },
+  "templates check": {
+    since: "0.17.0",
+    use: "doctrina upgrade",
+    why: "the upgrade preview reports every template finding, each with its fix, and exits 1 while one is left",
+  },
+  "templates update": {
+    since: "0.17.0",
+    use: "doctrina upgrade --write",
+    why: "the upgrade's first step is this update, previewed without --write and applied with it",
+  },
+});
+
+// A deprecated operation that has since been REMOVED. Typing the old name
+// answers with its replacement instead of "unknown command, did you mean
+// ...?" — whoever still has it in a script or a habit learns the one thing
+// they need. Usage class: the fix is the invocation (ADR 0018).
+export const REMOVED = Object.freeze({
+  "constitution": { since: "0.17.0", use: "doctrina prime --rules" },
+  "change diff": { since: "0.17.0", use: "doctrina change check --verbose" },
+});
+
+/** The removal record for an invocation, or null. */
+export function removalFor(argv) {
+  const words = argv.filter((a) => !a.startsWith("-"));
+  return REMOVED[words.slice(0, 2).join(" ")] ?? REMOVED[words[0] ?? ""] ?? null;
+}
+
+/** The deprecation record for an invocation, or null. */
+export function deprecationFor(argv) {
+  const words = argv.filter((a) => !a.startsWith("-"));
+  const two = words.slice(0, 2).join(" ");
+  const one = words[0] ?? "";
+  return DEPRECATED[two] ?? DEPRECATED[one] ?? null;
+}
+
 // The declared size budget for the generated block. A surface that cannot
 // describe itself in this many lines is too large — the answer is to cut
 // commands (M8), never to raise the number.
@@ -219,8 +325,13 @@ const COMPACT_MOMENTS = new Set(["Maintain"]);
 // a name index never told it. Same shape `context` prints for skills —
 // description plus `when:`, body on demand.
 export function surfaceMarkdown() {
+  // A deprecated operation stays in the catalog — `--help` and the shell
+  // completions must still know the name someone types — but leaves this
+  // block: it is the list of commands to REACH FOR, and pointing an agent at
+  // a name that warns when used is worse than not listing it.
   const subsByCmd = new Map();
   for (const [op] of OPERATIONS) {
+    if (DEPRECATED[op]) continue;
     const [cmd, sub] = op.split(" ");
     if (!subsByCmd.has(cmd)) subsByCmd.set(cmd, []);
     if (sub) subsByCmd.get(cmd).push(sub);
@@ -242,7 +353,7 @@ export function surfaceMarkdown() {
     "canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.",
   ];
   for (const moment of MOMENTS) {
-    const cmds = COMMAND_NAMES.filter((n) => COMMAND_META[n]?.moment === moment);
+    const cmds = COMMAND_NAMES.filter((n) => COMMAND_META[n]?.moment === moment && !DEPRECATED[n]);
     if (cmds.length === 0) continue;
     if (COMPACT_MOMENTS.has(moment)) {
       // Each name still carries the `doctrina ` prefix: the compact line is
@@ -405,6 +516,20 @@ export const AGENT_CHANGELOG = {
   // Each entry lists only ITS OWN delta. The series carries the rest
   // forward (see agentChangelogEntries), so a patch never has to restate
   // the minor that introduced the commands, and never silently erases it.
+  "0.17.0": [
+    "Preview a close with `doctrina change check <id>` (it exits 1 while a Verification box is open), then run `doctrina close <id>` — do not run `analyze`, `change apply` or `change archive` by hand; a chore closes the same way.",
+    "Deprecated names still run with a notice — use the replacement: `analyze` → `change check`, `report` → `status --view report`, `skill sync` → `index rebuild`, `templates check|update` → `upgrade [--write]`. `constitution` and `change diff` are removed (exit 2).",
+    "`doctrina upgrade` now reports an installed slash command that still teaches a retired command; run the fix it prints (`doctrina adapter add <agent> --force`).",
+    "`doctrina work \"<prompt>\" --design` also scaffolds design.md — no need to fall back to `change new` for a change with non-trivial choices.",
+    "A new tasks.md has no Closing steps — the close applies, archives and indexes. `intake --converted` refuses while `validate` reports an error; a change reference is its folder name, never a path (exit 2).",
+  ],
+  "0.16.0": [
+    "A reference or path that does not resolve now answers exit 2 (USAGE) everywhere — `clarify`, `show`, `why`, `analyze`, `context`, `change check`, `spec set`, `decision accept|scope`. Correct the invocation; retrying it unchanged never succeeds.",
+    "The `--json` envelope names the OPERATION in `command` and carries arguments in `args` — branch on those two, not on a joined string. An undeclared flag now answers with `{ok: false, exit_code: 2}` instead of an empty stdout.",
+    "`analyze` executes a MODIFIED delta's `ops` block, so `analyze`, `change apply` and `close` all refuse the same unappliable block. Fix the ops before closing; a delta with no ops block is still a legitimate manual merge.",
+    "`validate` refuses more: an active spec declaring no acceptance criteria, an empty artifact, a scaffold section left unwritten, a reference that resolves to nothing. Write the criteria before flipping a spec to `active`.",
+    "`change new <id>` requires the `NNNN-slug` shape (lowercase letters, digits, hyphens) and writes nothing otherwise — `doctrina work \"<prompt>\"` derives one for you.",
+  ],
   "0.15.1": [
     "Exporting a variable under a name that is not its source's is routine — declare it in the Wiring row's Origin cell as `<origin>:<source>` (e.g. `secrets:NPM_TOKEN`) and RT02 stays silent until either side moves.",
   ],

package/src/lib/config.js

@@ -0,0 +1,206 @@
+// @ts-check
+// The project's configuration, in one place, with WHERE each value came from.
+//
+// Five files configured a Doctrina project and only one of them had an
+// `--init`: `index.json` (the context budget, under `config`), `config.json`
+// (the language, read by `clarify` alone), `rules.json` (project rules,
+// read by `validate` alone), `verify.json`, and `verify.signoffs.json`.
+// `config.json` and `rules.json` were created by nothing, documented in no
+// surface block, and reported by no command — they existed only for someone
+// who had read the source. The symptom that found this (audit finding F19):
+// a pt-BR project sits permanently red under `clarify` with no clue why.
+//
+// `.doctrina/config.json` is now the declared home. The old locations are
+// still READ — a project that configured a budget in `index.json` keeps
+// working, and removal is announced rather than performed here — but every
+// consumer asks this module, and every value carries its source so `doctor`
+// can print "configured" or "default" instead of leaving a project to guess.
+import path from "node:path";
+import { isFile, read } from "./fs-ops.js";
+
+export const CONFIG_REL = ".doctrina/config.json";
+export const RULES_REL = ".doctrina/rules.json";
+
+// The built-in default for every option. `language: null` means "detect per
+// file", which is what the absence of a declaration has always meant.
+export const DEFAULTS = Object.freeze({
+  language: null,
+  context_budget: 15000,
+  rules: [],
+});
+
+// Where a value came from, most authoritative first. The strings are printed
+// by `doctor`, so they name FILES a reader can open, not internal ids.
+export const SOURCES = Object.freeze({
+  config: CONFIG_REL,
+  index: ".doctrina/index.json (config block — legacy home)",
+  rules: RULES_REL + " (legacy home)",
+  default: "default",
+});
+
+export function configPath(projectRoot) {
+  return path.join(projectRoot, ".doctrina", "config.json");
+}
+
+/**
+ * Read the effective configuration.
+ *
+ * Precedence, per option: `.doctrina/config.json` → the legacy home for that
+ * option → the built-in default. Malformed JSON is REPORTED, never thrown:
+ * a project cannot be left unable to assemble a context pack because someone
+ * left a trailing comma in a preferences file — `validate` is where that
+ * becomes an error.
+ *
+ * @param {string} projectRoot
+ * @returns {{
+ *   language: string|null, context_budget: number, rules: any[],
+ *   sources: {language: string, context_budget: string, rules: string},
+ *   errors: string[],
+ *   unknown: string[]
+ * }}
+ */
+export function loadConfig(projectRoot) {
+  const errors = [];
+  const cfg = readJson(configPath(projectRoot), CONFIG_REL, errors);
+  // Keys the CLI does not know (change 0115). `{"context_budjet": 10}` was
+  // silence at every door, and the author believed the budget was set.
+  // Reported, never rejected: the effective values are unchanged.
+  const KNOWN_KEYS = new Set(["language", "context_budget", "rules", "$comment", "$schema"]);
+  const unknown = cfg && typeof cfg === "object" && !Array.isArray(cfg)
+    ? Object.keys(cfg).filter((k) => !KNOWN_KEYS.has(k))
+    : [];
+  /** @type {{language: string, context_budget: string, rules: string}} */
+  const sources = { language: SOURCES.default, context_budget: SOURCES.default, rules: SOURCES.default };
+
+  // language — config.json has always been its only home.
+  //
+  // PRESENCE is what makes an option configured, not the value: a key
+  // scaffolded as its default is still a declaration, and reporting it as
+  // "default" would tell a reader the file does not say what it plainly
+  // says. Only a key that is absent, or one whose value is rejected, falls
+  // back to the default.
+  let language = DEFAULTS.language;
+  if (cfg && "language" in cfg) {
+    const rawLang = cfg.language;
+    sources.language = SOURCES.config;
+    if (rawLang === null) {
+      language = null; // an explicit "detect per file"
+    } else if (typeof rawLang === "string" && normalizeLanguage(rawLang) !== null) {
+      language = normalizeLanguage(rawLang);
+    } else {
+      errors.push(`${CONFIG_REL}: unknown language ${JSON.stringify(rawLang)} (use "en" or "pt", or null to detect per file)`);
+      sources.language = SOURCES.default;
+    }
+  }
+
+  // context_budget — declared here, historically in index.json's config block.
+  let context_budget = DEFAULTS.context_budget;
+  if (cfg && "context_budget" in cfg && isPositiveInt(cfg.context_budget)) {
+    context_budget = cfg.context_budget;
+    sources.context_budget = SOURCES.config;
+  } else {
+    if (cfg && "context_budget" in cfg) {
+      errors.push(`${CONFIG_REL}: context_budget must be a positive integer (got ${JSON.stringify(cfg.context_budget)})`);
+    }
+    const fromIndex = readJson(path.join(projectRoot, ".doctrina", "index.json"), ".doctrina/index.json", [])?.config?.context_budget;
+    if (isPositiveInt(fromIndex)) {
+      context_budget = fromIndex;
+      sources.context_budget = SOURCES.index;
+    }
+  }
+
+  // rules — declared here, historically a file of their own.
+  let rules = DEFAULTS.rules;
+  if (cfg && Array.isArray(cfg.rules)) {
+    rules = cfg.rules;
+    sources.rules = SOURCES.config;
+  } else {
+    if (cfg && "rules" in cfg) {
+      errors.push(`${CONFIG_REL}: rules must be an array`);
+    }
+    const rulesPath = path.join(projectRoot, ".doctrina", "rules.json");
+    if (isFile(rulesPath)) {
+      const legacy = readJson(rulesPath, RULES_REL, errors);
+      if (legacy && !Array.isArray(legacy.rules)) {
+        errors.push(`${RULES_REL}: expected { "rules": [...] }`);
+      } else if (legacy) {
+        rules = legacy.rules;
+        sources.rules = SOURCES.rules;
+      }
+    }
+  }
+
+  return { language, context_budget, rules, sources, errors, unknown };
+}
+
+/**
+ * The configuration as rows a reader can scan: option, effective value, and
+ * where it came from. `doctor` prints these; the point is that a project can
+ * see what it configured without reading the CLI's source.
+ *
+ * @param {string} projectRoot
+ * @returns {{option: string, value: string, source: string, configured: boolean}[]}
+ */
+export function configRows(projectRoot) {
+  const cfg = loadConfig(projectRoot);
+  const show = (v) => (v === null ? "auto-detect per file" : String(v));
+  return [
+    { option: "language", value: show(cfg.language), source: cfg.sources.language, configured: cfg.sources.language !== SOURCES.default },
+    { option: "context_budget", value: `${cfg.context_budget} tokens`, source: cfg.sources.context_budget, configured: cfg.sources.context_budget !== SOURCES.default },
+    { option: "rules", value: `${cfg.rules.length} rule${cfg.rules.length === 1 ? "" : "s"}`, source: cfg.sources.rules, configured: cfg.sources.rules !== SOURCES.default },
+  ];
+}
+
+/** "pt-BR" → "pt", "en-GB" → "en", anything else → null. */
+export function normalizeLanguage(raw) {
+  const lang = String(raw ?? "").toLowerCase();
+  if (lang.startsWith("pt")) return "pt";
+  if (lang.startsWith("en")) return "en";
+  return null;
+}
+
+function isPositiveInt(n) {
+  return Number.isInteger(n) && n > 0;
+}
+
+// A malformed file is a finding, not an exception: every caller of this
+// module is either a gate that will report it or a command that must keep
+// working without it.
+function readJson(file, rel, errors) {
+  if (!isFile(file)) return null;
+  try {
+    return JSON.parse(read(file));
+  } catch (err) {
+    errors.push(`${rel} is not valid JSON: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * The file `init` writes, from the same module that reads it.
+ *
+ * Written from the definition rather than from a template, for the reason
+ * index.json is: a template copy is how a project comes to be born already
+ * needing a scaffold update (audit item C5).
+ *
+ * It declares NOTHING. A scaffold that restated every default would make the
+ * file lie in two directions: `doctor` could no longer tell a choice from a
+ * default, and a written default would silently outrank a legacy declaration
+ * — a project that had set its budget in index.json would find it ignored by
+ * a file it never edited. So the scaffold is documentation of the options,
+ * and the first key a project adds is the first thing it has actually chosen.
+ * JSON carries no comments, hence `$comment`.
+ *
+ * @returns {string} the file's contents, newline-terminated
+ */
+export function scaffoldConfig() {
+  return JSON.stringify({
+    $comment:
+      "Doctrina project configuration. Nothing is declared here yet — add a key to " +
+      "change it. Options: \"language\" (\"en\" | \"pt\", or null to detect per file); " +
+      `"context_budget" (positive integer, default ${DEFAULTS.context_budget}); ` +
+      "\"rules\" (array of { id, forbid, paths, message } — permanent project " +
+      "constraints enforced by `doctrina validate`). Run `doctrina doctor` to see the " +
+      "effective value of each option and where it came from.",
+  }, null, 2) + "\n";
+}

package/src/lib/constitution-model.js

@@ -0,0 +1,102 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read } from "./fs-ops.js";
+import { listHeader } from "./scan.js";
+
+// The standing-rules MODEL: the accepted ADRs and the named sections of
+// product.md that together are the project's constitution. `constitution`
+// renders them in full and `prime` digests them to titles, so the reading
+// belongs here rather than in either command (audit finding F7).
+
+// Accepted ADRs (NNNN-slug.md with Status: accepted), oldest first, with the
+// title read from the `# ADR NNNN — <title>` heading. Exported for `prime`,
+// which digests the same standing rules into the session primer.
+export function acceptedDecisions(projectRoot) {
+  const dir = path.join(projectRoot, ".doctrina", "decisions");
+  const out = [];
+  if (!isDir(dir)) return out;
+  for (const f of readdirSync(dir).sort()) {
+    const m = f.match(/^(\d{4})-.*\.md$/);
+    if (!m) continue;
+    const text = read(path.join(dir, f));
+    if ((listHeader(text, "Status") ?? "").toLowerCase() !== "accepted") continue;
+    const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
+    out.push({ id: m[1], title: titleMatch ? titleMatch[1].trim() : f });
+  }
+  return out;
+}
+
+// Bullets under a named `## <section>` of product.md, each accumulated across
+// its continuation lines so a wrapped bullet reads as one rule. Exported for
+// `prime`.
+/**
+ * Does `product.md` carry this `## ` section at all? Separate from whether it
+ * holds anything, so a finding can name the remedy that actually resolves it
+ * (rule C2): "add the section" and "fill the section" are different asks.
+ *
+ * @param {string} projectRoot
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function hasProductSection(projectRoot, name) {
+  const p = path.join(projectRoot, ".doctrina", "product.md");
+  if (!isFile(p)) return false;
+  return new RegExp(`^##\\s+${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "im")
+    .test(read(p));
+}
+
+export function productSection(projectRoot, name) {
+  const p = path.join(projectRoot, ".doctrina", "product.md");
+  if (!isFile(p)) return [];
+  const lines = read(p).split(/\r?\n/);
+  let inSection = false;
+  let inComment = false;
+  const out = [];
+  let cur = null;
+  const flush = () => {
+    if (cur) out.push(cur.replace(/\s+/g, " ").trim());
+    cur = null;
+  };
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      if (inSection) {
+        flush();
+        break;
+      }
+      if (new RegExp(`^##\\s+${name}\\b`, "i").test(line)) inSection = true;
+      continue;
+    }
+    if (!inSection) continue;
+    // An HTML comment is annotation, not content (change 0055): the template's
+    // own instruction for this section must never read as a declared item.
+    if (inComment) {
+      if (line.includes("-->")) inComment = false;
+      continue;
+    }
+    if (line.trim().startsWith("<!--")) {
+      if (!line.includes("-->")) inComment = true;
+      continue;
+    }
+    const m = line.match(/^\s*[-*]\s+(.+)$/);
+    if (m) {
+      flush();
+      cur = m[1];
+    } else if (cur && line.trim() !== "") {
+      cur += " " + line.trim();
+    } else if (line.trim() === "") {
+      flush();
+    } else {
+      // PROSE (change 0069). The section's own template comment invites it —
+      // "Explicit things this project will NOT try to be" asks for no bullets
+      // — and reading only bullets made `prime --rules` report a filled
+      // section as "none declared" and tell the author to add a section that
+      // was already there. Rule C2: a finding may only name a remedy that
+      // resolves it, and this one named an act already done. A paragraph is
+      // one item; a blank line ends it, exactly as it ends a bullet.
+      cur = line.trim();
+    }
+  }
+  flush();
+  return out;
+}