doctrina-cli 0.6.0 → 0.9.0

package/src/commands/skill.js

@@ -1,14 +1,16 @@
 import path from "node:path";
 import process from "node:process";
-import { exists, isDir, mkdirp, read, relPath, walk, write } from "../lib/fs-ops.js";
+import { readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { exists, isDir, isFile, mkdirp, read, relPath, walk, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
-import { flagBool } from "../lib/args.js";
+import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
-const SUBCOMMANDS = ["new", "list", "sync"];
+const SUBCOMMANDS = ["new", "list", "sync", "suggest"];
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -22,9 +24,205 @@ export async function run(positional, flags) {
   }
   if (sub === "new") return skillNew(positional.slice(1), flags);
   if (sub === "sync") return skillSync();
+  if (sub === "suggest") return skillSuggest(positional.slice(1), flags);
   return skillList();
 }
 
+// Surface (and optionally scaffold) skills worth capturing (review 2026-06-27
+// passive-user feature #6). A skill exists so a hard-won lesson is not relearned
+// by the next agent/session; the framework otherwise never pulls you toward
+// writing one. `skill suggest` scans for fix-shaped work — the textbook case for
+// a skill — from two deterministic sources and lists candidates whose lesson is
+// not yet captured: archived change proposals, and the git commit history
+// (ADR 0013). The archive only fills if a team runs the `doctrina change`
+// lifecycle, so without the git source `suggest` is inert in most repos. With
+// --write it scaffolds a stub per candidate, pre-seeded from the source so the
+// human/agent only fills the body. Both sources are a pattern match — a hint,
+// never a decision (ADR 0005); skills are still authored, never generated.
+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 deliberate folder slug tolerates more noise than a free-form
+// subject line. Matches conventional fix-type prefixes (fix:, fix(scope):,
+// bug:, hotfix:, patch:, and the free-form "Fix the…") plus the strongly
+// fix-flavoured debugging keywords — never feat:/refactor:/docs:/chore:.
+const FIX_SHAPED_SUBJECT =
+  /^(?:fix|bug|hotfix|patch)\b|\b(?:tolerate|workaround|deadlock|flaky|race condition|retry|sanitiz|sanitis)/i;
+
+// How far back the git source looks when --since is not given, and how many
+// candidates we print before collapsing the rest into a "+N more" line.
+const GIT_LOG_LIMIT = 200;
+const MAX_SHOWN = 20;
+
+function skillSuggest(args, flags) {
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  const doWrite = flagBool(flags, "write", false);
+  const since = flagString(flags, "since");
+
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  const existing = new Set(
+    isDir(skillsDir) ? walk(skillsDir).filter((f) => f.endsWith(".md")).map((f) => path.basename(f, ".md")) : [],
+  );
+
+  // Two deterministic sources, deduped by slug. `seen` guards against a lesson
+  // appearing twice (e.g. a fix committed and later archived as a change).
+  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 (existing.has(slug) || seen.has(slug)) continue; // captured or already queued
+      const proposal = path.join(archiveDir, name, "proposal.md");
+      const why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
+      seen.add(slug);
+      candidates.push({ id, slug, why, source: "change", from: name });
+    }
+  }
+
+  // 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: GIT_LOG_LIMIT })) {
+    if (existing.has(cand.slug) || seen.has(cand.slug)) continue;
+    seen.add(cand.slug);
+    candidates.push(cand);
+  }
+
+  if (candidates.length === 0) {
+    console.log(c.gray("no uncaptured fix-shaped lessons found in .doctrina/changes/archive/ or the git history"));
+    console.log(c.gray("(scans archived changes and fix-shaped commits — pass --since <ref> to widen the git window;"));
+    console.log(c.gray(" skills are written by humans, so this only surfaces candidates — `doctrina skill new <slug>` to author one)"));
+    return 0;
+  }
+
+  if (!doWrite) {
+    console.log(c.bold("Skill candidates") + c.gray(" — fix-shaped lessons not yet captured:"));
+    console.log("");
+    for (const cand of candidates.slice(0, MAX_SHOWN)) {
+      console.log(`  ${c.cyan(cand.slug.padEnd(28))} ${c.gray(provenance(cand))}`);
+      if (cand.why) console.log(`    ${c.gray(cand.why.slice(0, 90))}`);
+    }
+    const hidden = candidates.length - MAX_SHOWN;
+    if (hidden > 0) console.log(c.gray(`  … +${hidden} more`));
+    console.log("");
+    console.log(c.gray(`${candidates.length} candidate${candidates.length === 1 ? "" : "s"}. Scaffold them: `) + c.cyan("doctrina skill suggest --write"));
+    return 0;
+  }
+
+  // --write: scaffold a stub per candidate, pre-seeded from its source.
+  const templatesDir = locateTemplatesDir();
+  const tplPath = path.join(templatesDir, "skill.md.template");
+  const tpl = read(tplPath);
+  mkdirp(skillsDir);
+  const index = idx.load(projectRoot);
+  const date = today();
+  let created = 0;
+  for (const cand of candidates) {
+    const target = path.join(skillsDir, `${cand.slug}.md`);
+    if (exists(target)) {
+      console.log(c.yellow("skip   ") + ` ${cand.slug} (already exists)`);
+      continue;
+    }
+    let body = substitute(tpl, { SKILL_NAME: cand.slug });
+    if (cand.why) {
+      // Drop the originating lesson into the body so authoring is "fill", not "start".
+      body += `\n<!-- ${seedLabel(cand)}. The lesson to capture:\n${cand.why}\n-->\n`;
+    }
+    write(target, body, { force: false });
+    idx.addSkill(index, {
+      id: cand.slug,
+      path: `.doctrina/skills/${cand.slug}.md`,
+      description: parseFrontmatter(body, "description") ?? "<edit me — one-sentence summary>",
+      last_updated: date,
+    });
+    console.log(c.green("created") + ` ${relPath(projectRoot, target)}`);
+    created += 1;
+  }
+  if (created > 0) {
+    idx.touch(index, date);
+    idx.save(projectRoot, index);
+  }
+  console.log("");
+  console.log(c.green("ok") + ` scaffolded ${created} skill stub${created === 1 ? "" : "s"} — fill the description/when/body, then \`doctrina skill sync\``);
+  return 0;
+}
+
+// One-line origin shown next to a candidate slug.
+function provenance(cand) {
+  return cand.source === "commit" ? `from commit ${cand.ref}` : `from ${cand.from}`;
+}
+
+// The label seeded into a scaffolded skill body so the author knows where the
+// lesson came from.
+function seedLabel(cand) {
+  return cand.source === "commit"
+    ? `Candidate from commit ${cand.ref}`
+    : `Candidate from change "${cand.id}"`;
+}
+
+// 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 = spawnSync("git", args, { cwd: projectRoot, encoding: "utf8" });
+  if (r.error || r.status !== 0 || !r.stdout) return [];
+
+  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, then reuse skillSlug for the lowercase/hyphenate/cap.
+function commitSlug(subject) {
+  const stripped = subject.replace(/^[a-z]+(?:\([^)]*\))?!?\s*:\s*/i, "");
+  return skillSlug(stripped.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""));
+}
+
+function skillSlug(id) {
+  // Reuse the change id as the skill slug, trimmed to a sane length.
+  const slug = id.replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug.length > 40 ? slug.slice(0, 40).replace(/-+$/g, "") : (slug || "lesson");
+}
+
+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;
+}
+
 function skillNew(args, flags) {
   const name = args[0];
   if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) {
@@ -176,6 +374,13 @@ Subcommands:
   sync          Copy each skill's frontmatter description into
                 .doctrina/index.json so the index never drifts
                 from the frontmatter (single source of truth).
+  suggest [--write] [--since <ref>]
+                Surface fix-shaped lessons not yet captured as skills,
+                from two sources: archived change proposals and the git
+                commit history (ADR 0013). --write scaffolds a stub per
+                candidate (pre-seeded from its source) to fill in.
+                --since <ref> scans commits in <ref>..HEAD instead of the
+                last 200 (e.g. --since v0.7.0).
 
 Skills are written by humans, not generated. See docs/en/skills.md
 for the design rationale and the distinction from specs / AGENTS.md /

package/src/commands/status.js

@@ -0,0 +1,178 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read, walk } from "../lib/fs-ops.js";
+import * as idx from "../lib/index-json.js";
+import { deriveIndex, indexesMatch, specHeader, listHeader } from "../lib/scan.js";
+import { cliVersion } from "../lib/version.js";
+import { summarize as coverageSummary } from "./coverage.js";
+import { summarize as traceSummary } from "./trace.js";
+import { c } from "../lib/colors.js";
+
+// One-glance project health (review 2026-06-27 passive-user feature #1): a
+// dashboard that answers "where do things stand?" in a single read, so neither
+// the human nor the agent has to run validate + coverage + trace + next
+// separately. Strictly read-only; never mutates and always exits 0. It reports
+// the gate signals it can compute cheaply (index drift, the framework stamp,
+// coverage/trace ratios, whether verify is configured) and the artifact counts;
+// `doctrina validate` / `verify` remain the full, authoritative gates.
+
+const CONFIG_REL = ".doctrina/verify.json";
+
+export async function run(_positional, _flags) {
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+
+  let index = null;
+  try {
+    index = idx.load(projectRoot);
+  } catch {
+    index = null;
+  }
+
+  const project = index?.project ?? path.basename(projectRoot);
+  const stamp = index?.framework_version ?? "—";
+  const cli = cliVersion();
+  console.log(c.bold("Doctrina status") + c.gray(` — ${project}  (framework ${stamp} / CLI ${cli})`));
+  console.log("");
+
+  // --- Gates ---
+  console.log(c.bold("  Gates"));
+  // Index drift (the silent rot validate now errors on).
+  let driftLine;
+  if (!index) {
+    driftLine = c.red("missing/unreadable") + c.gray(" — run `doctrina index rebuild`");
+  } else if (indexesMatch(deriveIndex(projectRoot, index), index)) {
+    driftLine = c.green("in sync");
+  } else {
+    driftLine = c.yellow("drifted") + c.gray(" — run `doctrina validate --fix`");
+  }
+  console.log(`    ${"index".padEnd(11)} ${driftLine}`);
+
+  // Framework stamp divergence.
+  const stampLine = stamp === cli
+    ? c.green("current")
+    : c.yellow(`${stamp} (CLI ${cli})`) + c.gray(" — `doctrina index rebuild`");
+  console.log(`    ${"stamp".padEnd(11)} ${stampLine}`);
+
+  // Coverage and trace ratios.
+  const cov = coverageSummary(projectRoot);
+  const covExtra = cov.totalDangling + cov.totalConditional > 0
+    ? c.yellow(` ${cov.totalDangling} dangling, ${cov.totalConditional} conditional`)
+    : "";
+  const covColor = cov.pct === 100 ? c.green : cov.pct >= 50 ? c.yellow : c.red;
+  console.log(`    ${"coverage".padEnd(11)} ${covColor(`${cov.pct}%`)} ${c.gray(`(${cov.totalCovered}/${cov.totalCriteria} criteria)`)}${covExtra}`);
+
+  const tr = traceSummary(projectRoot);
+  const trExtra = tr.untraceable + tr.dropped + tr.dangling > 0
+    ? c.yellow(` ${tr.dropped} dropped, ${tr.untraceable} untraceable`)
+    : "";
+  const trColor = tr.anchors === 0 ? c.gray : (tr.realized === tr.anchors && tr.untraceable === 0 ? c.green : c.yellow);
+  const trText = tr.anchors === 0 ? "no anchors" : `${tr.realized}/${tr.anchors} anchors`;
+  console.log(`    ${"trace".padEnd(11)} ${trColor(trText)}${trExtra}`);
+
+  // Verify config presence (running it is the slow, authoritative gate).
+  const verifyCfg = path.join(projectRoot, CONFIG_REL);
+  let verifyLine = c.gray("not configured") + c.gray(" — `doctrina verify --init`");
+  if (isFile(verifyCfg)) {
+    try {
+      const cfg = JSON.parse(read(verifyCfg));
+      const n = Array.isArray(cfg?.checks) ? cfg.checks.length : 0;
+      verifyLine = c.cyan(`${n} check${n === 1 ? "" : "s"}`) + c.gray(" — run `doctrina verify`");
+    } catch {
+      verifyLine = c.red("invalid JSON");
+    }
+  }
+  console.log(`    ${"verify".padEnd(11)} ${verifyLine}`);
+
+  // --- Work ---
+  console.log("");
+  console.log(c.bold("  Work"));
+  const specs = countSpecs(projectRoot);
+  const implBreak = Object.entries(specs.impl).map(([k, v]) => `${v} ${k}`).join(", ");
+  console.log(`    ${"specs".padEnd(11)} ${specs.total}${implBreak ? c.gray(`  (${implBreak})`) : ""}`);
+  console.log(`    ${"changes".padEnd(11)} ${specs.openChanges} open`);
+  const adr = countDecisions(projectRoot);
+  const adrNotes = [];
+  if (adr.proposed > 0) adrNotes.push(c.yellow(`${adr.proposed} proposed`));
+  if (adr.bare > 0) adrNotes.push(c.yellow(`${adr.bare} unproven`));
+  console.log(`    ${"decisions".padEnd(11)} ${adr.total}${adrNotes.length ? c.gray("  (") + adrNotes.join(c.gray(", ")) + c.gray(")") : ""}`);
+  const skills = countSkills(projectRoot);
+  console.log(`    ${"skills".padEnd(11)} ${skills}`);
+
+  console.log("");
+  console.log(c.gray("  Full gates: `doctrina validate` · `doctrina verify`.  Next step: `doctrina next`."));
+  return 0;
+}
+
+function countSpecs(projectRoot) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const impl = {};
+  let total = 0;
+  if (isDir(specsDir)) {
+    for (const cap of readdirSync(specsDir).sort()) {
+      const p = path.join(specsDir, cap, "spec.md");
+      if (!isFile(p)) continue;
+      total += 1;
+      const implRaw = specHeader(read(p), "Implementation");
+      if (implRaw) {
+        const word = implRaw.trim().split(/[\s—-]+/)[0].toLowerCase();
+        impl[word] = (impl[word] ?? 0) + 1;
+      }
+    }
+  }
+  const changesDir = path.join(projectRoot, ".doctrina", "changes");
+  let openChanges = 0;
+  if (isDir(changesDir)) {
+    for (const e of readdirSync(changesDir)) {
+      if (e === "archive" || e.startsWith(".")) continue;
+      if (isDir(path.join(changesDir, e))) openChanges += 1;
+    }
+  }
+  return { total, impl, openChanges };
+}
+
+function countDecisions(projectRoot) {
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  let total = 0, proposed = 0, bare = 0;
+  const isBare = (v) => {
+    const t = (v ?? "").trim();
+    return t === "" || t === "—" || t === "-";
+  };
+  if (isDir(adrDir)) {
+    for (const f of walk(adrDir)) {
+      if (!/^\d{4}-.+\.md$/.test(path.basename(f))) continue;
+      total += 1;
+      const text = read(f);
+      const status = (listHeader(text, "Status") ?? "").toLowerCase();
+      if (status === "proposed") proposed += 1;
+      if (status === "accepted") {
+        const evidence = listHeader(text, "Evidence");
+        const landed = listHeader(text, "Landed");
+        if (evidence !== null && isBare(evidence) && isBare(landed)) bare += 1;
+      }
+    }
+  }
+  return { total, proposed, bare };
+}
+
+function countSkills(projectRoot) {
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  if (!isDir(skillsDir)) return 0;
+  return walk(skillsDir).filter((f) => f.endsWith(".md")).length;
+}
+
+export const help = `
+Usage: doctrina status
+
+Print a one-glance health dashboard for the .doctrina/ project: the gate
+signals (index drift, framework stamp, coverage %, trace anchors, whether
+verify is configured) and the artifact counts (specs by implementation
+state, open changes, decisions, skills). Read-only; always exits 0.
+
+It is a fast summary, not the authoritative gate: run \`doctrina validate\`
+and \`doctrina verify\` for the full structural and build checks, and
+\`doctrina next\` for the recommended next action.
+`;

