doctrina-cli 0.16.0 → 0.18.0

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,106 @@ 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;
+}
+
+// The capabilities a change's deltas target, sorted — the change's own scope.
+// `close` gates coverage on it and `review --change` reads it as "these specs
+// are being updated by this change", because the delta merges at apply.
+export function deltaCapabilities(changeDir) {
+  const caps = new Set();
+  for (const deltaPath of walk(path.join(changeDir, "specs"))) {
+    if (!deltaPath.endsWith("delta.md")) continue;
+    const cap = parseCapabilityFromDelta(read(deltaPath), deltaPath);
+    if (cap) caps.add(cap);
+  }
+  return [...caps].sort();
+}

package/src/lib/signoff.js

@@ -96,6 +96,30 @@ export function changedSince(projectRoot, sha, paths) {
   return [...out].sort();
 }
 
+/**
+ * Which of `paths` the uncommitted work touches — edits against HEAD plus
+ * untracked files, `.gitignore` respected (change 0204). The same pathspec
+ * reading a sign-off's "paths" gets, so "what this check covers" means one
+ * thing in verify.json. Null when git cannot answer: a caller then runs the
+ * check rather than reading "nothing changed" out of a question it never
+ * got to ask.
+ *
+ * @param {string} projectRoot
+ * @param {string[]} paths
+ * @returns {string[] | null}
+ */
+export function workingChanges(projectRoot, paths) {
+  const tracked = git(projectRoot, ["diff", "--name-only", "HEAD", "--", ...paths]);
+  // No commit yet: every file is new, so what is staged counts as changed.
+  const staged = tracked.state === GIT_STATE.EMPTY
+    ? git(projectRoot, ["ls-files", "--cached", "--", ...paths])
+    : tracked;
+  if (staged.state !== GIT_STATE.OK) return null;
+  const untracked = git(projectRoot, ["ls-files", "--others", "--exclude-standard", "--", ...paths]);
+  if (untracked.state !== GIT_STATE.OK) return null;
+  return [...new Set([...staged.lines, ...untracked.lines].filter(Boolean))].sort();
+}
+
 /** The commit a signature is anchored to, or null outside a repository. */
 export function currentSha(projectRoot) {
   const r = git(projectRoot, ["rev-parse", "HEAD"]);

package/src/lib/skill-candidates.js

@@ -0,0 +1,162 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read, walk } from "./fs-ops.js";
+import { git, GIT_STATE } from "./git.js";
+import { FIX_SHAPED, FIX_SHAPED_SUBJECT, skillSlug } from "./lexicon.js";
+
+// The lessons worth a skill, as DATA (change 0202). `skill suggest` listed
+// them and `close` printed that whole listing at the end of every close —
+// the same thirteen candidates, close after close, which a field review of
+// 0.17 called noise. The close now asks for the list and renders only what
+// THIS close produced, so the collection lives here, where both read it
+// (ADR 0025: commands render, lib decides).
+
+/**
+ * @typedef {object} SkillCandidate
+ * @property {string} id
+ * @property {string} slug
+ * @property {"change"|"commit"} source
+ * @property {string} [from]  archive folder name, for a change candidate
+ * @property {string} [ref]   short sha, for a commit candidate
+ * @property {string} [why]
+ */
+
+/**
+ * Fix-shaped lessons not yet captured as a skill, from the archive and the
+ * git history, deduped by slug.
+ *
+ * @param {string} projectRoot
+ * @param {{ since?: string, limit?: number }} [opts]
+ * @returns {SkillCandidate[]}
+ */
+export function skillCandidates(projectRoot, { since, limit = 200 } = {}) {
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  const existingFiles = isDir(skillsDir) ? walk(skillsDir).filter((f) => f.endsWith(".md")) : [];
+  const existing = new Set(existingFiles.map((f) => path.basename(f, ".md")));
+  // A lesson may already be captured under a DIFFERENT slug (0.11.0 field
+  // review item 11: the human names the skill after the lesson, not after the
+  // change id — "tela-preta-crash-de-render..." for change 0049). Two extra
+  // dedup signals: an existing skill whose body cites the candidate's change
+  // id / commit hash, and token-overlap similarity between the slugs.
+  const existingBodies = existingFiles.map((f) => ({ slug: path.basename(f, ".md"), body: read(f) }));
+  const captured = (cand) => {
+    if (existing.has(cand.slug)) return true;
+    for (const sk of existingBodies) {
+      if (cand.id && sk.body.includes(cand.id)) return true;
+      if (cand.from && sk.body.includes(cand.from)) return true;
+      if (slugSimilarity(cand.slug, sk.slug) >= 0.5) return true;
+    }
+    return false;
+  };
+
+  // Two deterministic sources, deduped by slug. `seen` guards against a lesson
+  // appearing twice (e.g. a fix committed and later archived as a change).
+  /** @type {SkillCandidate[]} */
+  const candidates = [];
+  const seen = new Set();
+
+  // Source 1 — archived change proposals with a fix-shaped folder name.
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
+  if (isDir(archiveDir)) {
+    for (const name of readdirSync(archiveDir).sort()) {
+      if (!isDir(path.join(archiveDir, name))) continue;
+      const id = name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
+      if (!FIX_SHAPED.test(id)) continue;
+      const slug = skillSlug(id);
+      if (seen.has(slug)) continue;
+      /** @type {SkillCandidate} */
+      const cand = { id, slug, source: "change", from: name };
+      if (captured(cand)) continue; // captured (any slug) or cited by an existing skill
+      const proposal = path.join(archiveDir, name, "proposal.md");
+      cand.why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
+      seen.add(slug);
+      candidates.push(cand);
+    }
+  }
+
+  // Source 2 — fix-shaped commits in the git history (ADR 0013). Archive wins a
+  // slug collision: a `## Why` paragraph is a richer seed than a subject line.
+  for (const cand of gitFixCommits(projectRoot, { since, limit })) {
+    if (seen.has(cand.slug) || captured(cand)) continue;
+    seen.add(cand.slug);
+    candidates.push(cand);
+  }
+
+  return candidates;
+}
+
+// Source 2 for `skill suggest`: fix-shaped commits in the git history (ADR
+// 0013). Deterministic — a regex on the subject, never a read of the diff
+// (ADR 0005 semantic-fidelity ceiling). Returns [] silently when this is not a
+// git repo, git is absent, or the --since ref is unknown, so the command
+// degrades to archive-only rather than erroring.
+function gitFixCommits(projectRoot, { since, limit }) {
+  // US (0x1f) between fields, RS (0x1e) between records — robust against any
+  // newline or punctuation inside a subject or body.
+  const format = "%H%x1f%s%x1f%b%x1e";
+  const args = ["log", "--no-merges", `--format=${format}`];
+  if (since) args.push(`${since}..HEAD`);
+  else args.push("-n", String(limit));
+
+  const r = git(projectRoot, args);
+  if (r.state !== GIT_STATE.OK || !r.stdout) return [];
+
+  /** @type {SkillCandidate[]} */
+  const out = [];
+  const seen = new Set();
+  for (const record of r.stdout.split("\x1e")) {
+    const [sha, subject = "", body = ""] = record.replace(/^\r?\n/, "").split("\x1f");
+    if (!sha || !sha.trim()) continue;
+    if (!FIX_SHAPED_SUBJECT.test(subject)) continue;
+    const slug = commitSlug(subject);
+    if (!slug || seen.has(slug)) continue; // first commit wins a duplicate lesson
+    seen.add(slug);
+    const firstBodyLine = body.split(/\r?\n/).map((l) => l.trim()).find(Boolean) ?? "";
+    out.push({
+      id: slug,
+      slug,
+      source: "commit",
+      ref: sha.trim().slice(0, 9),
+      why: subject.trim() + (firstBodyLine ? ` — ${firstBodyLine}` : ""),
+    });
+  }
+  return out;
+}
+
+// Derive a skill slug from a commit subject: drop a conventional-commit
+// "type(scope): " prefix and hand the rest to the shared slug, which folds.
+function commitSlug(subject) {
+  return skillSlug(subject.replace(/^[a-z]+(?:\([^)]*\))?!?\s*:\s*/i, ""));
+}
+
+// Token-overlap similarity between two kebab slugs (Jaccard over meaningful
+// tokens). "0049-fix-tela-preta-render" vs "tela-preta-crash-de-render-sem-
+// error-boundary" share tela/preta/render → high overlap even though the
+// human renamed the skill after the lesson. Deterministic; never semantic.
+function slugSimilarity(a, b) {
+  const toks = (s) => new Set(
+    String(s).split("-").filter((t) => t.length >= 3 && !/^\d+$/.test(t) && !SLUG_NOISE.has(t)),
+  );
+  const A = toks(a);
+  const B = toks(b);
+  if (A.size === 0 || B.size === 0) return 0;
+  let inter = 0;
+  for (const t of A) if (B.has(t)) inter += 1;
+  return inter / (A.size + B.size - inter);
+}
+
+// Fix-shaped verbs and connectives carry no lesson identity — without this,
+// every "fix-..." candidate looks 30% similar to every "fix-..." skill.
+const SLUG_NOISE = new Set([
+  "fix", "bug", "hotfix", "patch", "the", "and", "for", "with", "sem", "com",
+  "que", "nao", "por", "para", "una", "uma", "dos", "das",
+]);
+
+function firstWhyLine(proposalText) {
+  const m = proposalText.match(/##\s*Why\s*\r?\n+([^\r\n][^\r\n]*)/i);
+  if (!m) return "";
+  const line = m[1].trim();
+  return /^<!--/.test(line) ? "" : line;
+}
+

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,9 @@ 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";
+import { today } from "./dates.js";
 
 // ONE collector, several views (audit finding F7).
 //
@@ -57,7 +61,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,
@@ -146,11 +150,47 @@ export function openChanges(projectRoot) {
     const tasksTotal = progress.total;
     const tasksDone = progress.done;
     const unchecked = progress.open.map((t) => t || "(unwritten task — the scaffold's placeholder)");
-    out.push({ id, title, status, tasksDone, tasksTotal, unchecked });
+    const date = proposal ? (listHeader(proposal, "Date") ?? null) : null;
+    out.push({ id, title, status, tasksDone, tasksTotal, unchecked, date, ageDays: ageInDays(date) });
   }
   return out;
 }
 
