create-yss-spec 3.5.0 → 3.5.3

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

@@ -1,21 +1,20 @@
 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" },
+        alpha: { effectiveHash: "bbb" }
       },
       platform: {
         ".codex/skills": {
           "product-design": { effectiveHash: "ccc" },
-          "data-analytics": { effectiveHash: "ddd" },
-        },
-      },
-    },
+          "data-analytics": { effectiveHash: "ddd" }
+        }
+      }
+    }
   });
   assert.match(text, /## shared/);
   assert.match(text, /## platform/);
@@ -24,11 +23,9 @@ test("skill-names lists shared and platform keys, sorted, without hashes", () =>
   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/.pi/skills/llm-wiki/scripts/feedback.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadManifest, safePath, sha256, json, fail, args, cliError, assertReadable } from "./core.mjs";
+import { createPlan, applyPlan } from "./transaction.mjs";
+async function feedbackPlan({ wikiRoot, repoRoot = process.cwd(), request }) {
+  await assertReadable(wikiRoot);
+  const manifest = await loadManifest(wikiRoot, { repoRoot });
+  if (manifest.schemaVersion !== 2) fail("MIGRATION_REQUIRED", "feedback requires v2");
+  manifest.feedback ||= [];
+  const a = manifest.articles.find((a2) => a2.id === request.articleId);
+  if (!a) fail("UNKNOWN_ARTICLE_ID", request.articleId);
+  const text = await readFile(await safePath(wikiRoot, a.file), "utf8"), digest = sha256(text), existing = manifest.feedback.find((f) => f.id === request.id);
+  if (!request.id || !request.issue || !request.locator?.quote) fail("FEEDBACK_INVALID", "id, issue and quoted locator required");
+  if (request.targetDigest !== digest) fail("FEEDBACK_REANCHOR_REQUIRED", "target changed; locate quoted text on current version");
+  const index = text.indexOf(request.locator.quote);
+  if (index < 0 || text.indexOf(request.locator.quote, index + 1) >= 0) fail("FEEDBACK_REANCHOR_REQUIRED", "quote must match exactly once");
+  const state = request.status || "open";
+  if (!["open", "accepted", "partial", "rejected", "deferred"].includes(state)) fail("FEEDBACK_INVALID", "status");
+  const record = { id: request.id, articleId: a.id, targetDigest: digest, locator: { quote: request.locator.quote, startLine: text.slice(0, index).split("\n").length }, issue: request.issue, status: state, history: existing?.history || [] };
+  if (existing && existing.articleId !== a.id) fail("FEEDBACK_ID_CONFLICT", request.id);
+  if (["accepted", "partial"].includes(state)) {
+    const r = request.resolution;
+    if (!existing || !r?.transactionId || r.beforeDigest !== existing.targetDigest || r.afterDigest !== digest || r.beforeDigest === r.afterDigest || !r.note) fail("FEEDBACK_EVIDENCE_REQUIRED", "actual change and verification required");
+    const j = JSON.parse(await readFile(await safePath(wikiRoot, `.wiki-staging/${r.transactionId}/completed.json`), "utf8"));
+    if (j.phase !== "finalized" || !j.writes?.some((w) => w.path === a.file && w.before === r.beforeDigest && w.after === r.afterDigest) || a.verification?.articleDigest !== digest) fail("FEEDBACK_EVIDENCE_REQUIRED", "completed article modification and verified compilation required");
+    record.resolution = r;
+  } else if (state !== "open") {
+    if (!request.resolution?.note) fail("FEEDBACK_EVIDENCE_REQUIRED", "disposition reason required");
+    record.resolution = request.resolution;
+  }
+  const comparable = (f) => JSON.stringify({ ...f, history: void 0 });
+  if (existing && comparable(existing) === comparable(record)) return { duplicate: true, id: record.id };
+  if (existing && existing.status === "open" && state === "open" && existing.issue !== record.issue) fail("FEEDBACK_ID_CONFLICT", "existing feedback differs");
+  record.history = [...record.history, { at: request.at || (/* @__PURE__ */ new Date()).toISOString(), status: state, targetDigest: digest }];
+  if (existing) manifest.feedback[manifest.feedback.indexOf(existing)] = record;
+  else manifest.feedback.push(record);
+  return createPlan({ wikiRoot, repoRoot, request: { operation: "feedback", manifest, authorization: { confirmed: request.confirmed === true, paths: [".wiki-manifest.json", "wiki/log.md"] } } });
+}
+async function main() {
+  const a = args(process.argv.slice(2));
+  if (!a.wiki || !a.request) fail("USAGE", "--wiki --request [--apply]");
+  const options = { wikiRoot: path.resolve(a.repo, a.wiki), repoRoot: path.resolve(a.repo) };
+  const plan = await feedbackPlan({ ...options, request: JSON.parse(await readFile(a.request, "utf8")) });
+  process.stdout.write(json(a.apply && !plan.duplicate ? await applyPlan({ ...options, plan }) : plan));
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) main().catch(cliError);
+export {
+  feedbackPlan
+};

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

@@ -1,174 +1,46 @@
 #!/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;
-  });
-}
+import { sha256, exists, loadManifest, args, cliError, transactionState } from "./core.mjs";
+import { observeSource, inspectArticles } from "./sources.mjs";
+const resolveWikiRoot = (arg, cwd = process.cwd()) => {
+  if (!arg) throw new Error("missing --wiki");
+  return path.resolve(cwd, arg);
+};
+const manifestPath = (root) => path.join(root, ".wiki-manifest.json");
+const normalizeLivePath = (p) => String(p || "").replace(/\\/g, "/").replace(/^\.\/+/, "");
+function unmappedCandidates(sources, candidates = []) {
+  const mapped = new Set(sources.map((s) => normalizeLivePath(s.livePath)));
+  return [...new Set(candidates.map(normalizeLivePath).filter((p) => p && !mapped.has(p)))];
+}
+async function hashSources({ wikiRoot, repoRoot = process.cwd() }) {
+  const manifest = await loadManifest(wikiRoot, { repoRoot });
+  const observations = [];
+  for (const s of manifest.sources) observations.push(await observeSource(s, { wikiRoot, repoRoot }));
+  return { manifest, observations, hashed: observations.length, missing: observations.filter((s) => s.state === "missing").map((s) => s.id), readOnly: true, transaction: await transactionState(wikiRoot) };
+}
+async function drift({ wikiRoot, repoRoot = process.cwd(), candidates = [], articleIds, reader }) {
+  const manifest = await loadManifest(wikiRoot, { repoRoot });
+  const report = await inspectArticles(manifest, { wikiRoot, repoRoot, articleIds, reader });
+  const select = (state) => report.sourceStates.filter((s) => s.state === state).map((s) => s.id);
+  return { changed: select("stale"), missing: select("missing"), unchanged: select("current"), unverified: select("unverified"), archived: select("archived"), articles: report.articleStates.filter((a) => a.state !== "current" && a.state !== "archived").map((a) => a.id), unmapped: unmappedCandidates(manifest.sources, candidates), humanOwned: report.articleStates.filter((a) => a.humanOwned).map((a) => a.id), ...report };
+}
+async function main() {
+  const a = args(process.argv.slice(2), ["hash", "drift", "status"]);
+  const options = { wikiRoot: resolveWikiRoot(a.wiki, a.repo), repoRoot: path.resolve(a.repo), candidates: a.candidates };
+  const result = a.command === "hash" ? await hashSources(options) : await drift(options);
+  if (a.command === "hash") delete result.manifest;
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) main().catch(cliError);
+export {
+  drift,
+  exists,
+  hashSources,
+  loadManifest,
+  manifestPath,
+  normalizeLivePath,
+  resolveWikiRoot,
+  sha256,
+  unmappedCandidates
+};

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

