create-yss-spec 3.5.0 → 3.5.3

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

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

@@ -2,15 +2,27 @@
 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"]);
-
+import { safePath, cliError } from "./core.mjs";
+const EXTRACT_KINDS = Object.freeze(["skill-names", "heading-list", "prose-note"]);
+function extractHeadings(text, input = "") {
+  const lines = [`# heading-list${input ? `: ${input}` : ""}`, ""];
+  let fence = null;
+  for (const [index, line] of text.split(/\r?\n/).entries()) {
+    const marker = line.match(/^\s*(`{3,}|~{3,})/);
+    if (marker) {
+      if (!fence) fence = marker[1][0];
+      else if (fence === marker[1][0]) fence = null;
+      continue;
+    }
+    if (!fence && /^#{1,6}\s+\S/.test(line)) lines.push(`- L${index + 1}: ${line.trim()}`);
+  }
+  return lines.join("\n") + "\n";
+}
 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) {
+function extractSkillNames(lock) {
   if (!lock || typeof lock !== "object" || Array.isArray(lock)) {
     throw new TypeError("skill-names input must be a lock object");
   }
@@ -27,9 +39,9 @@ export function extractSkillNames(lock) {
       lines.push("");
     }
   }
-  return `${lines.join("\n").replace(/\n+$/, "")}\n`;
+  return `${lines.join("\n").replace(/\n+$/, "")}
+`;
 }
-
 async function main(argv = process.argv.slice(2)) {
   const kind = argv[0];
   let input;
@@ -38,18 +50,23 @@ async function main(argv = process.argv.slice(2)) {
     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>");
+  if (!["skill-names", "heading-list"].includes(kind) || !input || !output) {
+    throw new Error("usage: extract.mjs skill-names|heading-list --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`);
+  const inputFile = await safePath(process.cwd(), input);
+  const outputFile = await safePath(process.cwd(), output, { write: true });
+  const content = await readFile(inputFile, "utf8");
+  const text = kind === "skill-names" ? extractSkillNames(JSON.parse(content)) : extractHeadings(content, input);
+  await mkdir(path.dirname(outputFile), { recursive: true });
+  await writeFile(outputFile, text, "utf8");
+  process.stdout.write(`${output}
+`);
 }
-
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main().catch((error) => {
-    process.stderr.write(`${error.message}\n`);
-    process.exitCode = 2;
-  });
+  main().catch(cliError);
 }
+export {
+  EXTRACT_KINDS,
+  extractHeadings,
+  extractSkillNames
+};