+// How old a change has to be before "still open" is worth saying on its own.
+export const STALE_CHANGE_DAYS = 7;
+
+/**
+ * The open changes worth a line at the end of someone else's close (change
+ * 0201): a change that LOOKS finished — applied, or every task ticked — and
+ * was never closed, and a change open for a week or more. A field review of
+ * 0.17 found change 0078 shipped and left open, and no later close said so:
+ * the close is the moment someone is looking, so it is where to say it.
+ *
+ * @param {string} projectRoot
+ * @param {{ exclude?: string[] }} [opts]
+ */
+export function unfinishedChanges(projectRoot, { exclude = [] } = {}) {
+  const skip = new Set(exclude);
+  const out = [];
+  for (const ch of openChanges(projectRoot)) {
+    if (skip.has(ch.id)) continue;
+    const finished = ch.status === "applied" ||
+      (ch.tasksTotal > 0 && ch.tasksDone === ch.tasksTotal);
+    const old = ch.ageDays !== null && ch.ageDays >= STALE_CHANGE_DAYS;
+    const reason = ch.status === "applied"
+      ? "applied but never closed"
+      : finished ? "every task ticked, never closed" : old ? "still open" : null;
+    out.push({ ...ch, finished, old, reason });
+  }
+  return out;
+}
+
+function ageInDays(date) {
+  if (!date || !/^\d{4}-\d{2}-\d{2}$/.test(date)) return null;
+  const ms = Date.parse(`${today()}T00:00:00Z`) - Date.parse(`${date}T00:00:00Z`);
+  return Number.isFinite(ms) ? Math.max(0, Math.round(ms / 86400000)) : null;
+}
+
 function countSpecs(projectRoot) {
   const specsDir = path.join(projectRoot, ".doctrina", "specs");
   const impl = {};
@@ -207,3 +247,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`),
+  };
+}