doctrina-cli 0.16.0 → 0.17.0

package/src/lib/index-json.js

@@ -64,10 +64,45 @@ export function blank(projectName, date) {
   };
 }
 
+// INSERT WHERE A REBUILD WOULD HAVE PUT IT.
+//
+// Every category here is written twice: incrementally, by the command that
+// creates the artifact, and wholesale by `index rebuild`, which walks the
+// directory — `readdirSync(...).sort()` — and writes what it finds, in that
+// order. The two agreed only by luck: appending matches a sorted walk exactly
+// when the new entry happens to sort last.
+//
+// It usually does, which is why this survived. `doctrina spec new alpha` after
+// `spec new zebra` does not, and neither does closing change 0138 after 0139 —
+// that one shipped, and turned all six test legs of CI red on a tree whose own
+// `close` had just reported green.
+//
+// `validate` cannot see it: drift of this kind is only visible by rebuilding
+// and comparing, which is `index rebuild --check`, a different gate. So the
+// tree looked healthy from inside and failed from outside.
+//
+// Each entry's `path` embeds the on-disk name the rebuild sorts by, and the
+// parent directory is constant within a category — so ordering by `path`
+// reproduces the walk exactly, without this module having to know how any
+// category is laid out.
+// The comparison has to be the SAME one: `readdirSync(dir).sort()` takes the
+// default comparator, which orders by UTF-16 code unit, and `localeCompare`
+// does not — it ignores or reweights punctuation, so `0100-a` and `0100_a`
+// can come out in the opposite order. Matching the walk means comparing the
+// way the walk compares.
+function insertInRebuildOrder(list, entry) {
+  list.push(entry);
+  list.sort((a, b) => {
+    const x = String(a.path ?? ""), y = String(b.path ?? "");
+    return x < y ? -1 : x > y ? 1 : 0;
+  });
+  return list;
+}
+
 export function addSkill(index, entry) {
   if (!index.artifacts.skills) index.artifacts.skills = [];
   if (!index.artifacts.skills.some((s) => s.id === entry.id)) {
-    index.artifacts.skills.push(entry);
+    insertInRebuildOrder(index.artifacts.skills, entry);
   }
   return index;
 }