@@ -1,18 +1,25 @@
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
-import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, writeFile, readFile } 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 });
+  await mkdir(path.join(wiki, "wiki"));
+  await writeFile(path.join(wiki, "raw/api.md"), "v1\n");
+  for (const id of ["API契约", "人工页"]) await writeFile(path.join(wiki, `wiki/${id}.md`), `# ${id}
+
+Summary.
+
+## 来源
+- api.md
+`);
   const liveRel = "docs/api.md";
   const live = path.join(repo, liveRel);
   await mkdir(path.dirname(live), { recursive: true });
@@ -29,28 +36,31 @@ async function seed() {
           kind: "document",
           livePath: liveRel,
           rawPath: "raw/api.md",
-          sha256: "",
-          role: "copy",
-        },
+          sha256: sha256("v1\n"),
+          role: "copy"
+        }
       ],
       articles: [
         { id: "API契约", file: "wiki/API契约.md", sourceIds: ["api.md"], humanOwned: false },
-        { id: "人工页", file: "wiki/人工页.md", sourceIds: ["api.md"], humanOwned: true },
-      ],
+        { id: "人工页", file: "wiki/人工页.md", sourceIds: ["api.md"], humanOwned: true }
+      ]
     }),
-    "utf8",
+    "utf8"
   );
   return { repo, wiki, live, liveRel };
 }
