create-yss-spec 2.1.11 → 2.1.13

package/template/.cursor/skills/llm-wiki/references/query.md

@@ -0,0 +1,21 @@
+# Query
+
+Query is not a compile mode. It reads the wiki; it does not write `raw/`, articles, `index.md`, `log.md`, or `.wiki-manifest.json`.
+
+Use this algorithm when the user asks a repository question and a wiki exists, or asks to answer from the wiki. Do not open the whole corpus, and do not treat wiki prose as live fact.
+
+## Steps
+
+1. **Detect.** If `wiki/index.md` is absent, say the question is outside query: no wiki exists. Suggest `init`. Stop.
+
+2. **Freshness.** If `.wiki-manifest.json` exists, run `inventory.mjs status --wiki <wiki-root>` (same JSON as `drift`). Read `changed`, `missing`, `unchanged`, `articles`, `unmapped`, `humanOwned`. Exit `0` is a valid report, not a failure. Exit `2` is a script error. Show that source-status table. Non-empty `changed` or `missing` means stale: name those sources, ask whether to `refresh`, and do not present drifted pages as current fact. If the user still wants an answer, mark every claim that depends on a drifted source as stale.
+
+3. **Select pages.** First match proper nouns and distinctive terms against `index.md` category headings (`##`) and `[[wikilink]]` targets. If that set is empty or clearly too narrow for the question, search H1 and the first paragraph of each non-infrastructure `wiki/*.md` with the question's distinctive terms and obvious synonyms (`rg` is enough; do not build an index). Open at most `N = min(8, hit count)` articles. Do not open the whole wiki. Do not answer from one summary paragraph when more hit pages exist.
+
+4. **Verify claims.** For each assertion, re-read the live paths in that page's `## 来源` (repo-relative live files, not the wiki sentence). If wiki text conflicts with live, cite live and record wiki drift. Do not rewrite the wiki during query. Do not ingest.
+
+5. **Zero hits.** Only after **both** the index/`[[wikilink]]` pass and the H1/summary search are empty may you say the wiki does not cover the question. List the index categories considered and the search terms used. Do not invent article ids, pages, or facts.
+
+## Done when
+
+The answer cites the pages actually opened and the live sources actually re-read, or it states non-coverage. Query never completes via lint, `CREATE`, `REFRESH`, `REBUILD`, or `INGEST`.

package/template/.cursor/skills/llm-wiki/references/schema.md

