create-religion 1.2.0 → 1.4.0

package/dist/lib/args.js

@@ -7,18 +7,19 @@
  * the wrong place.
  */
 import { ADAPTERS } from "./install.js";
-const COMMANDS = ["install", "update", "status", "doctor", "dashboard", "help"];
+const COMMANDS = ["install", "update", "uninstall", "status", "doctor", "dashboard", "help"];
 const WRITES = new Set(["install", "update"]);
+const CHANGES = new Set(["install", "update", "uninstall"]);
 const REPORTS = new Set(["status", "doctor"]);
 const EVERY = new Set(COMMANDS);
 /** Every option, the commands it applies to, and what it does. Parsing dispatches on this alone. */
 const FLAGS = {
     "--help": { commands: EVERY, apply: (options) => void (options.command = "help") },
     "-h": { commands: EVERY, apply: (options) => void (options.command = "help") },
-    "--dry-run": { commands: WRITES, apply: (options) => void (options.dryRun = true) },
+    "--dry-run": { commands: CHANGES, apply: (options) => void (options.dryRun = true) },
     "--force": { commands: WRITES, apply: (options) => void (options.force = true) },
-    "--yes": { commands: WRITES, apply: (options) => void (options.yes = true) },
-    "-y": { commands: WRITES, apply: (options) => void (options.yes = true) },
+    "--yes": { commands: CHANGES, apply: (options) => void (options.yes = true) },
+    "-y": { commands: CHANGES, apply: (options) => void (options.yes = true) },
     "--json": { commands: REPORTS, apply: (options) => void (options.json = true) },
     ...Object.fromEntries(Object.keys(ADAPTERS).map((adapter) => [
         `--${adapter}`,
@@ -34,6 +35,15 @@ const FLAGS = {
 };
 /** The options each command accepts, read from the same table parsing uses. */
 export const GRAMMAR = grammar();
+/** Every exit code the tool uses, and what each means. Public: a meaning never changes within 1.x. */
+export const EXIT_CODES = {
+    0: "the command did what it was asked",
+    1: "it ran and reports failure: no project found, a failing doctor check,\n" +
+        "conflicts, declined merges or linked files left by install or update,\n" +
+        "a file uninstall meant to change but left, a project installed by a\n" +
+        "newer version, or an unexpected error",
+    2: "usage error: nothing was written"
+};
 function grammar() {
     const table = {};
     for (const command of COMMANDS)
@@ -94,7 +104,7 @@ function unknownCommand(word) {
         ? `Unknown command '${word}'. Did you mean '${closest.command}'?`
         : `Unknown command '${word}', and no directory of that name exists.`;
 }
-function editDistance(a, b) {
+export function editDistance(a, b) {
     let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
     for (let i = 1; i <= a.length; i += 1) {
         const current = [i];

package/dist/lib/changelog.js

@@ -0,0 +1,29 @@
+/**
+ * What changed between two versions, read from the changelog the package ships.
+ *
+ * The format is what Changesets writes: `## 1.2.0` per release, `### Minor Changes` groups,
+ * and `- 6097eb0: text` entries that may run across several lines.
+ */
+import { isNewer } from "./install.js";
+/** Releases after `from`, up to and including `to`, newest first, each change as its first sentence. */
+export function changesSince(changelog, from, to) {
+    if (!changelog || typeof from !== "string")
+        return [];
+    return changelog.split(/^(?=## )/m).flatMap((section) => {
+        const version = /^## (\S+)/.exec(section)?.[1];
+        // A prerelease compares equal to its release, so its notes would be shown twice or never.
+        if (!version || version.includes("-") || !isNewer(version, from) || isNewer(version, to))
+            return [];
+        const changes = section
+            .split(/^- /m)
+            .slice(1)
+            .map((entry) => firstSentence(entry.split(/\n\s*\n|\n(?=#)|\n\s+- /)[0].replace(/\s+/g, " ").replace(/^[0-9a-f]{7,40}: /, "")))
+            .filter(Boolean);
+        return [{ version, changes }];
+    });
+}
+// A full stop ends the sentence only before a capital or a code span, so "e.g. `--yes`" does not.
+function firstSentence(text) {
+    const end = text.search(/(?<!\b(?:e\.g|i\.e|etc|vs))\.(\s+[A-Z`]|$)/);
+    return (end < 0 ? text : text.slice(0, end + 1)).trim();
+}

package/dist/lib/dashboard.js

@@ -7,10 +7,11 @@
 import http from "node:http";
 import path from "node:path";
 import { runDoctor } from "./doctor.js";
-import { readManifest } from "./install.js";
+import { editedSinceInstall, readManifest } from "./install.js";
 import { readIfPresent, statePath } from "./paths.js";
 import { parseInbox, parseSpec, readHistory, readProjectState } from "./state.js";
-import { computeStatus } from "./status.js";
+import { describeSettings } from "./settings.js";
+import { computeStatus, DISTILL_AFTER } from "./status.js";
 /** `version` is the running tool's, shown beside the version that installed the project. */
 export async function startDashboard(root, version = null) {
     let port = 0;
@@ -66,6 +67,7 @@ function send(response, status, type, body) {
 }
 async function readState(root, version) {
     const state = await readProjectState(root);
+    const changes = await editedSinceInstall(root);
     return {
         project: path.basename(root),
         status: computeStatus(state),
@@ -74,10 +76,12 @@ async function readState(root, version) {
         activity: await readActivity(root),
         work: parseSpec(await readIfPresent(statePath(root, "context", "current-work.md"))),
         history: await readHistory(root),
+        learning: { ...state.learning, distillAfter: DISTILL_AFTER },
         health: {
-            checks: await runDoctor(root),
+            checks: await runDoctor(root, changes),
             config: state.config,
-            install: await readInstall(root),
+            settings: describeSettings(state.config),
+            install: await readInstall(root, changes),
             tool: version,
             inbox: parseInbox(await readIfPresent(statePath(root, "context", "inbox.md"))),
             questions: state.openQuestions
@@ -85,7 +89,7 @@ async function readState(root, version) {
     };
 }
 /** The manifest is the project's file and may be hand-edited, so only well-formed parts are shown. */
-async function readInstall(root) {
+async function readInstall(root, changes) {
     const manifest = await readManifest(root);
     if (!manifest || typeof manifest !== "object")
         return null;
@@ -93,7 +97,9 @@ async function readInstall(root) {
     return {
         version: typeof version === "string" ? version : null,
         adapters: Array.isArray(adapters) ? adapters.filter((a) => typeof a === "string") : [],
-        managed: managed && typeof managed === "object" ? Object.keys(managed).length : 0
+        managed: managed && typeof managed === "object" ? Object.keys(managed).length : 0,
+        edited: changes?.edited ?? [],
+        missing: changes?.missing ?? []
     };
 }
 async function readActivity(root) {
@@ -416,13 +422,16 @@ code { font-family: var(--font-mono); font-size: var(--text-xs); background: var
 .view { display: none; scroll-margin-top: 100vh; }
 .view:target, main:not(:has(.view:target)) #overview { display: block; }
 .app:not(:has(.view:target)) .to-overview, .app:has(#overview:target) .to-overview, .app:has(#work:target) .to-work,
-.app:has(#findings:target) .to-findings, .app:has(#history:target) .to-history, .app:has(#health:target) .to-health { background: var(--surface-2); color: var(--text); }
+.app:has(#findings:target) .to-findings, .app:has(#history:target) .to-history, .app:has(#deferred:target) .to-deferred,
+.app:has(#learning:target) .to-learning,
+.app:has(#health:target) .to-health { background: var(--surface-2); color: var(--text); }
 .tile.bad .big { color: var(--block); }
 .checks span { align-items: flex-start; }
 .checks span::before { flex-shrink: 0; margin-top: calc((var(--leading-base) * 1em - var(--dot-size)) / 2); }
 .checks span.bad::before { background: var(--block); }
 .checklist .bad { width: var(--dot-size); height: var(--dot-size); border-radius: 50%; background: var(--block); }
 .callout.bad { color: var(--block); }
+.rows td .bad { color: var(--block); }
 .callout.bad::before { background: var(--block); }
 .live.off { color: var(--block); }
 .live.off::before { background: var(--block); }
@@ -430,6 +439,7 @@ code { font-family: var(--font-mono); font-size: var(--text-xs); background: var
 .empty { margin: 0; color: var(--text-3); font-size: var(--text-sm); }
 button.chip { font-family: inherit; cursor: pointer; }
 [data-pick] { cursor: pointer; }
+.section-label [data-pick] { color: var(--accent); } .section-label [data-pick].sel { text-decoration: underline; }
 .nowrap { white-space: nowrap; }
 :focus-visible { outline: var(--mark-ring) solid var(--accent); outline-offset: var(--space-1); }
 @media (max-width: 900px) {
@@ -446,6 +456,8 @@ button.chip { font-family: inherit; cursor: pointer; }
       <a class="to-work" href="#work">Work <span class="count" id="count-work"></span></a>
       <a class="to-findings" href="#findings">Findings <span class="count" id="count-findings"></span></a>
       <a class="to-history" href="#history">History <span class="count" id="count-history"></span></a>
+      <a class="to-deferred" href="#deferred">Deferred <span class="count" id="count-deferred"></span></a>
+      <a class="to-learning" href="#learning">Learning <span class="count" id="count-learning"></span></a>
       <a class="to-health" href="#health">Health <span class="count" id="count-health"></span></a>
     </div>
     <div class="rail-foot">
@@ -491,6 +503,18 @@ button.chip { font-family: inherit; cursor: pointer; }
         <aside class="panel sticky" id="hs-detail"></aside>
       </div>
     </section>
+    <section class="view" id="deferred">
+      <div class="head"><h1>Deferred</h1><div class="meta"><span>history/</span></div></div>
+      <section class="panel"><header><h2>What each item set aside</h2><a href="#history">Open the chosen item in History</a></header><div class="body" id="df-body"></div></section>
+    </section>
+    <section class="view" id="learning">
+      <div class="head"><h1>Learning</h1><div class="meta"><span>learning/lessons.md</span><span>learning/journal.md</span></div></div>
+      <div class="tiles" id="ln-tiles"></div>
+      <div class="grid">
+        <section class="panel"><header><h2>Lessons</h2><span class="count">loaded every session</span></header><div class="body" id="ln-lessons"></div></section>
+        <section class="panel"><header><h2>Journal</h2><span class="count" id="ln-count"></span></header><div class="body" id="ln-journal"></div></section>
+      </div>
+    </section>
     <section class="view" id="health">
       <div class="head"><h1>Activity and health</h1><div class="meta"><span>religion/.state/</span><span>religion/config.json</span></div></div>
       <div id="hl-notice"></div>
@@ -608,6 +632,8 @@ button.chip { font-family: inherit; cursor: pointer; }
     renderWork();
     renderFindings();
     renderHistory();
+    renderDeferred();
+    renderLearning();
     renderHealth();
   }
 
@@ -619,6 +645,9 @@ button.chip { font-family: inherit; cursor: pointer; }
     $("count-findings").textContent = pending ? String(pending) : "";
     $("count-findings").className = data.status.findings.blocking.length ? "count warn" : "count";
     $("count-history").textContent = data.history.length ? String(data.history.length) : "";
+    const deferred = sum(data.history, (a) => a.deferred.length);
+    $("count-deferred").textContent = deferred ? String(deferred) : "";
+    $("count-learning").textContent = data.learning.undecided ? String(data.learning.undecided) : "";
     $("count-health").textContent = passing + "/" + data.health.checks.length;
     $("count-health").className = passing < data.health.checks.length ? "count warn" : "count";
   }
@@ -631,7 +660,7 @@ button.chip { font-family: inherit; cursor: pointer; }
     const closed = sum(data.history, (a) => a.findings.filter((f) => f.status === "closed").length);
     $("ov-meta").innerHTML = "<span>" + esc(setting("git", "mode", "trunk")) + " mode</span><span>review " + esc(setting("workflow", "stepReview", "every")) + "</span>";
     $("ov-tiles").innerHTML =
-      tile("Plan", s.plan.done + "<small> / " + s.plan.total + " items</small>", s.plan.nextItem ? "Next: " + esc(short(s.plan.nextItem)) : s.plan.total ? "Complete" : "No items yet", bar([[s.plan.done, "--ok"]], s.plan.total)) +
+      tile("Plan", s.plan.done + "<small> / " + s.plan.total + " items</small>", s.plan.nextItem ? "Next: " + esc(short(s.plan.nextItem)) : !s.plan.total ? "No items yet" : s.plan.done === s.plan.total ? "Complete" : "Every remaining item waits", bar([[s.plan.done, "--ok"]], s.plan.total)) +
       (s.work.active
         ? tile("Active item", s.work.stepsDone + "<small> / " + s.work.stepsTotal + " steps</small>", esc(s.work.title || "Untitled"), bar([[s.work.stepsDone, "--progress"]], s.work.stepsTotal))
         : tile("Active item", "None", "Nothing in progress")) +
@@ -703,7 +732,7 @@ button.chip { font-family: inherit; cursor: pointer; }
             (step.doneWhen ? "<p class='when'><b>Done when</b>" + md(step.doneWhen) + "</p>" : "") + "</div>"
           ).join("")
         : "<div class='body'>" + empty("The spec has no build steps yet.") + "</div>") +
-      "</section></div><div class='col'>" +
+      "</section>" + evidencePanel(work.evidence) + "</div><div class='col'>" +
       "<section class='panel'><header><h2>Scope</h2></header><div class='body'><div class='label section-label'>In</div>" + list(work.inScope) + "<div class='label section-label'>Out</div>" + list(work.outOfScope) + "</div></section>" +
       "<section class='panel'><header><h2>Files and areas</h2><span class='count'>" + work.files.length + "</span></header><div class='body'>" + list(work.files) + "</div></section>" +
       "<section class='panel'><header><h2>How it is built</h2></header><div class='body'><dl class='kv'>" +
@@ -715,6 +744,18 @@ button.chip { font-family: inherit; cursor: pointer; }
       "</dl></div></section></div></div>";
   }
 
+  // What check recorded, so the proof is on the page rather than only in a past conversation.
+  function evidencePanel(evidence) {
+    const verdict = { pass: "ok", fail: "bad", "could not check": "bad" };
+    return "<section class='panel'><header><h2>Evidence</h2><span class='count'>" + (evidence && evidence.stamp ? esc(evidence.stamp) : "") + "</span></header><div class='body'>" +
+      (evidence && evidence.entries.length
+        ? "<ul class='checklist'>" + evidence.entries.map((e) =>
+            "<li><span class='" + (verdict[e.verdict] || "bad") + "'></span><span>" + md(e.outcome) + "</span><span class='detail'>" + md(e.detail) + "</span><span class='blocks'>" + esc(e.verdict) + "</span></li>"
+          ).join("") + "</ul>"
+        : empty("Not checked yet. check records here what it observed for each outcome.")) +
+      "</div></section>";
+  }
+
   const STATUS_ORDER = ["open", "fixed", "unverified", "accepted", "closed", "invalid"];
   const idNumber = (f) => Number(String(f.id).slice(2)) || 0;
   const pill = (status) => "<span class='status " + (["open", "fixed", "closed"].indexOf(status) >= 0 ? status : "unverified") + "'>" + esc(status) + "</span>";
@@ -811,7 +852,7 @@ button.chip { font-family: inherit; cursor: pointer; }
     shipped.forEach((a) => (kinds[a.kind] = (kinds[a.kind] || 0) + 1));
     const s = data.status;
     $("hs-tiles").innerHTML =
-      tile("Plan", s.plan.done + "<small> / " + s.plan.total + " items</small>", s.plan.nextItem ? "Next: " + esc(short(s.plan.nextItem)) : s.plan.total ? "Complete" : "No items yet", bar([[s.plan.done, "--ok"]], s.plan.total)) +
+      tile("Plan", s.plan.done + "<small> / " + s.plan.total + " items</small>", s.plan.nextItem ? "Next: " + esc(short(s.plan.nextItem)) : !s.plan.total ? "No items yet" : s.plan.done === s.plan.total ? "Complete" : "Every remaining item waits", bar([[s.plan.done, "--ok"]], s.plan.total)) +
       tile("Shipped", String(shipped.length), shipped.length ? Object.keys(kinds).map((k) => kinds[k] + " " + esc(k)).join(", ") : "Nothing archived yet") +
       tile("Commits", String(commits), shipped.length ? Math.round(commits / shipped.length) + " per item on average" : "None recorded") +
       tile("Repairs", String(sum(shipped, (a) => a.repairs)), "Steps added after an audit") +
@@ -861,13 +902,43 @@ button.chip { font-family: inherit; cursor: pointer; }
     return a[0] - b[0] < 0 || (a[0] === b[0] && (a[1] - b[1] < 0 || (a[1] === b[1] && a[2] < b[2])));
   }
 
-  function flatten(value, prefix, rows) {
-    if (value && typeof value === "object" && !Array.isArray(value)) {
-      Object.keys(value).forEach((k) => flatten(value[k], prefix ? prefix + "." + k : k, rows));
-    } else {
-      rows.push([prefix, typeof value === "string" ? value : JSON.stringify(value)]);
-    }
-    return rows;
+  // A record, not a queue: archives are never edited, so nothing here says whether a note was later done.
+  function renderDeferred() {
+    const left = data.history.filter((a) => a.deferred.length);
+    const total = sum(left, (a) => a.deferred.length);
+    $("df-body").innerHTML = left.length
+      ? "<p class='prose dim'>" + total + " notes from " + left.length + " items, newest first: what each chose to leave, as it stood when the item closed. " +
+        "A note may since have been done; the archive is not changed when it is. Choose an item to open it in History.</p>" +
+        left.map((a) =>
+          "<div class='divider'></div><div class='label section-label'><span tabindex='0' data-pick='archive' data-value='" + esc(a.kind + "/" + a.file) + "'" +
+          (ui.archive === a.kind + "/" + a.file ? " class='sel'" : "") + ">" +
+          esc((a.number ? a.number + ". " : "") + (a.title || a.file)) + "</span> <span class='faint'>" + esc(a.type || a.kind) + "</span></div>" +
+          "<ul class='list'>" + a.deferred.map((d) => "<li>" + md(d) + "</li>").join("") + "</ul>"
+        ).join("")
+      : empty("Nothing deferred yet. complete archives what each item set aside, and it gathers here.");
+  }
+
+  function renderLearning() {
+    const l = data.learning;
+    const due = l.undecided >= l.distillAfter;
+    $("ln-tiles").innerHTML =
+      tile("Lessons", String(l.lessons.length), l.lessons.length ? "Loaded into every session" : "None promoted yet") +
+      tile("Journal", String(l.journal.length), l.journal.length ? "One entry per finished item" : "No entries yet") +
+      tile("Waiting for distill", String(l.undecided), due ? "Enough to be worth a distill pass" : "Too few to group yet", "", due ? "bad" : "");
+    $("ln-lessons").innerHTML = l.lessons.length
+      ? l.lessons.map((lesson) => "<p class='prose'>" + md(lesson) + "</p>").join("")
+      : empty("Nothing learned yet. distill promotes an observation here once it has recurred or been confirmed.");
+    $("ln-count").textContent = l.journal.length ? l.journal.length + " entries, newest first" : "";
+    const field = (label, value) => (value ? "<dt>" + label + "</dt><dd>" + md(value) + "</dd>" : "");
+    $("ln-journal").innerHTML = l.journal.length
+      ? l.journal.slice().reverse().map((e) =>
+          "<div class='label section-label'>" + esc(e.heading) + " <span class='tag" + (e.decided ? "" : " progress") + "'>" + (e.decided ? "decided" : "waiting") + "</span></div>" +
+          (e.surprised || e.wentWrong || e.deferred
+            ? "<dl class='kv'>" + field("Surprised", e.surprised) + field("Went wrong", e.wentWrong) + field("Deferred", e.deferred) +
+              (e.archive ? "<dt>Archive</dt><dd class='mono dim'>" + esc(e.archive) + "</dd>" : "") + "</dl>"
+            : e.summary ? "<p class='prose'>" + md(e.summary) + "</p>" : "")
+        ).join("<div class='divider'></div>")
+      : empty("No entries yet. complete appends one for every item it finishes.");
   }
 
   function renderHealth() {
@@ -893,14 +964,23 @@ button.chip { font-family: inherit; cursor: pointer; }
       "<li><span class='" + (c.ok ? "ok" : "bad") + "'></span><span>" + esc(c.name) + "</span><span class='detail'>" + md(c.detail) + "</span><span class='blocks'>" +
       (c.blocks === "nothing" ? "advisory" : "blocks " + esc(c.blocks)) + "</span></li>"
     ).join("");
-    const settings = flatten(config(), "", []);
-    $("hl-config").innerHTML = settings.length
-      ? "<table class='rows'><tr><th>Setting</th><th>Value</th></tr>" + settings.map((r) => "<tr><td class='file'>" + esc(r[0]) + "</td><td class='mono'>" + esc(r[1]) + "</td></tr>").join("") + "</table>"
-      : "<div class='body'>" + empty("No configuration. The built-in defaults apply.") + "</div>";
+    $("hl-config").innerHTML = "<table class='rows'><tr><th>Setting</th><th>Here</th><th>Default</th><th>Accepts</th></tr>" +
+      h.settings.map((r) =>
+        "<tr><td><span class='file'>" + esc(r.key) + "</span>" + (r.summary ? "<div class='dim'>" + esc(r.summary) + "</div>" : "") +
+        (r.problem ? "<div class='bad'>" + esc(r.problem) + "</div>" : "") + "</td>" +
+        "<td class='mono'>" + (r.value === null ? "<span class='faint'>default</span>" : esc(r.value)) + "</td>" +
+        "<td class='mono'>" + (r.default ? md(r.default) : "") + "</td><td>" + (r.accepts ? md(r.accepts) : "") + "</td></tr>"
+      ).join("") + "</table>";
     $("hl-install").innerHTML =
       (install
         ? "<dl class='kv'>" + field("Installed by", esc(install.version || "unknown"), "mono") + field("This tool", esc(h.tool || "unknown"), "mono") +
-          field("Adapters", esc(install.adapters.map((x) => ADAPTER_NAMES[x] || x).join(", ") || "none")) + field("Managed", install.managed + " files") + "</dl>"
+          field("Adapters", esc(install.adapters.map((x) => ADAPTER_NAMES[x] || x).join(", ") || "none")) + field("Managed", install.managed + " files") + "</dl>" +
+          "<div class='divider'></div><div class='label section-label'>Changed since install</div>" +
+          (install.edited.length || install.missing.length
+            ? "<ul class='list'>" + install.edited.map((f) => "<li class='mono'>" + esc(f) + "</li>").join("") +
+              install.missing.map((f) => "<li class='mono'>" + esc(f) + " <span class='faint'>missing</span></li>").join("") + "</ul>" +
+              "<p class='prose dim'>update keeps edited files and reports them as changed locally; it puts missing ones back.</p>"
+            : empty("Nothing. Every skill and hook matches what was installed."))
         : empty("No install record. Installing or updating writes religion/.state/manifest.json.")) +
       "<div class='divider'></div><div class='label section-label'>Inbox</div>" +
       (h.inbox.length ? h.inbox.map((n) => "<p class='prose'>" + (n.date ? "<span class='faint mono'>" + esc(n.date) + "</span> " : "") + md(n.text) + "</p>").join("") : empty("Empty.")) +

package/dist/lib/doctor.js

@@ -6,7 +6,9 @@
  */
 import fs from "node:fs/promises";
 import path from "node:path";
-import { exists, readIfPresent, STATE_DIR, statePath } from "./paths.js";
+import { exists, readIfPresent, SKILL_TREES, STATE_DIR, statePath } from "./paths.js";
+import { editedSinceInstall, isPlainFile } from "./install.js";
+import { SETTINGS, settingProblems } from "./settings.js";
 import { readProjectState } from "./state.js";
 const REQUIRED = [
     "config.json",
@@ -26,17 +28,10 @@ const REQUIRED = [
     "history/spikes",
     "reference"
 ];
-/** The values each enumerated setting accepts. Other settings are not checked. */
-export const ALLOWED = {
-    "workflow.stepReview": ["every", "item"],
-    "git.mode": ["trunk", "branch-per-item", "pull-request"],
-    "git.checkpoints": ["none", "every-step", "squash"],
-    "verification.logicTests": ["when-configured", "required"],
-    "verification.uiEvidence": ["when-available", "required"],
-    "qualityGates.audit": ["manual", "when-sensitive", "always"],
-    "qualityGates.check": ["manual", "when-behavioral", "always"]
-};
-export async function runDoctor(root) {
+/** The values each enumerated setting accepts, as the surface record lists them. */
+export const ALLOWED = Object.fromEntries(Object.entries(SETTINGS).flatMap(([key, setting]) => (setting.kind === "enum" ? [[key, setting.values]] : [])));
+/** `changes` lets a caller that already compared the managed files share the result. */
+export async function runDoctor(root, changes) {
     const results = [];
     const state = await readProjectState(root);
     const missing = [];
@@ -54,7 +49,7 @@ export async function runDoctor(root) {
         results.push({ name: "configuration", ok: false, detail: "config.json does not parse", blocks: "work" });
     }
     else {
-        const bad = invalidSettings(state.config);
+        const bad = settingProblems(state.config);
         results.push({
             name: "configuration",
             ok: bad.length === 0,
@@ -62,7 +57,7 @@ export async function runDoctor(root) {
             blocks: "work"
         });
     }
-    const trees = [".claude/skills", ".agents/skills"];
+    const trees = SKILL_TREES;
     const present = {};
     for (const tree of trees) {
         const dir = path.join(root, tree);
@@ -132,21 +127,134 @@ export async function runDoctor(root) {
         detail: (await exists(path.join(root, ".git"))) ? "repository present" : "not a git repository",
         blocks: "completion"
     });
+    results.push(managedFilesCheck(changes === undefined ? await editedSinceInstall(root) : changes));
+    results.push(await readHooks(root));
     return results;
 }
-function invalidSettings(config) {
-    const problems = [];
-    if (config === null || typeof config !== "object")
-        return ["not an object"];
-    for (const [key, allowed] of Object.entries(ALLOWED)) {
-        const value = key.split(".").reduce((node, part) => (node && typeof node === "object" ? node[part] : undefined), config);
-        if (value === undefined)
-            continue;
-        if (!allowed.includes(String(value))) {
-            problems.push(`${key} is "${String(value)}", expected one of ${allowed.join(", ")}`);
-        }
+const SETTINGS_FILE = ".claude/settings.json";
+const LOCAL_SETTINGS_FILE = ".claude/settings.local.json";
+/**
+ * The hooks this version wires, held equal to the shipped settings template by verification.
+ * Not the project's own copy of that template, which is seeded once and goes stale.
+ */
+export const HOOKS = [
+    { event: "PreToolUse", command: "node .claude/hooks/guard-rendered-output.mjs" },
+    { event: "Stop", command: "node .claude/hooks/write-handoff.mjs" },
+    { event: "PostToolUse", command: "node .claude/hooks/scan-untrusted-input.mjs" },
+    { event: "PreToolUse", command: "node .claude/hooks/warn-on-drift.mjs" }
+];
+async function readHooks(root) {
+    const files = new Set();
+    for (const { command } of HOOKS) {
+        const file = hookFile(command);
+        // Existence only: a hook file is never read here, so one reached through a link still counts.
+        if (file && (await exists(path.join(root, ...file.split("/")))))
+            files.add(file);
+    }
+    return hooksCheck({
+        installed: await exists(path.join(root, ".claude", "skills")),
+        wanted: HOOKS,
+        settings: await readSettings(root, SETTINGS_FILE),
+        local: await readSettings(root, LOCAL_SETTINGS_FILE),
+        files
+    });
+}
+/** A settings file's text, read only when it is a plain file reached without a link. */
+async function readSettings(root, relative) {
+    if (await isPlainFile(root, relative))
+        return readIfPresent(path.join(root, ...relative.split("/")));
+    const parts = relative.split("/");
+    for (let i = 1; i <= parts.length; i += 1) {
+        const stat = await fs.lstat(path.join(root, ...parts.slice(0, i))).catch(() => null);
+        if (!stat)
+            return null;
+        if (stat.isSymbolicLink())
+            return "link";
+    }
+    return "not-file";
+}
+/** Every `(event, command)` a settings file registers, or null when it does not parse. */
+export function parseHooks(source) {
+    if (source === null)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        return null;
     }
-    return problems;
+    const hooks = parsed && typeof parsed === "object" ? parsed.hooks : undefined;
+    if (!hooks || typeof hooks !== "object")
+        return [];
+    return Object.entries(hooks).flatMap(([event, groups]) => (Array.isArray(groups) ? groups : []).flatMap((group) => {
+        const inner = group && typeof group === "object" ? group.hooks : undefined;
+        return (Array.isArray(inner) ? inner : []).flatMap((hook) => {
+            const command = hook && typeof hook === "object" ? hook.command : undefined;
+            return typeof command === "string" ? [{ event, command }] : [];
+        });
+    }));
+}
+// `node .claude/hooks/x.mjs`, or the `"$CLAUDE_PROJECT_DIR"/...` form Claude Code's own docs use.
+const HOOK_COMMAND = /\bnode\s+"?(?:\$\{?CLAUDE_PROJECT_DIR\}?"?\/)?(\.claude\/hooks\/[\w.-]+\.mjs)"?(?:\s|$)/;
+export function hookFile(command) {
+    return HOOK_COMMAND.exec(command)?.[1] ?? null;
+}
+function disablesHooks(source) {
+    try {
+        return source !== null && JSON.parse(source)?.disableAllHooks === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether Claude Code's settings register every hook the wiring template names, under the same
+ * event, with each hook's file present. Matchers are not compared: a user may tune them.
+ */
+export function hooksCheck(input) {
+    const result = (ok, detail) => ({ name: "hooks", ok, detail, blocks: "nothing" });
+    if (!input.installed)
+        return result(true, "Claude Code is not installed here");
+    if (input.settings === "link")
+        return result(false, `${SETTINGS_FILE} is reached through a link, so it was not read`);
+    if (input.settings === "not-file")
+        return result(false, `${SETTINGS_FILE} is not a regular file`);
+    const local = typeof input.local === "string" && input.local !== "link" && input.local !== "not-file" ? input.local : null;
+    if (input.settings === null && local === null)
+        return result(false, `${SETTINGS_FILE} is missing; a fresh install writes it`);
+    const shared = input.settings === null ? [] : parseHooks(input.settings);
+    if (shared === null)
+        return result(false, `${SETTINGS_FILE} does not parse`);
+    if (disablesHooks(input.settings) || disablesHooks(local))
+        return result(false, "disableAllHooks is on, so no hook runs");
+    const registered = [...shared, ...(parseHooks(local) ?? [])];
+    const unwired = input.wanted.filter((w) => !registered.some((r) => r.event === w.event && hookFile(r.command) === hookFile(w.command)));
+    const fileless = input.wanted.filter((w) => {
+        const file = hookFile(w.command);
+        return file !== null && !input.files.has(file);
+    });
+    if (unwired.length === 0 && fileless.length === 0)
+        return result(true, `all ${input.wanted.length} wired`);
+    const name = (hook) => `${hookFile(hook.command)?.split("/").pop() ?? hook.command} (${hook.event})`;
+    const parts = [
+        unwired.length ? `not registered in ${SETTINGS_FILE} or ${LOCAL_SETTINGS_FILE}: ${unwired.map(name).join(", ")}; copy them from a fresh install's settings` : "",
+        fileless.length ? `missing hook file: ${fileless.map(name).join(", ")}; run update` : ""
+    ].filter(Boolean);
+    return result(false, parts.join("; "));
+}
+const LISTED = 5;
+/** Advisory: an edited managed file is its owner's choice, and `update` keeps it rather than overwriting it. */
+export function managedFilesCheck(changes) {
+    const result = (detail) => ({ name: "managed files", ok: true, detail, blocks: "nothing" });
+    if (!changes)
+        return result("no install record to compare with");
+    const { edited, missing, total } = changes;
+    if (edited.length === 0 && missing.length === 0)
+        return result(`all ${total} unchanged since install`);
+    const changed = [...edited, ...missing.map((file) => `${file} (missing)`)];
+    const shown = changed.slice(0, LISTED).join(", ") + (changed.length > LISTED ? `, and ${changed.length - LISTED} more` : "");
+    return result(`${edited.length} edited and ${missing.length} missing of ${total} since install: ${shown}`);
 }
 export function doctorReport(checks) {
     return { schemaVersion: 1, healthy: checks.every((check) => check.ok), checks: [...checks] };

package/dist/lib/install.js

@@ -17,7 +17,7 @@ export const ADAPTERS = {
     copilot: { label: "GitHub Copilot", trees: [".agents/skills"], entry: ["AGENTS.md"] },
     opencode: { label: "OpenCode", trees: [".agents/skills"], entry: ["AGENTS.md"] }
 };
-const MANIFEST_PATH = `${STATE_DIR}/.state/manifest.json`;
+export const MANIFEST_PATH = `${STATE_DIR}/.state/manifest.json`;
 const MANIFEST = path.join(...MANIFEST_PATH.split("/"));
 /** Where originals are copied before install or update changes them, relative to the project. */
 export const BACKUPS = `${STATE_DIR}/.state/backups`;
@@ -121,7 +121,7 @@ async function planDropped(templateRoot, target, previous) {
  * asked anything. A case-insensitive disk would otherwise let `RELIGION/` or `.CLAUDE/`
  * reach files the comparison was meant to exclude.
  */
-function retiringTree(relative) {
+export function retiringTree(relative) {
     if (relative.includes("\\") || path.posix.isAbsolute(relative))
         return null;
     if (path.posix.normalize(relative) !== relative || relative.split("/").includes(".."))
@@ -130,7 +130,7 @@ function retiringTree(relative) {
     return [...trees].find((tree) => relative.startsWith(`${tree}/`)) ?? null;
 }
 /** Every component a real directory and the last a regular file, with no symbolic link anywhere. */
-async function isPlainFile(target, relative) {
+export async function isPlainFile(target, relative) {
     const parts = relative.split("/");
     let current = target;
     for (const [index, part] of parts.entries()) {
@@ -247,13 +247,13 @@ async function rebuildOrConflict(target, relative, recorded) {
     const genuine = typeof recorded === "string" && /^[0-9a-f]{16}$/.test(recorded);
     return genuine && (await isPlainFile(target, relative)) ? "rebuild" : "conflict";
 }
-async function backUp(target, relative) {
+export async function backUp(target, relative) {
     const backup = path.join(target, ...`${BACKUPS}/${relative}`.split("/"));
     await fs.mkdir(path.dirname(backup), { recursive: true });
     await fs.copyFile(path.join(target, relative), backup);
 }
 /** Whether any existing component of a project path is a symbolic link. Missing ones are not. */
-async function throughLink(target, relative) {
+export async function throughLink(target, relative) {
     let current = target;
     for (const part of relative.split("/")) {
         current = path.join(current, part);
@@ -369,7 +369,7 @@ export function manifestRefusal(manifest, packageVersion) {
     }
     return null;
 }
-function isNewer(candidate, than) {
+export function isNewer(candidate, than) {
     const a = parseVersion(candidate);
     const b = parseVersion(than);
     if (!a || !b)
@@ -386,6 +386,43 @@ function parseVersion(version) {
     const match = /^(\d+)\.(\d+)\.(\d+)(?:-.*)?$/.exec(version.trim());
     return match ? match.slice(1, 4).map(Number) : null;
 }
+/**
+ * Managed files whose contents no longer match what was installed, and those that are gone.
+ *
+ * Only plain files under a skill or hook tree are compared, the same line `update` draws for
+ * what it may retire: the manifest is a file in someone's repository, so a recorded path must
+ * not be able to make this read anything else. Entry files are left out because `update`
+ * merges them, so an edit there is expected rather than a change it will report.
+ */
+export async function editedSinceInstall(target) {
+    const managed = (await readManifest(target))?.managed;
+    if (!managed || typeof managed !== "object")
+        return null;
+    const edited = [];
+    const missing = [];
+    let total = 0;
+    for (const [relative, recorded] of Object.entries(managed)) {
+        if (typeof recorded !== "string" || !retiringTree(relative))
+            continue;
+        total += 1;
+        const file = path.join(target, ...relative.split("/"));
+        // Anything there that is not the plain, readable file installed counts as edited: a link,
+        // a directory or an unreadable file is what `update` reports too, and this check must
+        // never be the thing that makes doctor fail.
+        if (!(await fs.lstat(file).catch(() => null))) {
+            missing.push(relative);
+        }
+        else if (!(await isPlainFile(target, relative))) {
+            edited.push(relative);
+        }
+        else {
+            const contents = await fs.readFile(file).catch(() => null);
+            if (contents === null || hash(contents) !== recorded)
+                edited.push(relative);
+        }
+    }
+    return { edited: edited.sort(), missing: missing.sort(), total };
+}
 export async function readManifest(target) {
     try {
         return JSON.parse(await fs.readFile(path.join(target, MANIFEST), "utf8"));