create-yss-spec 3.5.0 → 3.5.3

package/template/.agents/skills/llm-wiki/references/transactions.md

@@ -0,0 +1,48 @@
+# 写入事务
+
+init / refresh / rebuild / ingest 使用同一 `plan → apply → verify → finalize` 流程。migrate、feedback 也走此流程。计划和候选草稿放在已授权的工作目录；尚未确认 ingest 时只展示候选，不写 wiki 或 raw。不要把授权字段当作向用户索取重复确认的理由：已确认的一组来源与页面范围可复用。新增页面、冲突处置、人工正文改变超出既有范围时先展示差异，取得真实决定。脚本验证写清单，不能证明字段背后的人类授权。
+
+## 计划请求
+
+Agent 先读 live 输入，准备候选文章、raw、索引和 manifest 元数据，逐条检查关键断言。原文件保持不动。传入 request JSON：
+
+```json
+{
+  "operation": "refresh",
+  "authorization": {"confirmed": true, "paths": ["raw/guide.md", "wiki/术语.md", ".wiki-manifest.json", "wiki/log.md"]},
+  "writes": [{"path": "raw/guide.md", "content": "完整候选内容"}, {"path": "wiki/术语.md", "content": "完整候选文章"}],
+  "compilations": [{
+    "articleId": "术语",
+    "consumed": {"guide": {"effectiveDigest": "实际读取版本的 SHA256", "rawDigest": "候选 raw 的 SHA256", "extractorVersion": "identity-v1"}},
+    "evidence": [{"sourceId": "guide", "inputPath": "docs/guide.md", "startLine": 1, "endLine": 3, "excerptDigest": "选中行的 SHA256", "claim": "文章中的实际断言", "risk": "general"}]
+  }]
+}
+```
+
+示例中的摘要占位符必须替换。`manifest` 可选：init 必须给 [schema](schema.md) v2 草稿；其他模式仅为添加已确认来源、文章或调整导航依赖等元数据提供。已有 articleDigest/compiledFrom/verification 不可手工推进，只由 compilations 更新。原来未核验的外源可摄取但须保留 unverified，不能编造本地 livePath 或 online 核验证据。
+
+source 的 document/code-surface extractorVersion 为 identity-v1；derived 为 `kind:version:`，prose-note 最后再拼 rules 和 inputDigests JSON 的 SHA256。可用 inventory hash observations.version 取得当前版本；新增 raw 尚未落盘时计算候选 raw 摘要。consumed 必须绑定实际读过的输入；计划重算观察值并检查二者一致，不能“随手 hash”充当阅读或语义核验。
+
+```bash
+node <skill-root>/scripts/transaction.mjs plan --wiki <root> --repo <repo> --request <request.json> > <plan.json>
+node <skill-root>/scripts/transaction.mjs apply --wiki <root> --repo <repo> --plan <plan.json>
+```
+
+plan 不写 wiki；返回 sources/articles/protected/conflicts、完整 writes `{path,before,after,content,original}`、inputs 摘要和计划 digest。检查准确范围后应用。source 删除只留 tombstone 与快照，不能删 source 或 article 记录。未被编译的文章保持旧 watermark；更新 raw 不会清除它们的 stale。human-owned 自动正文修改拒绝；已显式授权链接修复时传 `linkRepairs: [articleId]`，脚本严格比较 wikilink 外所有字节，不能夹带正文变更。
+
+apply 先核验全部输入摘要，变化即 PLAN_STALE，必须重新计划。只写计划内文件；内部 `.wiki-staging/<id>/` 保存候选与完成收据，`.wiki-transaction.json` 是恢复记录，`.wiki-lock` 是事务锁，`.wiki-runner-lock` 防止并发恢复。内部文件位于同一 wiki-root，纳入写操作授权；不分发或公开其中的来源原文/备份。共享 index/log/manifest 由主控生成。manifest、日志最后发布；未完成期间查询拒绝读取混合版本。
+
+## 恢复和取消
+
+```bash
+node <skill-root>/scripts/transaction.mjs resume --wiki <root> --repo <repo>
+node <skill-root>/scripts/transaction.mjs abort --wiki <root> --repo <repo>
+```
+
+resume 只补未完成步骤、验证 staging、检查来源是否仍为原计划版本。abort 先检查全部目标，再仅恢复该事务改动；目标被人工修改时停止，绝不覆盖。真实进程崩溃若留下 runner lock，禁止自动抢占：先核实原进程已停止，展示锁和 journal，由用户明确选择清除该残留执行锁后再 resume/abort。事务锁本身由恢复流程管理，不手删以绕过冲突。
+
+相同计划重放复用完成收据，不重复追加日志。aborted 计划是终态，重新执行用新计划 ID。保留内部 journal/staging/收据用于追溯；本轮不自动清理。最终做结构 lint + status + advise，明确剩余 freshness，结构维护完成不等于所有知识 current。
+
+## 人工反馈
+
+`feedback.mjs --wiki <root> --request <feedback.json>` 预览，`--apply` 应用。request 需要 confirmed:true、id、articleId、targetDigest、locator.quote、issue，可加 status。accepted/partial resolution 需要 transactionId/beforeDigest/afterDigest/note，对应实际文章修改且已核验；rejected/deferred 用 resolution.note 记录理由。反馈的重新定位与修复分开，反馈自身不修改文章。

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