package/src/commands/trace.js

@@ -106,6 +106,37 @@ export async function run(_positional, flags) {
   return strict ? 1 : 0;
 }
 
+// Pure summary of intent provenance, for other commands (`status`, `review`)
+// that need the numbers without the report output.
+export function summarize(projectRoot) {
+  const anchors = collectAnchors(projectRoot);
+  const specs = collectSpecs(projectRoot);
+  const anchorIds = new Set(anchors.map((a) => a.id));
+  const realizedBy = new Map();
+  let dangling = 0;
+  for (const s of specs) {
+    if (s.realizes === null) continue;
+    for (const id of s.realizes) {
+      if (anchorIds.has(id)) {
+        if (!realizedBy.has(id)) realizedBy.set(id, []);
+        realizedBy.get(id).push(s.cap);
+      } else {
+        dangling += 1;
+      }
+    }
+  }
+  const untraceable = specs.filter((s) => s.realizes === null && s.status === "active").length;
+  let realized = 0;
+  for (const a of anchors) if ((realizedBy.get(a.id) ?? []).length > 0) realized += 1;
+  return {
+    anchors: anchors.length,
+    realized,
+    dropped: anchors.length - realized,
+    dangling,
+    untraceable,
+  };
+}
+
 // Every "[A-Z]+\d+" tag at the head of a bullet in product.md is an intent
 // anchor. Section-agnostic so Success-criteria and In-scope bullets both work.
 function collectAnchors(projectRoot) {

package/src/commands/validate.js

@@ -266,6 +266,27 @@ export async function run(_positional, flags) {
           }
         }
 