@@ -0,0 +1,45 @@
+# Wiki schema
+
+Karpathy three-layer wiki. Detectable by `index.md`, `[[wikilink]]`, optional `raw/`, and `CLAUDE.md` or `AGENTS.md`.
+
+## Layers
+
+- **raw/** — immutable sources. The agent reads them; it does not edit them to "fix" facts. Wrong facts are fixed by recompiling the wiki from live paths. Allowed contents: copies of documents, and derived extracts that name their live inputs and an `extract` recipe (see [compile.md](compile.md)).
+- **wiki/** — LLM-owned markdown. Humans read; the agent writes. Article id = filename without `.md`, globally unique. Infrastructure files are not articles: `index.md`, `log.md`, `CLAUDE.md`, `AGENTS.md`, `soul.md`, `concept-table.md`.
+- **schema** — `wiki/CLAUDE.md` (this repo also accepts `AGENTS.md`). Conventions for ingest, refresh, rebuild, and lint. Co-evolve it with the domain; start from `assets/CLAUDE.md.template`.
+- **.wiki-manifest.json** — compile graph, sibling of `raw/` and `wiki/`. Not an article. Not a raw source.
+
+## index.md
+
+`##` headings are categories (taxonomy). Listed `[[wikilink]]` assign articles to categories. Categories come from index headings, not filename prefixes.
+
+## log.md
+
+Append-only. Format: `## [YYYY-MM-DD] OPERATION | 描述`
+
+Operations: `CREATE` `UPDATE` `LINK` `FIX` `REFRESH` `REBUILD` `RETIRE` `LINT` `INGEST`.
+
+## concept-table.md
+
+Optional. Infrastructure, same class as `index.md`. A table of concept, relationship, and article id. Rebuild may rewrite it. Do not move articles into `wiki/entities/`.
+
+## Articles
+
+1. `# H1` then a one-paragraph summary (parsers use this as summary).
+2. Body uses `[[ArticleId]]`. Target must be a wiki article filename without `.md`.
+3. Every claim traces to `raw/` or a live code path. End with a `## 来源` section.
+4. Optional YAML frontmatter: `human-owned: true` — refresh/rebuild must not rewrite the body; they may fix wikilinks only.
+5. Optional `## Status` when multiple `sourceIds` disagree, or live disagrees with old raw:
+
+```markdown
+## Status
+- kind: Disputed | Outdated
+- sources: <sourceId>, <sourceId>
+- note: one-line conflict
+```
+
+Do not write Status when a single live source is correct. Refresh that finds a conflict keeps both citations and the Status block; it must not silently overwrite with the newest live text and pretend there was no conflict. `human-owned` pages do not get a Status rewrite. Status is not an article id and is not an index category. Missing Status is not a lint failure.
+
+## Language
+
+Body language follows the host project's document-language rule. Keep identifiers, enums, table names, API paths, and filenames verbatim.

package/template/.cursor/skills/llm-wiki/references/writing.md

@@ -0,0 +1,35 @@
+# Writing
+
+## Page shape
+
+- `# H1` immediately followed by a summary paragraph.
+- `[[ArticleId]]` only; no relative `[[../other-wiki]]` inside a Karpathy wiki (cross-wiki use markdown links).
+- Close with `## 来源` listing raw files and live code paths actually read.
+- Optional `## Status` only when cited sources conflict or live disagrees with old raw. See [schema.md](schema.md). Missing Status is not a defect.
+- Do not invent enum values, table names, or endpoints. If unread, write「见源码」.
+
+## Fact order
+
+1. Called implementation (application service, domain method, mapper SQL).
+2. Table comments / OpenAPI / config defaults.
+3. Stale raw copies.
+
+A column default is not proof the runtime uses it. A freeze OpenAPI is not the full controller surface.
+
+## Coverage
+
+Core pages: deep (state machines, HTTP semantics, transactions). Extension pages: overview (models, enums, tables, links). Match the user's coverage choice from init.
+
+## Subagents
+
+When 2+ article groups have no shared files:
+
+- Each prompt lists exact write paths. Those agents must not touch `index.md`, `log.md`, `.wiki-manifest.json`, or `CLAUDE.md`.
+- Return: paths written + wikilink count per file.
+- Orchestrator merges, lints, samples facts, appends log.
+
+When article groups share no files, dispatch parallel subagents with disjoint write scopes.
+
+## Human-owned
+
+Frontmatter `human-owned: true` or manifest `humanOwned: true`. Refresh/rebuild leave the body; they may repair `[[wikilink]]` targets only. Do not add or rewrite `## Status` on these pages.

package/template/.cursor/skills/llm-wiki/scripts/advise.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { exists } from "./inventory.mjs";
+import { articlesDir, extractLinks, INFRA } from "./lint-wikilinks.mjs";
+
+const SOURCE_HEADING_RE = /^##\s+来源\s*$/m;
+const H1_RE = /^#\s+(.+?)\s*$/m;
+const NUMBER_RE = /\b\d+(?:\.\d+)?[A-Za-z%]+\b/g;
+const ISO_DATE_RE = /\b\d{4}-\d{2}-\d{2}\b/g;
+const LONG_QUOTE_RE = /[“"]([^”"]{12,})[”"]/g;
+const BACKTICK_RE = /`([^`\n]{2,64})`/g;
+const BOLD_RE = /\*\*([^*]{2,32})\*\*/g;
+const HEADING_RE = /^#{2,6}\s+(.+)$/gm;
+
+export function sourceSection(text) {
+  const match = text.match(SOURCE_HEADING_RE);
+  if (!match) return "";
+  return text.slice(match.index + match[0].length);
+}
+
+export function firstParagraph(text) {
+  const afterH1 = text.replace(/^---[\s\S]*?---\s*/, "").replace(H1_RE, "").trimStart();
+  const block = afterH1.split(/\n\s*\n/)[0] || "";
+  return block.trim();
+}
+
+export function articleBody(text) {
+  const source = text.search(SOURCE_HEADING_RE);
+  const head = source === -1 ? text : text.slice(0, source);
+  return head.replace(/^---[\s\S]*?---\s*/, "");
+}
+
+export function highSignalLiterals(text) {
+  const found = new Set();
+  for (const match of text.matchAll(NUMBER_RE)) found.add(match[0]);
+  for (const match of text.matchAll(ISO_DATE_RE)) found.add(match[0]);
+  for (const match of text.matchAll(LONG_QUOTE_RE)) found.add(match[1]);
+  return [...found];
+}
+
+function addTerm(counter, term) {
+  const value = term.trim();
+  if (!value) return;
+  counter.set(value, (counter.get(value) || 0) + 1);
+}
+
+export function collectTerms(text) {
+  const body = articleBody(text);
+  const counter = new Map();
+  for (const match of body.matchAll(BACKTICK_RE)) addTerm(counter, match[1]);
+  for (const match of body.matchAll(BOLD_RE)) addTerm(counter, match[1]);
+  for (const match of body.matchAll(HEADING_RE)) addTerm(counter, match[1]);
+  return counter;
+}
+
+export async function loadArticles(wikiRoot) {
+  const dir = articlesDir(wikiRoot);
+  const names = (await readdir(dir)).filter((name) => name.endsWith(".md"));
+  const files = names.filter((name) => !INFRA.has(name.toLowerCase()));
+  const articles = [];
+  for (const file of files) {
+    const text = await readFile(path.join(dir, file), "utf8");
+    articles.push({
+      id: file.slice(0, -3),
+      file,
+      text,
+      links: extractLinks(text).ids,
+    });
+  }
+  return articles;
+}
+
+export function oneWayLinks(articles) {
+  const inbound = new Map();
+  for (const article of articles) inbound.set(article.id, new Set());
+  for (const article of articles) {
+    for (const target of article.links) {
+      if (!inbound.has(target)) continue;
+      inbound.get(target).add(article.id);
+    }
+  }
+  const findings = [];
+  for (const article of articles) {
+    for (const target of new Set(article.links)) {
+      if (target === article.id) continue;
+      if (!inbound.has(target)) continue;
+      if (inbound.get(article.id).has(target)) continue;
+      findings.push({ from: article.id, to: target });
+    }
+  }
+  return findings;
+}
+
+export function missingTermPages(articles) {
+  const ids = new Set(articles.map((article) => article.id));
+  const counts = new Map();
+  for (const article of articles) {
+    const local = collectTerms(article.text);
+    for (const [term, count] of local) {
+      if (ids.has(term)) continue;
+      counts.set(term, (counts.get(term) || 0) + count);
+    }
+  }
+  return [...counts.entries()]
+    .filter(([, count]) => count >= 2)
+    .map(([term, count]) => ({ term, count }))
+    .sort((a, b) => b.count - a.count || a.term.localeCompare(b.term));
+}
+
+export function unreferencedRaws(manifest, articles) {
+  const cited = articles.map((article) => sourceSection(article.text)).join("\n");
+  const findings = [];
+  for (const source of manifest.sources || []) {
+    if (!source.rawPath) continue;
+    if (cited.includes(source.rawPath) || cited.includes(source.id)) continue;
+    findings.push({ id: source.id, rawPath: source.rawPath });
+  }
+  return findings;
+}
+
+async function citedCorpus({ wikiRoot, repoRoot, article, manifest }) {
+  const cited = sourceSection(article.text);
+  const chunks = [cited];
+  for (const source of manifest.sources || []) {
+    const mentioned =
+      (source.rawPath && cited.includes(source.rawPath)) ||
+      (source.id && cited.includes(source.id)) ||
+      (source.livePath && cited.includes(source.livePath));
+    if (!mentioned) continue;
+    if (source.rawPath) {
+      const raw = path.resolve(wikiRoot, source.rawPath);
+      if (await exists(raw)) chunks.push(await readFile(raw, "utf8"));
+    }
+    if (source.livePath) {
+      const live = path.resolve(repoRoot, source.livePath);
+      if (await exists(live)) chunks.push(await readFile(live, "utf8"));
+    }
+  }
+  return chunks.join("\n");
+}
+
+export async function evidenceSuspects({ wikiRoot, repoRoot, articles, manifest }) {
+  const findings = [];
+  for (const article of articles) {
+    const literals = highSignalLiterals(articleBody(article.text));
+    if (!literals.length) continue;
+    const corpus = await citedCorpus({ wikiRoot, repoRoot, article, manifest });
+    for (const value of literals) {
+      if (!corpus.includes(value)) {
+        findings.push({ article: article.id, value });
+      }
+    }
+  }
+  return findings;
+}
+
+export async function adviseWiki(wikiRoot, { repoRoot = process.cwd() } = {}) {
+  const articles = await loadArticles(wikiRoot);
+  const manifestFile = path.join(wikiRoot, ".wiki-manifest.json");
+  const manifest = (await exists(manifestFile))
+    ? JSON.parse(await readFile(manifestFile, "utf8"))
+    : { sources: [] };
+  return {
+    oneWayLinks: oneWayLinks(articles),
+    missingTermPages: missingTermPages(articles),
+    unreferencedRaws: unreferencedRaws(manifest, articles),
+    suspects: await evidenceSuspects({ wikiRoot, repoRoot, articles, manifest }),
+  };
+}
+
+function parseArgs(argv) {
+  const args = { wiki: null, repo: process.cwd() };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--repo") args.repo = argv[++i];
+    else if (argv[i] === "--wiki") args.wiki = argv[++i];
+    else if (!args.wiki && !argv[i].startsWith("-")) args.wiki = argv[i];
+  }
+  return args;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (!args.wiki) throw new Error("usage: advise.mjs <wiki-root> [--repo <repo-root>]");
+  const wikiRoot = path.resolve(args.repo, args.wiki);
+  const report = await adviseWiki(wikiRoot, { repoRoot: path.resolve(args.repo) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 2;
+  });
+}