-
-test("hash-sources fills sha256; drift is empty until live file changes", async () => {
+test("hash-sources only observes; v1 remains unverified until compiled", async () => {
   const { repo, wiki, live } = await seed();
+  const before = await readFile(path.join(wiki, ".wiki-manifest.json"));
   const hashed = await hashSources({ wikiRoot: wiki, repoRoot: repo, now: "2026-01-01T00:00:00Z" });
   assert.equal(hashed.missing.length, 0);
+  assert.deepEqual(await readFile(path.join(wiki, ".wiki-manifest.json")), before);
+  assert.equal(hashed.observations[0].originalDigest, sha256("v1\n"));
   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, []);
+  assert.deepEqual(clean.articles, ["API契约", "人工页"]);
+  assert.equal(clean.articleStates.every((a) => a.state === "unverified"), true);
   await writeFile(live, "v2\n", "utf8");
   const dirty = await drift({ wikiRoot: wiki, repoRoot: repo });
   assert.deepEqual(dirty.changed, ["api.md"]);
@@ -58,20 +68,18 @@ test("hash-sources fills sha256; drift is empty until live file changes", async
   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",
+    "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",
+    encoding: "utf8"
   });
   assert.equal(ran.status, 0, ran.stderr);
   const report = JSON.parse(ran.stdout);
@@ -80,7 +88,6 @@ test("drift CLI exits 0 when sources changed and prints JSON", async () => {
   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" });
@@ -88,7 +95,7 @@ test("status CLI exits 0 and lists unmapped candidates", async () => {
   const ran = spawnSync(
     process.execPath,
     [inventoryCli, "status", "--wiki", wiki, "--repo", repo, "--candidate", "docs/extra.md"],
-    { encoding: "utf8" },
+    { encoding: "utf8" }
   );
   assert.equal(ran.status, 0, ran.stderr);
   const report = JSON.parse(ran.stdout);

package/template/.pi/skills/llm-wiki/scripts/lint-wikilinks.mjs

@@ -2,31 +2,28 @@
 import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { EXTRACT_KINDS } from "./extract.mjs";
-import { exists, sha256 } from "./inventory.mjs";
-
-export const INFRA = new Set([
+import { exists, safePath, frontmatter, sourceSection, validateManifest, checkPaths, ownership, transactionState, cliError } from "./core.mjs";
+import { drift } from "./inventory.mjs";
+const INFRA = /* @__PURE__ */ new Set([
   "index.md",
   "log.md",
   "claude.md",
   "agents.md",
   "soul.md",
-  "concept-table.md",
+  "concept-table.md"
 ]);
 const WIKILINK_RE = /\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]/g;
 const SOURCE_HEADING_RE = /^##\s+来源\s*$/m;
 const H1_RE = /^#\s+(.+?)\s*$/m;
-
-export function articlesDir(wikiRoot) {
+function articlesDir(wikiRoot) {
   return path.join(wikiRoot, "wiki");
 }
-
-export function extractLinks(text) {
+function extractLinks(text) {
   const ids = [];
   const invalid = [];
   WIKILINK_RE.lastIndex = 0;
   let match;
-  while ((match = WIKILINK_RE.exec(text))) {
+  while (match = WIKILINK_RE.exec(text)) {
     const target = match[1].trim();
     if (!target) continue;
     if (target.startsWith("../") || target.includes("/")) {
@@ -37,34 +34,61 @@ export function extractLinks(text) {
   }
   return { ids, invalid };
 }
-
-export async function lintWiki(wikiRoot, { repoRoot = process.cwd() } = {}) {
+async function lintWiki(wikiRoot, { repoRoot = process.cwd(), structureOnly = false } = {}) {
+  const errors = [];
+  let manifest;
+  try {
+    const mf = await safePath(wikiRoot, ".wiki-manifest.json");
+    if (await exists(mf)) {
+      manifest = JSON.parse(await readFile(mf, "utf8"));
+      errors.push(...validateManifest(manifest));
+      if (!errors.length) await checkPaths(manifest, { wikiRoot, repoRoot });
+    }
+    await safePath(wikiRoot, "wiki/index.md");
+  } catch (error) {
+    errors.push(error.message);
+  }
+  if (errors.length) {
+    try {
+      const files = await readdir(await safePath(wikiRoot, "wiki"));
+      for (const file of files.filter((f) => f.endsWith(".md") && !INFRA.has(f.toLowerCase())))
+        if (!manifest?.articles?.some((a) => a.file === `wiki/${file}`)) errors.push(`UNLISTED ARTICLE: ${file}`);
+    } catch {
+    }
+    return { ok: false, errors, counts: {} };
+  }
   const dir = articlesDir(wikiRoot);
-  if (!(await exists(path.join(dir, "index.md")))) {
+  if (!await exists(path.join(dir, "index.md"))) {
     return { ok: false, errors: [`missing ${path.join(dir, "index.md")}`], counts: {} };
   }
   const names = (await readdir(dir)).filter((name) => name.endsWith(".md"));
   const articleFiles = names.filter((name) => !INFRA.has(name.toLowerCase()));
   const articleIds = new Set(articleFiles.map((name) => name.slice(0, -3)));
-  const errors = [];
   let linkCount = 0;
-
-  const indexText = await readFile(path.join(dir, "index.md"), "utf8");
+  const indexText = await readFile(await safePath(wikiRoot, "wiki/index.md"), "utf8");
   const indexLinks = extractLinks(indexText);
   linkCount += indexLinks.ids.length;
   for (const target of indexLinks.invalid) errors.push(`CROSS-WIKI (index): [[${target}]]`);
-  const indexed = new Set();
+  const indexed = /* @__PURE__ */ new Set();
   for (const id of indexLinks.ids) {
     indexed.add(id);
     if (!articleIds.has(id)) errors.push(`MISSING (index): [[${id}]]`);
   }
-
   for (const file of articleFiles) {
     const id = file.slice(0, -3);
-    const text = await readFile(path.join(dir, file), "utf8");
+    let text;
+    try {
+      text = await readFile(await safePath(wikiRoot, `wiki/${file}`), "utf8");
+      frontmatter(text);
+    } catch (error) {
+      errors.push(error.message);
+      continue;
+    }
     const heading = text.match(H1_RE);
     if (!heading || heading[1] !== id) errors.push(`H1 MISMATCH: ${file} expected # ${id}`);
-    if (!SOURCE_HEADING_RE.test(text)) errors.push(`NO SOURCE SECTION: ${file}`);
+    if (!sourceSection(text)) errors.push(`NO SOURCE SECTION: ${file}`);
+    const article = manifest?.articles.find((a) => a.id === id);
+    if (article && ownership(article, text).conflict) errors.push(`OWNERSHIP_CONFLICT: ${id}`);
     if (!indexed.has(id)) errors.push(`ORPHAN: ${file}`);
     const links = extractLinks(text);
     for (const target of links.invalid) errors.push(`CROSS-WIKI: ${file} -> [[${target}]]`);
@@ -73,76 +97,25 @@ export async function lintWiki(wikiRoot, { repoRoot = process.cwd() } = {}) {
       if (!articleIds.has(target)) errors.push(`MISSING: ${file} -> [[${target}]]`);
     }
   }
-
-  const manifestFile = path.join(wikiRoot, ".wiki-manifest.json");
-  if (await exists(manifestFile)) {
-    const manifest = JSON.parse(await readFile(manifestFile, "utf8"));
-    const sourceById = new Map();
-    for (const source of manifest.sources || []) {
-      if (source?.id) sourceById.set(source.id, source);
-    }
-    const listedFiles = new Set();
-    for (const article of manifest.articles || []) {
-      const rel = path.posix.normalize(article.file || "");
-      listedFiles.add(rel);
-      const expectedId = path.posix.basename(rel, ".md");
-      if (article.id !== expectedId) {
-        errors.push(`MANIFEST ID MISMATCH: ${article.file} id=${article.id} expected ${expectedId}`);
-      }
-      const file = path.resolve(wikiRoot, article.file);
-      if (!(await exists(file))) errors.push(`MANIFEST ARTICLE MISSING: ${article.file}`);
-      for (const sourceId of article.sourceIds || []) {
-        if (!sourceById.has(sourceId)) {
-          errors.push(`UNKNOWN SOURCE ID: ${article.id} -> ${sourceId}`);
-        }
-      }
-    }
-    for (const file of articleFiles) {
-      const rel = path.posix.join("wiki", file);
-      if (!listedFiles.has(rel)) errors.push(`UNLISTED ARTICLE: ${file}`);
-    }
-    for (const source of manifest.sources || []) {
-      if (manifest.profile === "documents" && source.kind === "code-surface") {
-        errors.push(`PROFILE KIND: documents forbids code-surface (${source.id})`);
-      }
-      if (source.kind === "document" || source.kind === "derived") {
-        if (!source.rawPath) {
-          errors.push(`RAW PATH REQUIRED: ${source.id} (${source.kind})`);
-        } else {
-          const raw = path.resolve(wikiRoot, source.rawPath);
-          if (!(await exists(raw))) errors.push(`RAW MISSING: ${source.id} (${source.rawPath})`);
-        }
-      }
-      if (source.kind === "derived") {
-        const extractKind = source.extract?.kind;
-        if (!extractKind) errors.push(`EXTRACT REQUIRED: ${source.id}`);
-        else if (!EXTRACT_KINDS.includes(extractKind)) {
-          errors.push(`EXTRACT KIND: ${source.id} (${extractKind})`);
-        }
-      }
-      if (source.kind === "code-surface" && source.rawPath != null) {
-        errors.push(`RAW PATH FORBIDDEN: ${source.id} (code-surface)`);
-      }
-      if (!source.livePath) continue;
-      const live = path.resolve(repoRoot, source.livePath);
-      if (!(await exists(live))) {
-        errors.push(`MANIFEST SOURCE MISSING: ${source.id} (${source.livePath})`);
-        continue;
-      }
-      const current = sha256(await readFile(live));
-      if (!source.sha256 || current !== source.sha256) {
-        errors.push(`STALE HASH: ${source.id} (${source.livePath})`);
-      }
+  if (manifest) {
+    const listed = new Set(manifest.articles.map((a) => a.file));
+    for (const file of articleFiles) if (!listed.has(`wiki/${file}`)) errors.push(`UNLISTED ARTICLE: ${file}`);
+    for (const a of manifest.articles) if (!await exists(await safePath(wikiRoot, a.file))) errors.push(`MANIFEST ARTICLE MISSING: ${a.file}`);
+    for (const s of manifest.sources) if (s.rawPath && !await exists(await safePath(wikiRoot, s.rawPath))) errors.push(`RAW MISSING: ${s.id} (${s.rawPath})`);
+    if (!structureOnly) {
+      const report = await drift({ wikiRoot, repoRoot });
+      for (const s of report.sourceStates) if (!["current", "archived"].includes(s.state)) errors.push(`STALE HASH / ${s.state}: ${s.id} (${s.reason})`);
+      for (const a of report.articleStates) if (!["current", "archived"].includes(a.state)) errors.push(`ARTICLE ${a.state}: ${a.id} (${a.reason})`);
     }
   }
-
+  const tx = await transactionState(wikiRoot);
+  if (tx.incomplete || tx.state === "locked") errors.push("TRANSACTION_INCOMPLETE");
   return {
     ok: errors.length === 0,
     errors,
-    counts: { articles: articleFiles.length, links: linkCount },
+    counts: { articles: articleFiles.length, links: linkCount }
   };
 }
-
 async function main(argv = process.argv.slice(2)) {
   let wikiArg;
   let repoRoot = process.cwd();
@@ -155,23 +128,27 @@ async function main(argv = process.argv.slice(2)) {
     throw new Error("usage: lint-wikilinks.mjs <wiki-root> [--repo <repo-root>]");
   }
   const wikiRoot = path.resolve(repoRoot, wikiArg);
-  const result = await lintWiki(wikiRoot, { repoRoot });
-  for (const error of result.errors) process.stdout.write(`${error}\n`);
+  const result = await lintWiki(wikiRoot, { repoRoot, structureOnly: argv.includes("--structure-only") });
+  for (const error of result.errors) process.stdout.write(`${error}
+`);
   process.stdout.write(
-    `校验完成：${result.counts.articles || 0} 篇文章，${result.counts.links || 0} 条 wikilink\n`,
+    `校验完成：${result.counts.articles || 0} 篇文章，${result.counts.links || 0} 条 wikilink
+`
   );
   if (result.ok) process.stdout.write("通过：所有 wikilink / 来源 / 索引检查通过\n");
   else {
     process.stdout.write(
-      "失败：存在缺失的 wikilink、孤儿页、来源小节、跨路径链接、H1 或 manifest 闭合问题\n",
+      "失败：存在缺失的 wikilink、孤儿页、来源小节、跨路径链接、H1 或 manifest 闭合问题\n"
     );
     process.exitCode = 1;
   }
 }
-
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main().catch((error) => {
-    process.stderr.write(`${error.message}\n`);
-    process.exitCode = 2;
-  });
+  main().catch(cliError);
 }
+export {
+  INFRA,
+  articlesDir,
+  extractLinks,
+  lintWiki
+};