@@ -75,7 +110,7 @@ export function addSkill(index, entry) {
 export function addContract(index, entry) {
   if (!index.artifacts.contracts) index.artifacts.contracts = [];
   if (!index.artifacts.contracts.some((s) => s.id === entry.id)) {
-    index.artifacts.contracts.push(entry);
+    insertInRebuildOrder(index.artifacts.contracts, entry);
   }
   return index;
 }
@@ -87,14 +122,14 @@ export function touch(index, date) {
 
 export function addSpec(index, entry) {
   if (!index.artifacts.specs.some((s) => s.id === entry.id)) {
-    index.artifacts.specs.push(entry);
+    insertInRebuildOrder(index.artifacts.specs, entry);
   }
   return index;
 }
 
 export function addDecision(index, entry) {
   if (!index.artifacts.decisions.some((d) => d.id === entry.id)) {
-    index.artifacts.decisions.push(entry);
+    insertInRebuildOrder(index.artifacts.decisions, entry);
   }
   return index;
 }
@@ -110,7 +145,7 @@ export function updateDecision(index, id, mutator) {
 export function moveChangeToArchive(index, id, archiveEntry) {
   index.artifacts.changes = index.artifacts.changes.filter((c) => c.id !== id);
   if (!index.artifacts.changes_archive.some((c) => c.id === id)) {
-    index.artifacts.changes_archive.push(archiveEntry);
+    insertInRebuildOrder(index.artifacts.changes_archive, archiveEntry);
   }
   return index;
 }

package/src/lib/intake-model.js

@@ -10,6 +10,8 @@ import { exists, isFile, read, relPath, write } from "./fs-ops.js";
 import { assessBrief } from "./clarity.js";
 import { c } from "./colors.js";
 import { printPlaybookTemplate } from "./playbook.js";
+import { getHeader, setHeader } from "./doc-model.js";
+import { stateWord } from "./spec-ops.js";
 // Clarification gate (review Topic A). A description too thin to spec from is
 // the moment to ask the user, not to let the agent invent requirements. Prints
 // the specific gaps before the bootstrap playbook; advisory, never blocking —
@@ -39,6 +41,30 @@ export function looksLikePath(value) {
   return false;
 }
 
+// What `init` tells a person to do next (change 0173). The first run used to
+// contradict itself three ways: `init` said "edit AGENTS.md and product.md",
+// `next` asked for the description again as an intake, and AGENTS.md said the
+// agent runs the commands while the human stays passive. One answer now,
+// the same one `next` and AGENTS.md give.
+//
+// `intakeFrom` is "tty" when the description was typed at init's question
+// (it is stored as the intake), or null when init got no intake at all.
+export function nextStepAfterInit(intakeFrom) {
+  if (intakeFrom === "tty") {
+    return [
+      "Next: open your AI agent in this repository and tell it:",
+      "    read AGENTS.md and run doctrina next",
+      "It turns your description into product.md and specs; you review and approve.",
+    ];
+  }
+  return [
+    "Next: give your AI agent the whole project description. It runs",
+    "    doctrina intake --text \"<description>\"",
+    "and turns it into product.md and specs (AGENTS.md, \"Working from intent\");",
+    "for an existing codebase, `doctrina work --from-diff` backfills them from the code.",
+  ];
+}
+
 export function warnIfThinIntake(body) {
   const assessment = assessBrief(body, { kind: "intake" });
   if (!assessment.thin) return;
@@ -47,8 +73,51 @@ export function warnIfThinIntake(body) {
   console.log("");
 }
 
+// THE INTAKE'S STATUS IS A CONTROL VALUE, SO IT GETS AN ENUM AND AN OWNER.
+//
+// `next` branches on it: pending means the bootstrap is unfinished, and every
+// other artifact's status in this framework is both written by a command and
+// checked against an enum — `spec set` refuses "Status: nonsense", and
+// `validate` calls it an error. The intake was the one header the playbook
+// told an agent to edit BY HAND, and the one nothing read back.
+//
+// So any token that was not exactly "converted" meant pending, in silence:
+// "convertido" typed in a Portuguese project, "done", or an empty value left
+// by a botched edit. `validate` exited 0 on all of them and `next` went on
+// asking for a bootstrap that had already happened.
+export const INTAKE_STATUSES = ["pending", "converted"];
+
+/** The intake's status word, note stripped and folded. Defaults to pending. */
+export function intakeStatus(text) {
+  const raw = getHeader(String(text ?? ""), "Status");
+  if (raw === null) return "pending";
+  return stateWord(raw) || "";
+}
+
+/** null when the intake's status is a declared value; otherwise the error. */
+export function intakeStatusError(text) {
+  const word = intakeStatus(text);
+  if (INTAKE_STATUSES.includes(word)) return null;
+  const got = getHeader(String(text ?? ""), "Status");
+  return `Status must be one of ${INTAKE_STATUSES.join("|")} `
+    + `(got "${String(got ?? "").trim()}") — every other value reads as pending, in silence`;
+}
+
+/**
+ * Flip the stored intake to `converted`. Returns the path written, or null
+ * when there is no intake (or no Status header) to flip.
+ */
+export function markIntakeConverted(projectRoot) {
+  const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
+  if (!exists(intakePath)) return null;
+  const next = setHeader(read(intakePath), "Status", "converted");
+  if (next === null) return null;
+  write(intakePath, next, { force: true });
+  return intakePath;
+}
+
 // Shared with `init --intake`. Writes the intake verbatim under a small
-// status header; the agent flips Status to converted at the end of the
+// status header; `doctrina intake --converted` flips it at the end of the
 // playbook, which is how `next` knows the bootstrap is done.
 export function writeIntakeFile(projectRoot, { body, source, projectName, date, force = false }) {
   const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
@@ -61,7 +130,7 @@ export function writeIntakeFile(projectRoot, { body, source, projectName, date,
     "",
     "<!-- Raw project intent, stored verbatim. The bootstrap playbook",
     "     (doctrina intake) converts it into product.md and capability",
-    "     specs, then flips Status to converted. After conversion the",
+    "     specs. Close it with `doctrina intake --converted`; after that the",
     "     specs are the only source of truth; never edit this file to",
     "     change requirements. -->",
     "",

package/src/lib/lexicon.js

@@ -183,9 +183,46 @@ export const CONFIDENT_MARGIN = 10;
 // 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 = terms(prompt).slice(0, 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

@@ -83,6 +83,36 @@ export function round(x) {
 }
 
 
+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.
  *

package/src/lib/project.js

@@ -1,7 +1,9 @@
 // @ts-check
 import path from "node:path";
 import { exists } from "./fs-ops.js";
-import { notADoctrinaProject } from "./exit-codes.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
@@ -13,6 +15,31 @@ export function ensureDoctrinaProject(projectRoot) {
   }
 }
 
+/**
+ * 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
@@ -31,6 +58,27 @@ 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.
  *

package/src/lib/scan.js

@@ -1,14 +1,16 @@
 // @ts-check
 import { getHeader, getSection, parseChangeTitle } from "./doc-model.js";
+import { projectName } from "./project.js";
 import path from "node:path";
 import { readdirSync } from "node:fs";
 import { isDir, isFile, read, walk } from "./fs-ops.js";
 import { today } from "./dates.js";
 import { cliVersion, newestVersion } from "./version.js";
 import { load } from "./index-json.js";
-import { parseFrontmatter } from "./doc-model.js";
+import { parseFrontmatter, isScaffoldValue } from "./doc-model.js";
 import { parseCapabilityFromDelta } from "./doc-model.js";
 import { parseOperation } from "./doc-model.js";
+import { git, gitLines, isRepo, GIT_STATE } from "./git.js";
 
 // Header reading lives in ONE place now (lib/doc-model.js, audit item M3).
 // These two names survive because dozens of call sites use them and the
@@ -168,6 +170,23 @@ export function changeEntry(proposal, id, prev, date) {
 }
 
 
+// An archived change, as an index entry — the one constructor both the
+// rebuild and `change archive` use. They each built their own, and neither
+// 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 }) {
+  return {
+    id,
+    title: (title === undefined ? parseChangeTitle(proposal) : title) ?? prev?.title ?? id,
+    path: `.doctrina/changes/archive/${archiveName}`,
+    status: "applied",
+    applied,
+    specs_affected: specsAffected,
+    ...laneOf(proposal, prev),
+  };
+}
+
 // Regenerate the index object from the artifacts on disk. The files are
 // the source of truth; fields with no on-disk source (project name,
 // framework_version, product metadata) are carried over from `current`.
@@ -178,7 +197,7 @@ export function deriveIndex(projectRoot, current) {
 
   const out = {
     $schema_version: current?.$schema_version ?? "0.1.0",
-    project: current?.project ?? path.basename(projectRoot),
+    project: projectName(projectRoot, current),
     framework_version: current?.framework_version ?? "0.0.0",
     last_updated: current?.last_updated ?? date,
     // Project settings, carried over verbatim. `deriveIndex` rebuilds the
@@ -284,14 +303,9 @@ export function deriveIndex(projectRoot, current) {
         specsAffected.push({ capability, operation: parseOperation(text) ?? "MODIFIED" });
       }
     }
-    out.artifacts.changes_archive.push({
-      id: m[2],
-      title: title ?? prev?.title ?? m[2],
-      path: `.doctrina/changes/archive/${name}`,
-      status: "applied",
-      applied: m[1],
-      specs_affected: specsAffected,
-    });
+    out.artifacts.changes_archive.push(archivedChangeEntry(proposal, {
+      id: m[2], archiveName: name, applied: m[1], specsAffected, prev, title,
+    }));
   }
 
   // Contracts — the integration/runtime surface (ports, env, interfaces)
@@ -310,18 +324,26 @@ export function deriveIndex(projectRoot, current) {
     });
   }
 
-  // Skills — frontmatter description wins.
+  // Skills — a WRITTEN frontmatter description wins. The rebuild is the one
+  // reconciliation (change 0177 retired `skill sync`, which did a subset of
+  // this), so it carries sync's rule: a description still in the scaffold's
+  // `<...>` form never overwrites one somebody wrote (change 0111), and the
+  // entry's date moves when its description does.
   const skillsDir = path.join(dot, "skills");
   for (const f of walk(skillsDir)) {
     if (!f.endsWith(".md")) continue;
     const id = path.basename(f, ".md");
     const prev = (cur.skills ?? []).find((s) => s.id === id);
+    const written = parseFrontmatter(read(f), "description");
+    const kept = prev?.description && !isScaffoldValue(prev.description) ? prev.description : null;
+    const description = written && !isScaffoldValue(written)
+      ? written
+      : kept ?? written ?? "<edit me — one-sentence summary>";
     out.artifacts.skills.push({
       id,
       path: `.doctrina/skills/${id}.md`,
-      description: parseFrontmatter(read(f), "description")
-        ?? prev?.description ?? "<edit me — one-sentence summary>",
-      last_updated: prev?.last_updated ?? date,
+      description,
+      last_updated: prev && prev.description === description ? prev.last_updated ?? date : date,
     });
   }
 
@@ -487,3 +509,93 @@ export function dependentsOf(projectRoot, caps) {
   }
   return out;
 }
+
+// ---------------------------------------------------------------- staged
+
+/**
+ * The same question as `collectIndexDrift`, asked of the COMMIT instead of
+ * the disk.
+ *
+ * `index.json` is derived from the whole tree, so it cannot describe a
+ * subset of it. Stage some of `.doctrina/` and the index that rides along
+ * names artifacts the commit does not carry — and every gate that would
+ * catch it reads the working tree, where those artifacts are still present.
+ * Four commits of this repository shipped that way, each green locally and
+ * each red on checkout: `index.json references missing artifact`.
+ *
+ * Read with git plumbing, never from disk: `:<path>` is the staged blob and
+ * `ls-files --cached` is the file list the commit will have.
+ *
+ * @param {string} projectRoot
+ * @returns {{ok: boolean, applicable: boolean, missing: string[], unindexed: string[], reason: string|null}}
+ */
+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"]);
+  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.
+    return { ...nothing, reason: "no staged .doctrina/index.json" };
+  }
+
+  let staged;
+  try {
+    staged = JSON.parse(blob.stdout);
+  } catch {
+    return { ok: false, applicable: true, missing: [], unindexed: [],
+      reason: "the staged .doctrina/index.json is not valid JSON" };
+  }
+
+  const files = new Set(gitLines(projectRoot, ["ls-files", "--cached", "--", ".doctrina"]));
+  // An entry's path is a file for specs, ADRs, skills and contracts, and a
+  // DIRECTORY for changes — a directory is in the commit when any file under
+  // it is.
+  const inCommit = (p) => files.has(p) || [...files].some((f) => f.startsWith(`${p}/`));
+
+  const artifacts = staged.artifacts ?? {};
+  const missing = [];
+  for (const [kind, entries] of Object.entries(artifacts)) {
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      const p = String(entry?.path ?? "");
+      if (p && !inCommit(p)) missing.push(`${kind}: ${p}`);
+    }
+  }
+
+  // The mirror case: an artifact staged into the commit that the staged index
+  // never heard of. Same shapes `index rebuild` derives entries from.
+  const indexed = new Set();
+  for (const entries of Object.values(artifacts)) {
+    if (Array.isArray(entries)) for (const e of entries) indexed.add(String(e?.path ?? ""));
+  }
+  const unindexed = [];
+  for (const f of [...files].sort()) {
+    const owner = artifactPathOf(f);
+    if (owner && !indexed.has(owner)) unindexed.push(owner);
+  }
+
+  const unique = [...new Set(unindexed)];
+  return {
+    ok: missing.length === 0 && unique.length === 0,
+    applicable: true,
+    missing,
+    unindexed: unique,
+    reason: null,
+  };
+}
+
+// The index entry a staged file belongs to, or null when the file is not an
+// artifact (templates, config.json, product.md, the index itself).
+function artifactPathOf(file) {
+  let m = /^\.doctrina\/specs\/[^/]+\/spec\.md$/.exec(file);
+  if (m) return file;
+  m = /^\.doctrina\/(?:decisions|skills|contracts)\/[^/]+\.md$/.exec(file);
+  if (m) return file;
+  m = /^(\.doctrina\/changes\/archive\/[^/]+)\/proposal\.md$/.exec(file);
+  if (m) return m[1];
+  m = /^(\.doctrina\/changes\/(?!archive\/)[^/]+)\/proposal\.md$/.exec(file);
+  if (m) return m[1];
+  return null;
+}

package/src/lib/snapshot.js

@@ -2,6 +2,7 @@
 import path from "node:path";
 import { readdirSync } from "node:fs";
 import { isDir, isFile, read, walk } from "./fs-ops.js";
+import { projectName } from "./project.js";
 import * as idx from "./index-json.js";
 import { deriveIndex, indexesMatch, specHeader, listHeader } from "./scan.js";
 import { cliVersion } from "./version.js";
@@ -12,6 +13,8 @@ import { computeActions } from "./actions.js";
 import { readLedger } from "./ledger.js";
 import { parseChangeTitle, checklistProgress } from "./doc-model.js";
 import { summarizeSignoffs } from "./signoff.js";
+import { gitWindow, historyState, windowCutoff } from "./git.js";
+import { collectMetrics } from "./metrics-model.js";
 
 // ONE collector, several views (audit finding F7).
 //
@@ -57,7 +60,7 @@ export function collectSnapshot(projectRoot, { actions = true } = {}) {
   const verify = readVerifyConfig(projectRoot);
 
   return {
-    project: index?.project ?? path.basename(projectRoot),
+    project: projectName(projectRoot, index),
     stamp: index?.framework_version ?? null,
     cli: cliVersion(),
     indexState,
@@ -207,3 +210,22 @@ function countSkills(projectRoot) {
   if (!isDir(skillsDir)) return 0;
   return walk(skillsDir).filter((f) => f.endsWith(".md")).length;
 }
+
+/**
+ * Everything the period digest reads beyond the snapshot, for a window of
+ * `days`. ONE collector for every door that renders the digest: `report`
+ * passed the metrics and `status --view report` did not, so the view that
+ * promised "never different numbers" printed two lines fewer (change 0176).
+ *
+ * @param {string} projectRoot
+ * @param {number} days
+ */
+export function collectReportWindow(projectRoot, days) {
+  return {
+    days,
+    cutoffIso: windowCutoff(days),
+    git: gitWindow(projectRoot, days),
+    gitState: historyState(projectRoot),
+    metrics: collectMetrics(projectRoot, `${days} days ago`),
+  };
+}

package/src/lib/spec-ops.js

@@ -256,7 +256,10 @@ export function setHeader(text, name, value) {
   // has a lifecycle of its own (proposed -> applied, accepted, superseded).
   const listForm = /^\s*-/.test(text.match(re)?.[1] ?? "");
   const domain = listForm ? null : headerValueError(name, value);
-  if (domain) return { error: `set-header: ${domain}` };
+  // `cause: "argument"` marks an error about the value supplied, not about
+  // the document: `spec set` answers it as USAGE, a delta as a defect of
+  // the work (ADR 0018).
+  if (domain) return { error: `set-header: ${domain}`, cause: "argument" };
   const next = text.replace(re, (_m, prefix) => `${prefix} ${value}`.replace(/\s+$/, ""));
   return { text: next, summary: `set ${name}: ${value}` };
 }
@@ -309,10 +312,10 @@ export function setCriterionMark(text, n, markRaw) {
   const loc = locateCriteria(text);
   if (!loc) return { error: "set-criterion: spec has no '## Acceptance criteria' section" };
   const item = loc.items.find((it) => it.n === n);
-  if (!item) return { error: `set-criterion: no criterion #${n} found` };
+  if (!item) return { error: `set-criterion: no criterion #${n} found`, cause: "argument" };
   const mark = markRaw.replace(/^\[|\]$/g, "").trim();
   const domain = criterionMarkError(mark);
-  if (domain) return { error: `set-criterion: ${domain}` };
+  if (domain) return { error: `set-criterion: ${domain}`, cause: "argument" };
   const line = loc.lines[item.lineIndex];
   let next;
   if (/\[[^\]]*\]/.test(line)) {
@@ -481,8 +484,24 @@ export function replaceRequirement(text, section, n, value) {
   if (n > real.length) {
     return { error: `replace-requirement: section "${section}" has ${real.length} requirement${real.length === 1 ? "" : "s"}, no #${n}` };
   }
-  const indent = loc.lines[real[n - 1]].match(/^(\s*)/)[1];
-  loc.lines[real[n - 1]] = `${indent}- ${value}`;
+  // REPLACE THE WHOLE ITEM, continuation lines included.
+  //
+  // Writing only the first line leaves the old bullet's wrapped prose sitting
+  // under the new one, indented, reading as part of it. That is not cosmetic:
+  // the orphan is the PREVIOUS version of the requirement, so the spec ends up
+  // stating a contract and then contradicting it two lines later, and a spec
+  // is the one artifact this framework asks everyone to trust.
+  //
+  // It had already happened four times in this repository's own tree before
+  // anyone noticed — twice in `gates` (a closing sequence missing its review
+  // and runtime steps, a doctor set missing its runtime row) and once in
+  // `insight`, all three describing older behaviour beside the current one.
+  //
+  // `append-requirement` learned this in 0.13.0 and got `endOfItem`; this verb
+  // was written afterwards and never picked it up.
+  const start = real[n - 1];
+  const indent = loc.lines[start].match(/^(\s*)/)[1];
+  loc.lines.splice(start, endOfItem(loc.lines, start) - start + 1, `${indent}- ${value}`);
   return { text: loc.lines.join("\n"), summary: `replace-requirement ${section} ${n}` };
 }