package/template/.cursor/skills/llm-wiki/scripts/advise.test.mjs

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { sha256 } from "./inventory.mjs";
+import { adviseWiki } from "./advise.mjs";
+import { lintWiki } from "./lint-wikilinks.mjs";
+
+const adviseCli = fileURLToPath(new URL("./advise.mjs", import.meta.url));
+
+async function seedAdvise() {
+  const repo = await mkdtemp(path.join(tmpdir(), "llm-wiki-advise-"));
+  const wikiRoot = path.join(repo, "wiki-root");
+  const wiki = path.join(wikiRoot, "wiki");
+  await mkdir(wiki, { recursive: true });
+  await mkdir(path.join(wikiRoot, "raw"), { recursive: true });
+  await mkdir(path.join(repo, "docs"), { recursive: true });
+  await writeFile(path.join(repo, "docs", "api.md"), "version one\n", "utf8");
+  await writeFile(path.join(wikiRoot, "raw", "api.md"), "version one\n", "utf8");
+  await writeFile(path.join(wikiRoot, "raw", "orphan-raw.md"), "unused\n", "utf8");
+  await writeFile(path.join(wiki, "index.md"), "# index\n\n## 分类\n\n- [[Alpha]]\n- [[Beta]]\n", "utf8");
+  await writeFile(
+    path.join(wiki, "Alpha.md"),
+    "# Alpha\n\nSee [[Beta]] and **孤立术语**. The figure is 42K.\n\n## 来源\n\n- raw/api.md\n",
+    "utf8",
+  );
+  await writeFile(
+    path.join(wiki, "Beta.md"),
+    "# Beta\n\nMentions **孤立术语** again.\n\n## 来源\n\n- raw/api.md\n",
+    "utf8",
+  );
+  await writeFile(path.join(wiki, "concept-table.md"), "# concepts\n", "utf8");
+  await writeFile(
+    path.join(wikiRoot, ".wiki-manifest.json"),
+    JSON.stringify({
+      schemaVersion: 1,
+      profile: "documents",
+      sources: [
+        {
+          id: "api.md",
+          kind: "document",
+          livePath: "docs/api.md",
+          rawPath: "raw/api.md",
+          sha256: sha256(Buffer.from("version one\n")),
+        },
+        {
+          id: "orphan-raw.md",
+          kind: "document",
+          livePath: "docs/api.md",
+          rawPath: "raw/orphan-raw.md",
+          sha256: sha256(Buffer.from("version one\n")),
+        },
+      ],
+      articles: [
+        { id: "Alpha", file: "wiki/Alpha.md", sourceIds: ["api.md"] },
+        { id: "Beta", file: "wiki/Beta.md", sourceIds: ["api.md"] },
+      ],
+    }),
+    "utf8",
+  );
+  return { repo, wikiRoot };
+}
+
+test("advise reports one-way links, missing terms, unreferenced raw, and suspects without failing lint", async () => {
+  const { repo, wikiRoot } = await seedAdvise();
+  const lint = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(lint.ok, true, lint.errors.join("\n"));
+  const report = await adviseWiki(wikiRoot, { repoRoot: repo });
+  assert.ok(report.oneWayLinks.some((item) => item.from === "Alpha" && item.to === "Beta"));
+  assert.ok(report.missingTermPages.some((item) => item.term === "孤立术语" && item.count >= 2));
+  assert.ok(report.unreferencedRaws.some((item) => item.rawPath === "raw/orphan-raw.md"));
+  assert.ok(report.suspects.some((item) => item.article === "Alpha" && item.value === "42K"));
+});
+
+test("advise CLI exits 0 and prints JSON", async () => {
+  const { repo, wikiRoot } = await seedAdvise();
+  const ran = spawnSync(process.execPath, [adviseCli, wikiRoot, "--repo", repo], { encoding: "utf8" });
+  assert.equal(ran.status, 0, ran.stderr);
+  const report = JSON.parse(ran.stdout);
+  assert.ok(Array.isArray(report.suspects));
+});
+
+test("concept-table.md is infrastructure and does not fail lint as an orphan", async () => {
+  const { repo, wikiRoot } = await seedAdvise();
+  const lint = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(lint.ok, true, lint.errors.join("\n"));
+  assert.equal(lint.counts.articles, 2);
+});

