create-yss-spec 2.1.11 → 2.1.14

package/template/.agents/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/.agents/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/.agents/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/.agents/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/.agents/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;
+  });
+}

package/template/.agents/skills/llm-wiki/scripts/inventory.test.mjs

@@ -0,0 +1,98 @@
+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 { drift, hashSources, sha256, unmappedCandidates } from "./inventory.mjs";
+
+const inventoryCli = fileURLToPath(new URL("./inventory.mjs", import.meta.url));
+
+async function seed() {
+  const repo = await mkdtemp(path.join(tmpdir(), "llm-wiki-inv-"));
+  const wiki = path.join(repo, "wiki-root");
+  await mkdir(path.join(wiki, "raw"), { recursive: true });
+  const liveRel = "docs/api.md";
+  const live = path.join(repo, liveRel);
+  await mkdir(path.dirname(live), { recursive: true });
+  await writeFile(live, "v1\n", "utf8");
+  await writeFile(
+    path.join(wiki, ".wiki-manifest.json"),
+    JSON.stringify({
+      schemaVersion: 1,
+      wikiRoot: "wiki-root",
+      profile: "documents",
+      sources: [
+        {
+          id: "api.md",
+          kind: "document",
+          livePath: liveRel,
+          rawPath: "raw/api.md",
+          sha256: "",
+          role: "copy",
+        },
+      ],
+      articles: [
+        { id: "API契约", file: "wiki/API契约.md", sourceIds: ["api.md"], humanOwned: false },
+        { id: "人工页", file: "wiki/人工页.md", sourceIds: ["api.md"], humanOwned: true },
+      ],
+    }),
+    "utf8",
+  );
+  return { repo, wiki, live, liveRel };
+}
+
+test("hash-sources fills sha256; drift is empty until live file changes", async () => {
+  const { repo, wiki, live } = await seed();
+  const hashed = await hashSources({ wikiRoot: wiki, repoRoot: repo, now: "2026-01-01T00:00:00Z" });
+  assert.equal(hashed.missing.length, 0);
+  assert.equal(hashed.manifest.sources[0].sha256, sha256(Buffer.from("v1\n")));
+  const clean = await drift({ wikiRoot: wiki, repoRoot: repo });
+  assert.deepEqual(clean.changed, []);
+  assert.deepEqual(clean.articles, []);
+  await writeFile(live, "v2\n", "utf8");
+  const dirty = await drift({ wikiRoot: wiki, repoRoot: repo });
+  assert.deepEqual(dirty.changed, ["api.md"]);
+  assert.deepEqual(dirty.articles, ["API契约", "人工页"]);
+  assert.deepEqual(dirty.humanOwned, ["人工页"]);
+  assert.deepEqual(dirty.unmapped, []);
+});
+
+test("unmapped candidates are listed without scanning the tree", () => {
+  const sources = [{ livePath: "docs/api.md" }];
+  assert.deepEqual(unmappedCandidates(sources, ["docs/api.md", "docs/new.md", "./docs/new.md"]), [
+    "docs/new.md",
+  ]);
+});
+
+test("drift CLI exits 0 when sources changed and prints JSON", async () => {
+  const { repo, wiki, live } = await seed();
+  await hashSources({ wikiRoot: wiki, repoRoot: repo, now: "2026-01-01T00:00:00Z" });
+  await writeFile(live, "v2\n", "utf8");
+  const ran = spawnSync(process.execPath, [inventoryCli, "drift", "--wiki", wiki, "--repo", repo], {
+    encoding: "utf8",
+  });
+  assert.equal(ran.status, 0, ran.stderr);
+  const report = JSON.parse(ran.stdout);
+  assert.deepEqual(report.changed, ["api.md"]);
+  assert.deepEqual(report.articles, ["API契约", "人工页"]);
+  assert.deepEqual(report.humanOwned, ["人工页"]);
+  assert.deepEqual(report.unmapped, []);
+});
+
+test("status CLI exits 0 and lists unmapped candidates", async () => {
+  const { repo, wiki, live } = await seed();
+  await hashSources({ wikiRoot: wiki, repoRoot: repo, now: "2026-01-01T00:00:00Z" });
+  await writeFile(live, "v2\n", "utf8");
+  const ran = spawnSync(
+    process.execPath,
+    [inventoryCli, "status", "--wiki", wiki, "--repo", repo, "--candidate", "docs/extra.md"],
+    { encoding: "utf8" },
+  );
+  assert.equal(ran.status, 0, ran.stderr);
+  const report = JSON.parse(ran.stdout);
+  assert.deepEqual(report.changed, ["api.md"]);
+  assert.deepEqual(report.unmapped, ["docs/extra.md"]);
+  assert.deepEqual(report.humanOwned, ["人工页"]);
+});