+        // 8e. Provenance adoption (review 2026-06-27, §5/§9). `trace` is the
+        //     intent→capability link, but it stays inert when nothing forces
+        //     the tag, so an active capability with no Realizes: header is an
+        //     untraced promise — warn here (validate is always run) rather than
+        //     only in the opt-in `trace`. Advisory, with the same escape hatch
+        //     pattern as Implementation: any value silences it, including a
+        //     deliberate "n/a — <why>" for an internal capability that maps to
+        //     no product anchor. Bug specs (off the implementation axis) and
+        //     draft/deprecated documents are exempt — only active capability
+        //     specs make the promise.
+        const docStatusForRealizes = (specHeader(text, "Status") ?? "active").toLowerCase();
+        const onImplAxis = specHeader(text, "Implementation") !== null;
+        if (docStatusForRealizes === "active" && onImplAxis && specHeader(text, "Realizes") === null) {
+          warnings.push(
+            `${relPath(projectRoot, specPath)}: active spec has no Realizes: header — ` +
+              `it traces to no product intent (\`doctrina trace\`). Tag a product.md ` +
+              `success-criteria bullet "- [SC1] ..." and add "**Realizes:** SC1", or ` +
+              `record "**Realizes:** n/a — <why>" if it maps to no product anchor`,
+          );
+        }
+
         // 8d. Metadata-header shape (review G11). In the header block (before
         //     the first `## ` section or `<!--` comment), a known key written
         //     without the canonical `**Key:** value` form silently fails to