@@ -4,7 +4,7 @@
 
 - `# 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.
+- Close with nonempty `## 来源` listing raw/live paths and line ranges actually read. Record factual article dependencies in dependsOnArticles; ordinary links are navigation.
 - 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「见源码」.
 
@@ -25,11 +25,11 @@ Core pages: deep (state machines, HTTP semantics, transactions). Extension pages
 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.
+- Return candidate contents + paths + consumed source versions + claim evidence. Write only isolated staging, never published articles.
+- Orchestrator checks evidence and uses the unified transaction to publish index, articles, manifest and 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.
+Frontmatter `human-owned: true` or manifest `humanOwned: true`. Refresh/rebuild leave the body; only explicitly authorized link repairs may change `[[wikilink]]` targets. Conflicting flags are reported; neither side overrides a true flag. Do not add or rewrite `## Status` on these pages.

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

@@ -2,9 +2,8 @@
 import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { exists } from "./inventory.mjs";
+import { exists, safePath, loadManifest, frontmatter, assertReadable, cliError } from "./core.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;
@@ -13,68 +12,62 @@ 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) {
+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) {
+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) {
+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();
+function highSignalLiterals(text) {
+  const found = /* @__PURE__ */ 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) {
+function collectTerms(text) {
   const body = articleBody(text);
-  const counter = new Map();
+  const counter = /* @__PURE__ */ 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);
+async function loadArticles(wikiRoot) {
+  await assertReadable(wikiRoot);
+  const dir = await safePath(wikiRoot, "wiki");
   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");
+    const text = await readFile(await safePath(wikiRoot, `wiki/${file}`), "utf8");
+    frontmatter(text);
     articles.push({
       id: file.slice(0, -3),
       file,
       text,
-      links: extractLinks(text).ids,
+      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());
+function oneWayLinks(articles) {
+  const inbound = /* @__PURE__ */ new Map();
+  for (const article of articles) inbound.set(article.id, /* @__PURE__ */ new Set());
   for (const article of articles) {
     for (const target of article.links) {
       if (!inbound.has(target)) continue;
@@ -92,10 +85,9 @@ export function oneWayLinks(articles) {
   }
   return findings;
 }
-
-export function missingTermPages(articles) {
+function missingTermPages(articles) {
   const ids = new Set(articles.map((article) => article.id));
-  const counts = new Map();
+  const counts = /* @__PURE__ */ new Map();
   for (const article of articles) {
     const local = collectTerms(article.text);
     for (const [term, count] of local) {
@@ -103,13 +95,9 @@ export function missingTermPages(articles) {
       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));
+  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) {
+function unreferencedRaws(manifest, articles) {
   const cited = articles.map((article) => sourceSection(article.text)).join("\n");
   const findings = [];
   for (const source of manifest.sources || []) {
@@ -119,29 +107,24 @@ export function unreferencedRaws(manifest, articles) {
   }
   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));
+    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);
+      const raw = await safePath(wikiRoot, source.rawPath);
       if (await exists(raw)) chunks.push(await readFile(raw, "utf8"));
     }
     if (source.livePath) {
-      const live = path.resolve(repoRoot, source.livePath);
+      const live = await safePath(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 }) {
+async function evidenceSuspects({ wikiRoot, repoRoot, articles, manifest }) {
   const findings = [];
   for (const article of articles) {
     const literals = highSignalLiterals(articleBody(article.text));
@@ -155,21 +138,17 @@ export async function evidenceSuspects({ wikiRoot, repoRoot, articles, manifest
   }
   return findings;
 }
-
-export async function adviseWiki(wikiRoot, { repoRoot = process.cwd() } = {}) {
+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: [] };
+  const manifestFile = await safePath(wikiRoot, ".wiki-manifest.json");
+  const manifest = await exists(manifestFile) ? await loadManifest(wikiRoot, { repoRoot }) : { sources: [] };
   return {
     oneWayLinks: oneWayLinks(articles),
     missingTermPages: missingTermPages(articles),
     unreferencedRaws: unreferencedRaws(manifest, articles),
-    suspects: await evidenceSuspects({ wikiRoot, repoRoot, articles, manifest }),
+    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) {
@@ -179,18 +158,27 @@ function parseArgs(argv) {
   }
   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`);
+  process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
 }
-
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main().catch((error) => {
-    process.stderr.write(`${error.message}\n`);
-    process.exitCode = 2;
-  });
-}
+  main().catch(cliError);
+}
+export {
+  adviseWiki,
+  articleBody,
+  collectTerms,
+  evidenceSuspects,
+  firstParagraph,
+  highSignalLiterals,
+  loadArticles,
+  missingTermPages,
+  oneWayLinks,
+  sourceSection,
+  unreferencedRaws
+};

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

@@ -8,9 +8,7 @@ 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");
@@ -25,12 +23,12 @@ async function seedAdvise() {
   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",
+    "utf8"
   );
   await writeFile(
     path.join(wiki, "Beta.md"),
     "# Beta\n\nMentions **孤立术语** again.\n\n## 来源\n\n- raw/api.md\n",
-    "utf8",
+    "utf8"
   );
   await writeFile(path.join(wiki, "concept-table.md"), "# concepts\n", "utf8");
   await writeFile(
@@ -44,37 +42,35 @@ async function seedAdvise() {
           kind: "document",
           livePath: "docs/api.md",
           rawPath: "raw/api.md",
-          sha256: sha256(Buffer.from("version one\n")),
+          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")),
-        },
+          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"] },
-      ],
+        { id: "Beta", file: "wiki/Beta.md", sourceIds: ["api.md"] }
+      ]
     }),
-    "utf8",
+    "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 });
+  const lint = await lintWiki(wikiRoot, { repoRoot: repo, structureOnly: true });
   assert.equal(lint.ok, true, lint.errors.join("\n"));
-  const report = await adviseWiki(wikiRoot, { repoRoot: repo });
+  const report = await adviseWiki(wikiRoot, { repoRoot: repo, structureOnly: true });
   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" });
@@ -82,10 +78,9 @@ test("advise CLI exits 0 and prints JSON", async () => {
   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 });
+  const lint = await lintWiki(wikiRoot, { repoRoot: repo, structureOnly: true });
   assert.equal(lint.ok, true, lint.errors.join("\n"));
   assert.equal(lint.counts.articles, 2);
 });

package/template/.agents/skills/llm-wiki/scripts/core.mjs

@@ -0,0 +1,262 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, writeFile, rename, lstat, realpath, mkdir, access } from "node:fs/promises";
+import path from "node:path";
+const STATES = ["current", "stale", "missing", "unverified", "archived"];
+const INFRA = /* @__PURE__ */ new Set(["index.md", "log.md", "claude.md", "agents.md", "soul.md", "concept-table.md"]);
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+const json = (value) => `${JSON.stringify(value, null, 2)}
+`;
+class WikiError extends Error {
+  constructor(code, message) {
+    super(`${code}: ${message}`);
+    this.code = code;
+  }
+}
+function fail(code, message) {
+  throw new WikiError(code, message);
+}
+async function exists(file) {
+  try {
+    await access(file);
+    return true;
+  } catch (e) {
+    if (e.code === "ENOENT") return false;
+    throw e;
+  }
+}
+async function digestFile(file) {
+  try {
+    return sha256(await readFile(file));
+  } catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  }
+}
+function inside(root, target) {
+  const r = path.relative(root, target);
+  return r === "" || !r.startsWith(`..${path.sep}`) && r !== ".." && !path.isAbsolute(r);
+}
+async function safePath(root, ref, { write = false } = {}) {
+  if (typeof ref !== "string" || !ref || ref.includes("\\") || ref.includes("\0") || path.isAbsolute(ref) || ref.split("/").some((x) => ["..", ".", ""].includes(x))) fail("PATH_INVALID", String(ref));
+  const base = path.resolve(root), target = path.resolve(base, ref);
+  if (!inside(base, target) || target === base) fail("PATH_ESCAPE", ref);
+  let baseReal;
+  try {
+    baseReal = await realpath(base);
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+    const parent = path.dirname(base);
+    baseReal = path.join(await realpath(parent), path.basename(base));
+  }
+  let current = base;
+  for (const part of ref.split("/")) {
+    current = path.join(current, part);
+    let st;
+    try {
+      st = await lstat(current);
+    } catch (e) {
+      if (e.code === "ENOENT") continue;
+      throw e;
+    }
+    if (st.isSymbolicLink() && write) fail("SYMLINK_WRITE", ref);
+    let resolved;
+    try {
+      resolved = await realpath(current);
+    } catch {
+      fail("PATH_ESCAPE", `unresolved symlink ${ref}`);
+    }
+    if (!inside(baseReal, resolved)) fail("PATH_ESCAPE", ref);
+  }
+  return target;
+}
+async function atomicWrite(file, content) {
+  await mkdir(path.dirname(file), { recursive: true });
+  const temp = `${file}.${randomUUID()}.tmp`;
+  await writeFile(temp, content, { flag: "wx" });
+  await rename(temp, file);
+}
+function frontmatter(text) {
+  if (!text.startsWith("---\n") && !text.startsWith("---\r\n")) return { humanOwned: false, body: text, fields: {} };
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!m) fail("FRONTMATTER_INVALID", "unterminated header");
+  const fields = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const pair = line.match(/^([\w-]+):\s*(.*?)\s*$/);
+    if (!pair) fail("FRONTMATTER_INVALID", "use flat scalar fields");
+    if (Object.hasOwn(fields, pair[1])) fail("FRONTMATTER_INVALID", `duplicate ${pair[1]}`);
+    fields[pair[1]] = pair[2];
+  }
+  if (fields["human-owned"] !== void 0 && !["true", "false"].includes(fields["human-owned"])) fail("FRONTMATTER_INVALID", "human-owned must be a boolean");
+  return { humanOwned: fields["human-owned"] === "true", fields, body: text.slice(m[0].length) };
+}
+function sourceSection(text) {
+  return text.match(/^##\s+来源\s*\r?\n([\s\S]*)/m)?.[1]?.trim() || "";
+}
+function ownership(article, text) {
+  const fm = frontmatter(text);
+  return { protected: article.humanOwned === true || fm.humanOwned, conflict: article.humanOwned !== void 0 && fm.fields["human-owned"] !== void 0 && article.humanOwned !== fm.humanOwned };
+}
+const array = (v) => Array.isArray(v);
+const unique = (v) => new Set(v).size === v.length;
+const digest = (v) => v === null || /^[a-f0-9]{64}$/.test(v);
+function validateManifest(m) {
+  const errors = [];
+  const check = (ok, code, detail) => {
+    if (!ok) errors.push(`${code}: ${detail}`);
+  };
+  if (!m || typeof m !== "object" || array(m)) return ["MANIFEST_INVALID: expected object"];
+  check([1, 2].includes(m.schemaVersion), "SCHEMA_UNSUPPORTED", m.schemaVersion);
+  check(m.profile === void 0 && m.schemaVersion === 1 || ["mixed", "documents", "code"].includes(m.profile), "PROFILE_INVALID", m.profile);
+  if (!array(m.sources) || !array(m.articles)) return [...errors, "MANIFEST_INVALID: sources and articles must be arrays"];
+  for (const [group, rows] of [["source", m.sources], ["article", m.articles]]) {
+    check(rows.every((x) => x && typeof x.id === "string" && x.id.trim() && (group === "source" || !/[\[\]#|/\\]/.test(x.id))), "ID_INVALID", group);
+    check(unique(rows.map((x) => x?.id)), "DUPLICATE_ID", group);
+  }
+  const sources = new Set(m.sources.map((x) => x?.id)), articles = new Set(m.articles.map((x) => x?.id));
+  check(unique(m.articles.map((x) => x?.file)), "DUPLICATE_FILE", "articles");
+  for (const s of m.sources) {
+    if (!s || typeof s !== "object") continue;
+    check(["document", "derived", "code-surface"].includes(s.kind), "SOURCE_KIND", s.id);
+    if (s.kind === "code-surface") check(typeof s.livePath === "string" && s.livePath.length > 0, "LIVE_PATH_REQUIRED", s.id);
+    check(!(m.profile === "documents" && s.kind === "code-surface"), "PROFILE KIND", s.id + " code-surface");
+    check(s.kind === "code-surface" ? s.rawPath == null : typeof s.rawPath === "string" && s.rawPath.length > 0, s.kind === "code-surface" ? "RAW PATH FORBIDDEN" : "RAW PATH REQUIRED", s.id);
+    if (s.kind === "derived") {
+      if (m.schemaVersion === 2 && s.extract?.kind === "prose-note") check(typeof s.extract.rules === "string" && s.extract.rules.length > 0 && s.extract.inputDigests && typeof s.extract.inputDigests === "object", "EXTRACT_RULES", s.id);
+      check(!!s.extract?.kind, "EXTRACT REQUIRED", s.id);
+      if (s.extract?.kind) check(["skill-names", "heading-list", "prose-note"].includes(s.extract.kind), "EXTRACT KIND", `${s.id} ${s.extract.kind}`);
+      if (m.schemaVersion === 2) {
+        check(typeof s.extract?.version === "string" && !!s.extract.version, "EXTRACT_VERSION", s.id);
+        check(array(s.extract?.inputs) && s.extract.inputs.length > 0 && unique(s.extract.inputs), "EXTRACT_INPUTS", s.id);
+      }
+    }
+    if (s.status !== void 0) check(STATES.includes(s.status), "STATUS_INVALID", s.id);
+    if (m.schemaVersion === 2) {
+      for (const k of ["originalDigest", "effectiveDigest", "rawDigest"]) check(Object.hasOwn(s, k) && digest(s[k]), "DIGEST_INVALID", `${s.id}.${k}`);
+      check(typeof s.location === "string" && s.location.length > 0, "LOCATION_REQUIRED", s.id);
+    }
+  }
+  for (const a of m.articles) {
+    if (!a || typeof a !== "object") continue;
+    check(a.file === `wiki/${a.id}.md` && !INFRA.has(`${a.id}.md`.toLowerCase()), "MANIFEST ID MISMATCH", a.id);
+    check(array(a.sourceIds) && unique(a.sourceIds), "SOURCE_REFS_INVALID", a.id);
+    check(array(a.sourceIds) && (a.sourceIds.length > 0 || array(a.dependsOnArticles) && a.dependsOnArticles.length > 0), "EMPTY_SOURCE_REFS", a.id);
+    for (const id of array(a.sourceIds) ? a.sourceIds : []) check(sources.has(id), "UNKNOWN SOURCE ID", `${a.id} -> ${id}`);
+    if (a.dependsOnArticles !== void 0) check(array(a.dependsOnArticles) && unique(a.dependsOnArticles), "DEPENDENCIES_INVALID", a.id);
+    for (const id of array(a.dependsOnArticles) ? a.dependsOnArticles : []) check(articles.has(id), "UNKNOWN_ARTICLE_ID", `${a.id} -> ${id}`);
+    if (a.aliases !== void 0) check(array(a.aliases) && a.aliases.every((x) => typeof x === "string" && x.trim()), "ALIASES_INVALID", a.id);
+    if (a.humanOwned !== void 0) check(typeof a.humanOwned === "boolean", "OWNERSHIP_INVALID", a.id);
+    if (a.verification !== void 0 && a.verification !== null) check(a.verification && typeof a.verification === "object" && array(a.verification.evidence) && a.verification.evidence.every((e) => e && typeof e === "object" && sources.has(e.sourceId) && ["general", "critical"].includes(e.risk) && typeof e.claim === "string" && e.claim.length > 0 && digest(e.excerptDigest) && e.excerptDigest !== null && typeof e.inputPath === "string" && Number.isInteger(e.startLine) && e.startLine > 0 && Number.isInteger(e.endLine) && e.endLine >= e.startLine) && digest(a.verification.articleDigest) && a.verification.articleDigest !== null, "EVIDENCE_INVALID", a.id);
+    if (a.status !== void 0) check(STATES.includes(a.status), "STATUS_INVALID", a.id);
+    if (m.schemaVersion === 2) {
+      check(digest(a.articleDigest) && Object.hasOwn(a, "articleDigest"), "DIGEST_INVALID", a.id);
+      check(a.compiledFrom && typeof a.compiledFrom === "object" && !array(a.compiledFrom), "COMPILED_FROM_INVALID", a.id);
+      for (const [id, binding] of Object.entries(a.compiledFrom || {})) {
+        check(sources.has(id) && binding && digest(binding.effectiveDigest) && binding.effectiveDigest !== null, "COMPILED_FROM_INVALID", `${a.id}:${id}`);
+      }
+    }
+  }
+  if (errors.length === 0) {
+    try {
+      for (const a of m.articles) sourceClosure(m, a.id);
+    } catch (e) {
+      errors.push(e.message);
+    }
+  }
+  if (m.feedback !== void 0) {
+    check(array(m.feedback), "FEEDBACK_INVALID", "expected array");
+    if (array(m.feedback)) {
+      check(unique(m.feedback.map((f) => f?.id)), "DUPLICATE_ID", "feedback");
+      for (const f of m.feedback) {
+        if (!f || typeof f !== "object") {
+          errors.push("FEEDBACK_INVALID: expected object");
+          continue;
+        }
+        check(typeof f.id === "string" && f.id.length > 0 && articles.has(f.articleId) && digest(f.targetDigest) && f.targetDigest !== null && typeof f.issue === "string" && f.issue.trim() && f.locator && typeof f.locator.quote === "string" && f.locator.quote.length > 0, "FEEDBACK_INVALID", f.id);
+        check(["open", "accepted", "partial", "rejected", "deferred"].includes(f.status), "FEEDBACK_STATUS", f.id);
+      }
+    }
+  }
+  return errors;
+}
+function sourceClosure(m, id, trail = []) {
+  if (trail.includes(id)) fail("DEPENDENCY_CYCLE", [...trail, id].join(" -> "));
+  const a = m.articles.find((x) => x.id === id);
+  if (!a) fail("UNKNOWN_ARTICLE_ID", id);
+  return [.../* @__PURE__ */ new Set([...a.sourceIds || [], ...(a.dependsOnArticles || []).flatMap((dep) => sourceClosure(m, dep, [...trail, id]))])].sort();
+}
+async function checkPaths(m, { wikiRoot, repoRoot }) {
+  for (const s of m.sources) {
+    for (const ref of [s.livePath, ...s.extract?.inputs || []].filter(Boolean)) await safePath(repoRoot, ref);
+    if (s.rawPath) await safePath(wikiRoot, s.rawPath);
+  }
+  for (const a of m.articles) await safePath(wikiRoot, a.file);
+}
+async function loadManifest(wikiRoot, { repoRoot = process.cwd(), validate = true } = {}) {
+  const m = JSON.parse(await readFile(await safePath(wikiRoot, ".wiki-manifest.json"), "utf8"));
+  if (validate) {
+    const errors = validateManifest(m);
+    if (errors.length) fail("MANIFEST_INVALID", errors.join("\n"));
+    await checkPaths(m, { wikiRoot, repoRoot });
+  }
+  return m;
+}
+async function transactionState(wikiRoot, { reader } = {}) {
+  // A writer claims the lock before replacing an earlier finalized journal.
+  // That interval must also block readers.
+  if (await exists(await safePath(wikiRoot, ".wiki-lock"))) return { state: "locked", incomplete: true };
+  const file = await safePath(wikiRoot, ".wiki-transaction.json");
+  if (!await exists(file)) return { state: "none" };
+  const j = JSON.parse(reader ? (await reader(file)).toString() : await readFile(file, "utf8"));
+  return { id: j.id, state: j.phase, incomplete: !["finalized", "aborted"].includes(j.phase) };
+}
+async function assertReadable(wikiRoot, reader) {
+  const tx = await transactionState(wikiRoot, { reader });
+  if (tx.incomplete || tx.state === "locked") fail("TRANSACTION_INCOMPLETE", "explicit resume or abort required; query never recovers");
+  return tx;
+}
+function cliError(e) {
+  process.stderr.write(`${JSON.stringify({ ok: false, code: e.code || "EXECUTION_ERROR", message: e.message })}
+`);
+  process.exitCode = 2;
+}
+function args(argv, commands = []) {
+  const result = { command: commands.length ? argv.shift() : void 0, repo: process.cwd() };
+  if (commands.length && !commands.includes(result.command)) fail("USAGE", commands.join("|"));
+  while (argv.length) {
+    const a = argv.shift();
+    if (a === "--apply" || a === "--structure-only") {
+      result[a.slice(2)] = true;
+    } else if (a.startsWith("--")) {
+      if (!argv.length || argv[0].startsWith("--")) fail("USAGE", `value required ${a}`);
+      const key = a.slice(2);
+      if (key === "candidate") (result.candidates ??= []).push(argv.shift());
+      else result[key] = argv.shift();
+    } else if (!result.wiki) result.wiki = a;
+    else fail("USAGE", a);
+  }
+  return result;
+}
+export {
+  INFRA,
+  STATES,
+  WikiError,
+  args,
+  assertReadable,
+  atomicWrite,
+  checkPaths,
+  cliError,
+  digestFile,
+  exists,
+  fail,
+  frontmatter,
+  json,
+  loadManifest,
+  ownership,
+  safePath,
+  sha256,
+  sourceClosure,
+  sourceSection,
+  transactionState,
+  validateManifest
+};