package/template/.cursor/skills/llm-wiki/scripts/extract.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const EXTRACT_KINDS = Object.freeze(["skill-names", "heading-list", "prose-note"]);
+
+function namesOf(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+  return Object.keys(value).sort((a, b) => a.localeCompare(b));
+}
+
+export function extractSkillNames(lock) {
+  if (!lock || typeof lock !== "object" || Array.isArray(lock)) {
+    throw new TypeError("skill-names input must be a lock object");
+  }
+  const shared = namesOf(lock.skills?.shared);
+  const platform = lock.skills?.platform && typeof lock.skills.platform === "object" ? lock.skills.platform : {};
+  const lines = ["# skills-lock names", "", "Derived names only. Do not copy hashes, paths, or the lock file.", "", "## shared", ""];
+  for (const name of shared) lines.push(`- \`${name}\``);
+  const roots = namesOf(platform);
+  if (roots.length) {
+    lines.push("", "## platform", "");
+    for (const root of roots) {
+      lines.push(`### \`${root}\``, "");
+      for (const name of namesOf(platform[root])) lines.push(`- \`${name}\``);
+      lines.push("");
+    }
+  }
+  return `${lines.join("\n").replace(/\n+$/, "")}\n`;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const kind = argv[0];
+  let input;
+  let output;
+  for (let i = 1; i < argv.length; i += 1) {
+    if (argv[i] === "--in") input = argv[++i];
+    else if (argv[i] === "--out") output = argv[++i];
+  }
+  if (kind !== "skill-names" || !input || !output) {
+    throw new Error("usage: extract.mjs skill-names --in <lock.json> --out <raw.md>");
+  }
+  const text = extractSkillNames(JSON.parse(await readFile(input, "utf8")));
+  await mkdir(path.dirname(output), { recursive: true });
+  await writeFile(output, text, "utf8");
+  process.stdout.write(`${output}\n`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 2;
+  });
+}