package/src/commands/verify.js

@@ -3,7 +3,8 @@ import process from "node:process";
 import { readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { exists, isDir, isFile, read, write, relPath } from "../lib/fs-ops.js";
-import { flagBool } from "../lib/args.js";
+import { flagBool, flagString } from "../lib/args.js";
+import { today } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
 
 // The build/verify gate `validate` is not. `validate` checks the shape of
@@ -15,6 +16,7 @@ import { c } from "../lib/colors.js";
 // `.doctrina/verify.json`, and `verify` runs exactly that, in order.
 
 const CONFIG_REL = ".doctrina/verify.json";
+const SIGNOFF_REL = ".doctrina/verify.signoffs.json";
 
 const STARTER = {
   $comment:
@@ -80,8 +82,11 @@ export async function run(_positional, flags) {
     return 1;
   }
   for (const ch of checks) {
-    if (!ch || typeof ch.run !== "string" || ch.run.trim() === "") {
-      console.error(c.red("error:") + ` every check in ${CONFIG_REL} needs a non-empty "run" string`);
+    // A "manual" check is the qualitative gate (review 2026-06-27 feature #7):
+    // a DoD item judged by a human/eval, recorded as a sign-off, not run as a
+    // command — so it needs no `run`. Every other check still needs one.
+    if (!ch || (ch.type !== "manual" && (typeof ch.run !== "string" || ch.run.trim() === ""))) {
+      console.error(c.red("error:") + ` every check in ${CONFIG_REL} needs a non-empty "run" string (or "type": "manual")`);
       return 1;
     }
   }
@@ -90,21 +95,69 @@ export async function run(_positional, flags) {
     return 1;
   }
 
+  // Sign-off store for manual checks: { "<check name>": { date, note } }.
+  const signoffPath = path.join(projectRoot, SIGNOFF_REL);
+  let signoffs = {};
+  if (isFile(signoffPath)) {
+    try { signoffs = JSON.parse(read(signoffPath)) ?? {}; } catch { signoffs = {}; }
+  }
+
+  // --signoff "<name>=<note>" records a manual check's human/eval sign-off
+  // (date stamped today) and exits. The name must be a declared manual check.
+  const signoffArg = flagString(flags, "signoff");
+  if (signoffArg !== undefined) {
+    const eq = String(signoffArg).indexOf("=");
+    const name = (eq >= 0 ? signoffArg.slice(0, eq) : signoffArg).trim();
+    const note = eq >= 0 ? signoffArg.slice(eq + 1).trim() : "";
+    const target = checks.find((ch) => (ch.name ?? "") === name && ch.type === "manual");
+    if (!target) {
+      console.error(c.red("error:") + ` no manual check named "${name}" in ${CONFIG_REL}`);
+      const manualNames = checks.filter((ch) => ch.type === "manual").map((ch) => ch.name);
+      console.error(c.gray("hint: ") + (manualNames.length
+        ? `manual checks: ${manualNames.join(", ")}`
+        : `add one: { "name": "${name || "quality"}", "type": "manual", "rubric": "<the question>" }`));
+      return 1;
+    }
+    signoffs[name] = { date: today(), note };
+    write(signoffPath, JSON.stringify(signoffs, null, 2) + "\n", { force: true });
+    console.log(c.green("signed off") + ` ${name} on ${today()}${note ? `: ${note}` : ""}`);
+    return 0;
+  }
+
   // --list prints the configured checks without running them.
   if (flagBool(flags, "list", false)) {
     console.log(c.bold("Verify checks") + c.gray(` (from ${CONFIG_REL}):`));
     console.log("");
     checks.forEach((ch, i) => {
-      console.log(`  ${i + 1}. ${c.cyan((ch.name ?? "check").padEnd(16))} ${c.gray(ch.run)}`);
+      const what = ch.type === "manual" ? c.gray(`manual${ch.rubric ? " — " + ch.rubric : ""}`) : c.gray(ch.run);
+      console.log(`  ${i + 1}. ${c.cyan((ch.name ?? "check").padEnd(16))} ${what}`);
     });
     return 0;
   }
 
+  const strict = flagBool(flags, "strict", false);
   console.log(c.bold("doctrina verify") + c.gray(` — ${checks.length} check${checks.length === 1 ? "" : "s"} from ${CONFIG_REL}`));
   const results = [];
   for (const ch of checks) {
     const name = ch.name ?? "check";
     console.log("");
+
+    // Manual (qualitative) check: pass if signed off, else pending. Pending is
+    // non-blocking by default (a report) and fails only under --strict, so CI
+    // can require the human/eval sign-off without blocking local runs.
+    if (ch.type === "manual") {
+      console.log(c.gray(`──── ${name}: `) + c.gray(`manual${ch.rubric ? " — " + ch.rubric : ""}`));
+      const so = signoffs[name];
+      if (so && so.date) {
+        console.log(c.green(`✓ ${name}`) + c.gray(` — signed off ${so.date}${so.note ? `: ${so.note}` : ""}`));
+        results.push({ name, ok: true, kind: "manual" });
+      } else {
+        console.log(c.yellow(`○ ${name} — pending sign-off`) + c.gray(` (doctrina verify --signoff "${name}=<note>")`));
+        results.push({ name, ok: false, kind: "manual", pending: true });
+      }
+      continue;
+    }
+
     const where = ch.cwd ? c.gray(` [${ch.cwd}]`) : "";
     console.log(c.gray(`──── ${name}: `) + ch.run + where);
     // Run through the shell so declared commands can use pipes, &&, env,
@@ -125,19 +178,28 @@ export async function run(_positional, flags) {
     } else {
       console.log(ok ? c.green(`✓ ${name}`) : c.red(`✗ ${name} (exit ${res.status})`));
     }
-    results.push({ name, ok });
+    results.push({ name, ok, kind: "command" });
     // Fail fast is tempting, but running every check surfaces all breakage
     // in one pass — more useful for an agent fixing the gap.
   }
 
+  const cmdFailed = results.filter((r) => r.kind === "command" && !r.ok);
+  const pending = results.filter((r) => r.pending);
   const passed = results.filter((r) => r.ok).length;
   console.log("");
-  if (passed === results.length) {
-    console.log(c.green("ok") + ` ${passed}/${results.length} checks passed`);
+  // The gate fails on any failed command check, or (only under --strict) any
+  // manual check still awaiting sign-off. Pending manual checks are otherwise
+  // a non-blocking report.
+  const failGate = cmdFailed.length > 0 || (strict && pending.length > 0);
+  const pendNote = pending.length > 0 ? c.gray(` (${pending.length} manual pending)`) : "";
+  if (!failGate) {
+    console.log(c.green("ok") + ` ${passed}/${results.length} checks passed${pendNote}`);
     return 0;
   }
-  const failed = results.filter((r) => !r.ok).map((r) => r.name).join(", ");
-  console.log(c.red("fail") + ` ${passed}/${results.length} checks passed — failed: ${failed}`);
+  const reasons = [];
+  if (cmdFailed.length > 0) reasons.push(`failed: ${cmdFailed.map((r) => r.name).join(", ")}`);
+  if (strict && pending.length > 0) reasons.push(`pending sign-off: ${pending.map((r) => r.name).join(", ")}`);
+  console.log(c.red("fail") + ` ${passed}/${results.length} checks passed — ${reasons.join("; ")}`);
   return 1;
 }
 
@@ -276,22 +338,28 @@ function findPackageJsons(projectRoot) {
 }
 
 export const help = `
-Usage: doctrina verify [--list] [--init] [--clean] [--force]
+Usage: doctrina verify [--list] [--init] [--clean] [--strict] [--signoff "<name>=<note>"] [--force]
 
 Run the project-declared build/verify checks from ${CONFIG_REL} in order,
 streaming their output, and exit non-zero if any check fails. This is the
 real "does the code work" gate, separate from the structural \`validate\`.
 
 ${CONFIG_REL} shape (an optional per-check "cwd", relative to the project
-root, targets a sub-package in a monorepo):
+root, targets a sub-package in a monorepo; a "manual" check is the
+qualitative gate — judged by a human/eval, recorded as a sign-off, not run):
   {
     "checks": [
       { "name": "typecheck", "run": "tsc --noEmit", "cwd": "packages/api" },
       { "name": "test",      "run": "npm test" },
-      { "name": "build",     "run": "npm run build" }
+      { "name": "build",     "run": "npm run build" },
+      { "name": "chronicle", "type": "manual", "rubric": "is the chronicle enjoyable to read?" }
     ]
   }
 
+A manual check passes when it has been signed off and is otherwise reported
+as "pending" — non-blocking by default, failing only under --strict (so CI
+can require the sign-off). Sign-offs are stored in ${SIGNOFF_REL}.
+
 Flags:
   --init     Scaffold a starter ${CONFIG_REL} (refuses to overwrite without --force)
   --list     Print the configured checks without running them
@@ -299,5 +367,8 @@ Flags:
              reproducibility footguns (entry points in a build dir with no
              prepare/prepack; a Prisma dep with no generate on install) so
              "verify green" can't hide a clean checkout that won't build.
+  --strict   Fail the gate when a manual check is still pending sign-off
+  --signoff "<name>=<note>"
+             Record today's sign-off for a manual check, then exit
   --force    With --init, overwrite an existing config
 `;