doctrina-cli 0.15.1 → 0.17.0

package/src/lib/lexicon.js

@@ -0,0 +1,228 @@
+// @ts-check
+import { slugify } from "./dates.js";
+
+// ONE lexicon (audit findings F5/F6).
+//
+// `work` ranked a prompt against the spec tree with one stop list, and
+// `context --for` ranked the same prompt with a different one — while the
+// work playbook tells the agent to run `context` immediately after `work`.
+// Two rankers, in sequence, on the same text, free to disagree about which
+// capability it is about. And `FIX_SHAPED` appeared byte for byte in two
+// modules, so a term added to one classifier silently did not reach the
+// other.
+//
+// What follows is the whole vocabulary the CLI uses to read natural
+// language: how text is folded, what counts as a content word, and how
+// strongly a document answers a query. Every consumer reads it from here.
+//
+// It is deliberately small and deterministic. The CLI does no natural-
+// language interpretation (ADR 0005) — these functions rank, they never
+// decide, and the playbook says so at the point the ranking is shown.
+
+/**
+ * Fold to comparable ASCII-ish lowercase: strip combining marks so a
+ * Portuguese prompt and an ASCII spec match on the same word ("função" and
+ * "funcao"), and lowercase so case never decides relevance.
+ */
+export function fold(text) {
+  return String(text ?? "").normalize("NFD").replace(/\p{M}+/gu, "").toLowerCase();
+}
+
+/**
+ * The connective tissue of a task description, in English and Portuguese.
+ *
+ * Deliberately conservative: it covers grammar and the verbs every prompt
+ * uses ("add", "create", "implementar"), and nothing domain-specific — a
+ * stop list that swallowed a real term would quietly make retrieval worse
+ * in exactly the cases it is supposed to help.
+ */
+export const STOPWORDS = new Set([
+  // en — grammar
+  "a", "an", "and", "are", "as", "at", "be", "but", "by", "can", "do", "for",
+  "from", "has", "have", "how", "i", "if", "in", "into", "is", "it", "its",
+  "of", "on", "or", "should", "that", "the", "then", "this", "to", "up",
+  "was", "we", "what", "when", "where", "which", "why", "will", "with",
+  "shall", "must",
+  // en — the verbs and nouns every feature prompt carries
+  "make", "add", "new", "use", "create", "implement", "feature", "system",
+  "user", "users",
+  // pt (ASCII-folded) — grammar
+  "uma", "umas", "uns", "dos", "das", "nos", "nas", "por", "para", "com",
+  "que", "sem", "aos", "nao", "mais", "ser", "quando", "esta", "sao",
+  "pela", "pelo", "deve", "de", "do", "da", "no", "na", "em", "ao", "os",
+  "as", "um", "ou", "se", "eh", "pra",
+  // pt — the same verbs and nouns
+  "faca", "fazer", "criar", "crie", "novo", "nova", "adicionar", "adicione",
+  "implementar", "implemente", "funcionalidade", "sistema", "usuario",
+  "usuarios",
+]);
+
+/**
+ * The content words of a query: folded, de-duplicated, stop words dropped.
+ *
+ * A term must be at least two characters, so an initial or a stray letter
+ * never becomes a search term — but "id", "ci" and "pt" survive, and those
+ * are real terms in this domain.
+ */
+export function terms(query) {
+  if (query === undefined || query === null) return [];
+  const words = fold(query).match(/[a-z][a-z0-9-]+/g) ?? [];
+  return [...new Set(words.filter((w) => !STOPWORDS.has(w)))];
+}
+
+/**
+ * How strongly a document answers the query, as a comparable TUPLE rather
+ * than one blended number — so the tiebreak order is readable and no
+ * weighting constant has to be guessed:
+ *
+ *   [ terms in the title/id, terms in the body, hits per 1000 chars ]
+ *
+ * Density, not raw hit count, breaks the final tie. Raw hits reward a
+ * document for being long: the 473-line `cli` spec out-scored `skills` on
+ * the query "write a skill from git history" purely on volume, which is the
+ * length bias that makes naive retrieval useless on a mature tree.
+ */
+export function relevance(text, queryTerms, emphasis = "") {
+  if (queryTerms.length === 0) return [0, 0, 0];
+  const hay = fold(text);
+  const head = fold(emphasis);
+  let inTitle = 0;
+  let inBody = 0;
+  let hits = 0;
+  for (const term of queryTerms) {
+    const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const boundary = `(^|[^a-z0-9-])${escaped}`;
+    const n = (hay.match(new RegExp(boundary, "g")) ?? []).length;
+    if (n > 0) {
+      inBody += 1;
+      hits += n;
+    }
+    if (head && new RegExp(boundary).test(head)) inTitle += 1;
+  }
+  const density = hay.length > 0 ? Math.round((hits / hay.length) * 1000) : 0;
+  return [inTitle, inBody, density];
+}
+
+/**
+ * The same relevance, projected onto ONE comparable number.
+ *
+ * `work` shows a score in a column and `context` orders by the tuple; both
+ * must agree about which capability a prompt is about, so the scalar is a
+ * PROJECTION of the tuple rather than a second calculation. The weights only
+ * have to preserve the tuple's own ordering — title beats body beats
+ * density — which is what the lexicographic comparison already says.
+ */
+export function score(text, queryTerms, emphasis = "") {
+  const [inTitle, inBody, density] = relevance(text, queryTerms, emphasis);
+  return inTitle * 100 + inBody * 10 + Math.min(density, 9);
+}
+
+/**
+ * A slug or identifier that reads as a FIX rather than a feature — the
+ * signal `skill suggest` and `next` both look for when deciding whether an
+ * archived change taught a lesson worth capturing.
+ *
+ * One definition: it lived byte for byte in two modules, so a term added to
+ * one classifier did not reach the other.
+ */
+export const FIX_SHAPED =
+  /(?:^|-)(fix|bug|hotfix|patch|parse|parsing|tolerate|workaround|race|deadlock|flaky|retry|escape|sanitize|sanitise)(?:-|$)/;
+
+/**
+ * The same idea applied to a commit subject. Narrower than FIX_SHAPED on
+ * purpose: a subject is prose, so it needs the conventional-commit shape or
+ * an explicit fix verb rather than a bare word match.
+ */
+export const FIX_SHAPED_SUBJECT =
+  /^(fix|bugfix|hotfix|patch)(\(|:|!)|^(revert)\b|\b(fixes|fixed|regression|workaround)\b/i;
+
+/**
+ * Which language a document is written in, by counting each lexicon's
+ * grammar words. Used by `clarify` to pick its smell lexicon when the
+ * project declares no language.
+ */
+const PT_GRAMMAR = /\b(que|n[aã]o|para|uma|como|mais|ser|quando|est[aá]|s[aã]o|pela|pelo|dos|das|ou seja|deve)\b/gi;
+const EN_GRAMMAR = /\b(the|and|that|with|shall|when|this|from|are|not|for|must)\b/gi;
+
+export function detectLanguage(text) {
+  const pt = (String(text).match(PT_GRAMMAR) ?? []).length;
+  const en = (String(text).match(EN_GRAMMAR) ?? []).length;
+  return pt > en ? "pt" : "en";
+}
+
+/**
+ * The margin a ranked winner must hold over the runner-up before a caller
+ * may ACT on the ranking rather than merely display it.
+ *
+ * `triage` calls a verdict confident when the winning lane beats the
+ * runner-up by 2. Copying that number here would copy a unit, not the
+ * notion: on `score()` above, every signal is worth 10 or 100 and the
+ * density tie-breaker alone moves the number by up to 9. A gap of 2 can
+ * therefore mean the two specs matched exactly the same terms and one of
+ * them is shorter — the opposite of confidence.
+ *
+ * 10 is the smallest gap density CANNOT produce: it is one whole body
+ * term. Density is capped at 9 precisely so it can only break ties, so a
+ * margin at or above 10 says the winner led on term overlap itself.
+ */
+export const CONFIDENT_MARGIN = 10;
+
+// The SLUG_WORDS content words of a prompt, slugified — the short half of a
+// change id (change 0070).
+//
+// The id used to be the whole prompt slugified, and the proposal's H1 is
+// `# Change <id> — <title>` with the title defaulting to that same prompt: so
+// a change opened on the default path said the same sentence twice, and every
+// read surface printed both halves. `prime` spent 133 characters of one line
+// on it — the command whose entire value is density.
+//
+// The id is what a person types and what sorts a backlog, so it wants to be
+// short; the title is what a person reads, so it wants to be whole. Capping
+// the SLUG rather than truncating the title gives both, and is exactly what
+// `--title` did by hand. Deterministic: a shipped stopword list, first N
+// content words, no interpretation (ADR 0005).
+export const SLUG_WORDS = 4;
+
+// A number is content in an id (change 0191). `terms` serves retrieval, where
+// a bare "24" matches everything, so it keeps only words that start with a
+// letter — and the slug inherited that: "cortar a 0.17.0" became `cortar`
+// and "migrar para Node 24" `migrar-node`. The slug reads its own tokens: a
+// version or a number is one word, its dots folded into hyphens.
+function slugTerms(prompt) {
+  const words = (fold(String(prompt ?? "")).match(/[a-z0-9][a-z0-9.-]*/g) ?? [])
+    .map((w) => w.replace(/[.-]+$/g, "").replace(/\./g, "-"))
+    .filter((w) => (w.length > 1 || /^\d$/.test(w)) && !STOPWORDS.has(w));
+  return [...new Set(words)];
+}
+
+export function slugFromPrompt(prompt, { words = SLUG_WORDS } = {}) {
+  const content = slugTerms(prompt).slice(0, words);
+  const slug = slugify(content.join(" "));
+  // A prompt of nothing but stopwords ("do it now") still needs an id.
+  return slug || slugify(prompt).split("-").slice(0, words).join("-");
+}
+
+// A SKILL SLUG IS FOLDED, NOT SHREDDED.
+//
+// `skill suggest` names a lesson from text a person wrote — a change id, a
+// commit subject, the seed tokens of an error. That name became a filename,
+// and it was built by stripping everything outside `[a-z0-9-]` from the raw
+// text. On Portuguese input the strip is destructive rather than normalising:
+// every capital is DELETED and every accented letter becomes a hyphen, so
+// "Corrigir A Validação" came out "orrigir-alida-o" and a real run wrote
+// `.doctrina/skills/o-modelo-de-documento-n-o-l-cabe-alho-de.md`.
+//
+// The tell was already in this module: SLUG_NOISE lists "nao", a token the
+// old pipeline could never produce. So the slug goes through `slugify`, the
+// same fold every other slug in the tree uses.
+//
+// The leading numeric run goes with it. The source is often a change id
+// ("0049-fix-tela-preta"), the digits identify nothing about the lesson, and
+// the skills spec requires a filename slug to start with a letter.
+export const SKILL_SLUG_MAX = 40;
+
+export function skillSlug(text, { max = SKILL_SLUG_MAX } = {}) {
+  const slug = slugify(text).replace(/^\d+(?:-|$)/, "");
+  const capped = slug.length > max ? slug.slice(0, max).replace(/-+$/g, "") : slug;
+  return capped || "lesson";
+}

package/src/lib/metrics-model.js

@@ -0,0 +1,189 @@
+// @ts-check
+// The adoption metrics themselves: what a snapshot IS, computed once.
+//
+// `metrics` renders a snapshot and saves it; `report` shows two of its rates
+// for the reporting period. Before this they would each have had their own
+// idea of "revert rate", which is the kind of divergence nobody notices until
+// two numbers on two screens disagree and neither is wrong (ADR 0025).
+//
+// Everything here is derived from local git history. No network calls, no
+// telemetry: the numbers stay in the repository, versioned like any other
+// artifact. This is the tooling half of docs/en/validation.md.
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read } from "./fs-ops.js";
+import { today } from "./dates.js";
+import { GIT_STATE, git } from "./git.js";
+
+export const REEDIT_WINDOW_DAYS = 21;
+export const METRICS_REL = ".doctrina/metrics";
+
+export function computeSnapshot(commits, since) {
+  const total = commits.length;
+  const reverts = commits.filter((cm) => /^Revert\b/.test(cm.subject)).length;
+  const fixes = commits.filter((cm) => /^fix[(:!]/.test(cm.subject)).length;
+
+  // File churn: commits per file, top offenders first.
+  const churn = new Map();
+  for (const cm of commits) {
+    for (const f of cm.files) churn.set(f, (churn.get(f) ?? 0) + 1);
+  }
+  const topChurn = [...churn.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .map(([file, count]) => ({ file, commits: count }));
+
+  // Re-edit proxy: a commit counts when it touches a file another commit
+  // already touched in the previous REEDIT_WINDOW_DAYS. This is a proxy
+  // for rework, not a verdict — iterative work also trips it.
+  const windowSec = REEDIT_WINDOW_DAYS * 86400;
+  const lastTouch = new Map();
+  let reedits = 0;
+  for (const cm of [...commits].sort((a, b) => a.ts - b.ts)) {
+    const isReedit = cm.files.some((f) => {
+      const prev = lastTouch.get(f);
+      return prev !== undefined && cm.ts - prev <= windowSec;
+    });
+    if (isReedit) reedits += 1;
+    for (const f of cm.files) lastTouch.set(f, cm.ts);
+  }
+
+  return {
+    generated: today(),
+    window: since,
+    commits: total,
+    reverts,
+    revert_rate: round(reverts / total),
+    fix_share: round(fixes / total),
+    reedit_window_days: REEDIT_WINDOW_DAYS,
+    reedit_rate: round(reedits / total),
+    top_churn: topChurn,
+  };
+}
+
+
+export function parseLog(stdout) {
+  const commits = [];
+  let current = null;
+  for (const line of stdout.split("\n")) {
+    if (line.startsWith("@@")) {
+      const [hash, ts, ...rest] = line.slice(2).split("|");
+      current = { hash, ts: Number(ts), subject: rest.join("|"), files: [] };
+      commits.push(current);
+    } else if (line.trim() !== "" && current) {
+      current.files.push(line.trim());
+    }
+  }
+  return commits;
+}
+
+
+export function round(x) {
+  return Math.round(x * 1000) / 1000;
+}
+
+
+const WINDOW_UNIT = /^(\d+)\s+(second|minute|hour|day|week|month|year)s?\s+ago$/i;
+
+/**
+ * The git `--since` value for a `--since` flag, or null when the flag is not
+ * a window this can check.
+ *
+ * git never refuses a date: "abc" parses as NOW (an empty window, reported
+ * as "nothing to measure") and "2026-13-45" as some other day. Handing it
+ * free text turned a typo into a confident, wrong answer, so only the forms
+ * whose meaning is certain pass: a day count, a calendar date
+ * (YYYY-MM-DD), or "<n> <unit>s ago".
+ *
+ * @param {string} raw
+ * @returns {string | null}
+ */
+export function sinceWindow(raw) {
+  const s = String(raw ?? "").trim();
+  if (/^\d+$/.test(s)) return Number(s) > 0 ? `${Number(s)} days ago` : null;
+  const date = s.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (date) {
+    const [y, m, d] = date.slice(1).map(Number);
+    const t = new Date(Date.UTC(y, m - 1, d));
+    const real = t.getUTCFullYear() === y && t.getUTCMonth() === m - 1 && t.getUTCDate() === d;
+    return real ? s : null;
+  }
+  const rel = s.match(WINDOW_UNIT);
+  if (rel) return Number(rel[1]) > 0 ? s.replace(/\s+/g, " ") : null;
+  return null;
+}
+
+/**
+ * A snapshot for a window, or null when there is no history to read.
+ *
+ * @param {string} projectRoot
+ * @param {string} since  a git --since value ("90 days ago", "2026-01-01")
+ */
+export function collectMetrics(projectRoot, since) {
+  const log = git(projectRoot, [
+    "log", `--since=${since}`, "--date=unix",
+    "--pretty=format:@@%H|%ct|%s", "--name-only",
+  ]);
+  if (log.state !== GIT_STATE.OK) return null;
+  const commits = parseLog(log.stdout);
+  if (commits.length === 0) return null;
+  return computeSnapshot(commits, since);
+}
+
+/**
+ * Every saved snapshot, oldest first.
+ *
+ * The snapshots are a TIME SERIES, versioned in the repository — and for two
+ * releases the only thing that ever read them was a delta against the most
+ * recent one, so a year of measurement answered exactly one question: "is it
+ * better than last time?" (audit finding F15). Reading the series is what
+ * makes the saving worth doing.
+ */
+export function readSeries(projectRoot) {
+  const dir = path.join(projectRoot, ...METRICS_REL.split("/"));
+  if (!isDir(dir)) return [];
+  const out = [];
+  for (const f of readdirSync(dir).sort()) {
+    if (!/^\d{4}-\d{2}-\d{2}\.json$/.test(f)) continue;
+    const file = path.join(dir, f);
+    if (!isFile(file)) continue;
+    try {
+      const snap = JSON.parse(read(file));
+      // The filename is the authority on when it was taken: `generated` can
+      // be absent in a hand-edited file, and a series ordered by a field
+      // that may be missing is not ordered at all.
+      out.push({ ...snap, generated: snap.generated ?? f.replace(/\.json$/, "") });
+    } catch { /* a malformed snapshot is skipped, never fatal */ }
+  }
+  return out;
+}
+
+/** The most recent saved snapshot, excluding one basename. */
+export function latestSnapshot(projectRoot, excludeBase = null) {
+  const series = readSeries(projectRoot).filter((s) => `${s.generated}.json` !== excludeBase);
+  return series.length > 0 ? series[series.length - 1] : null;
+}
+
+/**
+ * The direction each tracked rate moved across the WHOLE series.
+ *
+ * First to last, not last to previous: a rate that drifted up for six months
+ * and dipped once looks like an improvement from the delta and like what it
+ * is from the series.
+ *
+ * @param {ReturnType<typeof readSeries>} series
+ */
+export function trend(series) {
+  const rates = ["revert_rate", "fix_share", "reedit_rate"];
+  if (series.length < 2) return { span: series.length, rows: [] };
+  const first = series[0];
+  const last = series[series.length - 1];
+  const rows = [];
+  for (const rate of rates) {
+    const a = first[rate];
+    const b = last[rate];
+    if (typeof a !== "number" || typeof b !== "number") continue;
+    rows.push({ rate, first: a, last: b, delta: round(b - a) });
+  }
+  return { span: series.length, from: first.generated, to: last.generated, rows };
+}

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,105 @@
+// @ts-check
+import path from "node:path";
+import { exists } from "./fs-ops.js";
+import { EXIT, notADoctrinaProject } from "./exit-codes.js";
+import { c } from "./colors.js";
+import { load } from "./index-json.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();
+  }
+}
+
+/**
+ * What this project is CALLED — the name it recorded at `init`, with the
+ * directory as the fallback for a tree that has none.
+ *
+ * Four modules asked this privately and one of them answered differently:
+ * `adapter` read the directory and never the record, so every adapter file
+ * installed after `doctrina init --project-name "Minha Carteira"` greeted the
+ * agent with the folder's name instead. `init --agent`, holding the name it
+ * had just been given, got it right — the same templates, two callers, two
+ * answers.
+ *
+ * Pass `index` when you already hold it; the helper then reads nothing.
+ *
+ * @param {string} projectRoot
+ * @param {any} [index] an already-loaded index.json, when the caller has one
+ */
+export function projectName(projectRoot, index) {
+  if (index !== undefined) return index?.project ?? path.basename(projectRoot);
+  try {
+    return load(projectRoot)?.project ?? path.basename(projectRoot);
+  } catch {
+    return path.basename(projectRoot);
+  }
+}
+
+// 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);
+}
+
+// A reference to an EXISTING change is looser than the id `change new`
+// accepts — a project may hold a change named before that grammar — but it
+// is always a folder NAME under .doctrina/changes/, never a path. Nothing
+// checked that: `change archive ../../victim --force` moved the project's
+// own `victim/` directory into the archive and wrote it into the ledger and
+// the index (change 0196). `archive` is the archive's own folder, not a
+// change.
+export function isChangeRef(id) {
+  return typeof id === "string" && id.length > 0 && id !== "." && id !== ".."
+    && id !== "archive" && !/[\/\\\0]/.test(id);
+}
+
+// The one refusal every command that takes a change reference prints: the
+// USAGE class, before anything is resolved against the filesystem.
+export function refuseChangeRef(id) {
+  if (isChangeRef(id)) return null;
+  console.error(c.red("error:") + ` "${id}" is not a change — a change is named by its folder under .doctrina/changes/, never by a path`);
+  console.error(c.gray("hint: ") + "open changes: `doctrina next`");
+  return EXIT.USAGE;
+}
+
+/**
+ * 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;
+}