package/template/.cursor/skills/llm-wiki/scripts/extract.test.mjs

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { EXTRACT_KINDS, extractSkillNames } from "./extract.mjs";
+
+test("skill-names lists shared and platform keys, sorted, without hashes", () => {
+  const text = extractSkillNames({
+    skills: {
+      shared: {
+        zeta: { effectiveHash: "aaa", skillPath: "hidden" },
+        alpha: { effectiveHash: "bbb" },
+      },
+      platform: {
+        ".codex/skills": {
+          "product-design": { effectiveHash: "ccc" },
+          "data-analytics": { effectiveHash: "ddd" },
+        },
+      },
+    },
+  });
+  assert.match(text, /## shared/);
+  assert.match(text, /## platform/);
+  assert.ok(text.indexOf("`alpha`") < text.indexOf("`zeta`"));
+  assert.ok(text.indexOf("`data-analytics`") < text.indexOf("`product-design`"));
+  assert.doesNotMatch(text, /aaa|bbb|ccc|ddd|skillPath|effectiveHash/);
+  assert.doesNotMatch(text, /"version"|canonicalRoot/);
+});
+
+test("skill-names rejects a whole-file dump of a non-object", () => {
+  assert.throws(() => extractSkillNames("not-json-object"), /lock object/);
+});
+
+test("declared extract kinds stay the documented set", () => {
+  assert.deepEqual([...EXTRACT_KINDS], ["skill-names", "heading-list", "prose-note"]);
+});

package/template/.cursor/skills/llm-wiki/scripts/inventory.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { readFile, writeFile, access } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MANIFEST = ".wiki-manifest.json";
+
+export function sha256(buffer) {
+  return createHash("sha256").update(buffer).digest("hex");
+}
+
+export function resolveWikiRoot(wikiArg, cwd = process.cwd()) {
+  if (!wikiArg) throw new Error("missing --wiki <wiki-root>");
+  return path.resolve(cwd, wikiArg);
+}
+
+export function manifestPath(wikiRoot) {
+  return path.join(wikiRoot, MANIFEST);
+}
+
+export async function loadManifest(wikiRoot) {
+  const file = manifestPath(wikiRoot);
+  const raw = await readFile(file, "utf8");
+  return JSON.parse(raw);
+}
+
+export async function saveManifest(wikiRoot, manifest) {
+  const file = manifestPath(wikiRoot);
+  await writeFile(file, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  return file;
+}
+
+export async function exists(file) {
+  try {
+    await access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function gitCommit(repoRoot) {
+  try {
+    return execFileSync("git", ["-C", repoRoot, "rev-parse", "HEAD"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+export async function hashSources({ wikiRoot, repoRoot, now = new Date().toISOString() }) {
+  const manifest = await loadManifest(wikiRoot);
+  const missing = [];
+  for (const source of manifest.sources || []) {
+    if (!source.livePath) {
+      source.sha256 = "";
+      continue;
+    }
+    const live = path.resolve(repoRoot, source.livePath);
+    if (!(await exists(live))) {
+      missing.push(source.id);
+      source.sha256 = "";
+      continue;
+    }
+    source.sha256 = sha256(await readFile(live));
+  }
+  manifest.compiledAt = now;
+  manifest.gitCommit = gitCommit(repoRoot);
+  await saveManifest(wikiRoot, manifest);
+  return { manifest, missing };
+}
+
+export function normalizeLivePath(livePath) {
+  return String(livePath || "").replace(/\\/g, "/").replace(/^\.\/+/, "");
+}
+
+export function unmappedCandidates(sources, candidates = []) {
+  const mapped = new Set(
+    (sources || []).map((source) => normalizeLivePath(source.livePath)).filter(Boolean),
+  );
+  const unmapped = [];
+  const seen = new Set();
+  for (const candidate of candidates) {
+    const livePath = normalizeLivePath(candidate);
+    if (!livePath || mapped.has(livePath) || seen.has(livePath)) continue;
+    seen.add(livePath);
+    unmapped.push(livePath);
+  }
+  return unmapped;
+}
+
+export async function drift({ wikiRoot, repoRoot, candidates = [] }) {
+  const manifest = await loadManifest(wikiRoot);
+  const changed = [];
+  const missing = [];
+  const unchanged = [];
+  for (const source of manifest.sources || []) {
+    if (!source.livePath) {
+      unchanged.push(source.id);
+      continue;
+    }
+    const live = path.resolve(repoRoot, source.livePath);
+    if (!(await exists(live))) {
+      missing.push(source.id);
+      continue;
+    }
+    const current = sha256(await readFile(live));
+    if (current !== source.sha256) changed.push(source.id);
+    else unchanged.push(source.id);
+  }
+  const hit = new Set([...changed, ...missing]);
+  const articles = [];
+  const humanOwned = [];
+  for (const article of manifest.articles || []) {
+    const impacted = (article.sourceIds || []).some((id) => hit.has(id));
+    if (!impacted) continue;
+    articles.push(article.id);
+    if (article.humanOwned === true) humanOwned.push(article.id);
+  }
+  return {
+    changed,
+    missing,
+    unchanged,
+    articles,
+    unmapped: unmappedCandidates(manifest.sources, candidates),
+    humanOwned,
+  };
+}
+
+function parseArgs(argv) {
+  const args = { command: argv[0], wiki: null, repo: process.cwd(), candidates: [] };
+  for (let i = 1; i < argv.length; i += 1) {
+    if (argv[i] === "--wiki") args.wiki = argv[++i];
+    else if (argv[i] === "--repo") args.repo = argv[++i];
+    else if (argv[i] === "--candidate") args.candidates.push(argv[++i]);
+    else if (!args.wiki && !argv[i].startsWith("-")) args.wiki = argv[i];
+  }
+  return args;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (!args.command || !["hash", "drift", "status"].includes(args.command)) {
+    throw new Error(
+      "usage: inventory.mjs hash|drift|status --wiki <wiki-root> [--repo <repo-root>] [--candidate <livePath>]",
+    );
+  }
+  const wikiRoot = resolveWikiRoot(args.wiki, args.repo);
+  const repoRoot = path.resolve(args.repo);
+  if (!(await exists(manifestPath(wikiRoot)))) {
+    throw new Error(`manifest not found: ${manifestPath(wikiRoot)}`);
+  }
+  if (args.command === "hash") {
+    const result = await hashSources({ wikiRoot, repoRoot });
+    process.stdout.write(
+      `${JSON.stringify({ hashed: (result.manifest.sources || []).length, missing: result.missing }, null, 2)}\n`,
+    );
+    if (result.missing.length) process.exitCode = 1;
+    return;
+  }
+  const report = await drift({ wikiRoot, repoRoot, candidates: args.candidates });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 2;
+  });
+}