create-yss-spec 2.1.10 → 2.1.13

package/template/.trae/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/.trae/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, ["人工页"]);
+});

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

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+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([
+  "index.md",
+  "log.md",
+  "claude.md",
+  "agents.md",
+  "soul.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) {
+  return path.join(wikiRoot, "wiki");
+}
+
+export function extractLinks(text) {
+  const ids = [];
+  const invalid = [];
+  WIKILINK_RE.lastIndex = 0;
+  let match;
+  while ((match = WIKILINK_RE.exec(text))) {
+    const target = match[1].trim();
+    if (!target) continue;
+    if (target.startsWith("../") || target.includes("/")) {
+      invalid.push(target);
+      continue;
+    }
+    ids.push(target);
+  }
+  return { ids, invalid };
+}
+
+export async function lintWiki(wikiRoot, { repoRoot = process.cwd() } = {}) {
+  const dir = articlesDir(wikiRoot);
+  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 indexLinks = extractLinks(indexText);
+  linkCount += indexLinks.ids.length;
+  for (const target of indexLinks.invalid) errors.push(`CROSS-WIKI (index): [[${target}]]`);
+  const indexed = 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");
+    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 (!indexed.has(id)) errors.push(`ORPHAN: ${file}`);
+    const links = extractLinks(text);
+    for (const target of links.invalid) errors.push(`CROSS-WIKI: ${file} -> [[${target}]]`);
+    for (const target of links.ids) {
+      linkCount += 1;
+      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})`);
+      }
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    counts: { articles: articleFiles.length, links: linkCount },
+  };
+}
+
+async function main(argv = process.argv.slice(2)) {
+  let wikiArg;
+  let repoRoot = process.cwd();
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--repo") repoRoot = argv[++i];
+    else if (!wikiArg && !argv[i].startsWith("-")) wikiArg = argv[i];
+  }
+  repoRoot = path.resolve(repoRoot);
+  if (!wikiArg) {
+    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`);
+  process.stdout.write(
+    `校验完成：${result.counts.articles || 0} 篇文章，${result.counts.links || 0} 条 wikilink\n`,
+  );
+  if (result.ok) process.stdout.write("通过：所有 wikilink / 来源 / 索引检查通过\n");
+  else {
+    process.stdout.write(
+      "失败：存在缺失的 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;
+  });
+}

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

@@ -0,0 +1,212 @@
+import assert from "node:assert/strict";
+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 { lintWiki } from "./lint-wikilinks.mjs";
+
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const broken = path.join(skillRoot, "assets/fixtures/broken-wiki");
+
+test("broken fixture fails on dangling wikilink", async () => {
+  const result = await lintWiki(broken);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((line) => line.includes("[[不存在的页]]")));
+});
+
+test("complete wiki passes wikilink, index, and source-section checks", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "llm-wiki-lint-"));
+  const wiki = path.join(root, "wiki");
+  await mkdir(wiki, { recursive: true });
+  await writeFile(
+    path.join(wiki, "index.md"),
+    "# index\n\n## 分类\n\n- [[Alpha]]\n",
+    "utf8",
+  );
+  await writeFile(
+    path.join(wiki, "Alpha.md"),
+    "# Alpha\n\nSee [[Alpha]].\n\n## 来源\n\n- live\n",
+    "utf8",
+  );
+  await writeFile(path.join(wiki, "CLAUDE.md"), "# schema\n", "utf8");
+  const result = await lintWiki(root);
+  assert.equal(result.ok, true, result.errors.join("\n"));
+  assert.equal(result.counts.articles, 1);
+});
+
+test("cross-path wikilink fails instead of being ignored", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "llm-wiki-cross-"));
+  const wiki = path.join(root, "wiki");
+  await mkdir(wiki, { recursive: true });
+  await writeFile(path.join(wiki, "index.md"), "# index\n\n## 分类\n\n- [[Alpha]]\n", "utf8");
+  await writeFile(
+    path.join(wiki, "Alpha.md"),
+    "# Alpha\n\nSee [[../other]]\n\n## 来源\n\n- live\n",
+    "utf8",
+  );
+  const result = await lintWiki(root);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((line) => line.includes("CROSS-WIKI") && line.includes("[[../other]]")));
+});
+
+test("manifest sha256 mismatch is stale", async () => {
+  const repo = await mkdtemp(path.join(tmpdir(), "llm-wiki-hash-"));
+  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 });
+  const liveRel = "docs/api.md";
+  await writeFile(path.join(repo, liveRel), "v2\n", "utf8");
+  await writeFile(path.join(wikiRoot, "raw", "api.md"), "v1\n", "utf8");
+  await writeFile(path.join(wiki, "index.md"), "# index\n\n## 分类\n\n- [[API]]\n", "utf8");
+  await writeFile(path.join(wiki, "API.md"), "# API\n\nSummary.\n\n## 来源\n\n- live\n", "utf8");
+  await writeFile(
+    path.join(wikiRoot, ".wiki-manifest.json"),
+    JSON.stringify({
+      schemaVersion: 1,
+      sources: [
+        {
+          id: "api.md",
+          kind: "document",
+          livePath: liveRel,
+          rawPath: "raw/api.md",
+          sha256: sha256(Buffer.from("v1\n")),
+        },
+      ],
+      articles: [{ id: "API", file: "wiki/API.md", sourceIds: ["api.md"] }],
+    }),
+    "utf8",
+  );
+  const result = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((line) => line.includes("STALE HASH") && line.includes("api.md")));
+});
+
+async function seedClosedWiki() {
+  const repo = await mkdtemp(path.join(tmpdir(), "llm-wiki-closed-"));
+  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 });
+  const liveRel = "docs/api.md";
+  await writeFile(path.join(repo, liveRel), "v1\n", "utf8");
+  await writeFile(path.join(wikiRoot, "raw", "api.md"), "v1\n", "utf8");
+  await writeFile(path.join(wiki, "index.md"), "# index\n\n## 分类\n\n- [[Alpha]]\n", "utf8");
+  await writeFile(
+    path.join(wiki, "Alpha.md"),
+    "# Alpha\n\nSee [[Alpha]].\n\n## 来源\n\n- live\n",
+    "utf8",
+  );
+  const manifest = {
+    schemaVersion: 1,
+    profile: "documents",
+    sources: [
+      {
+        id: "api.md",
+        kind: "document",
+        livePath: liveRel,
+        rawPath: "raw/api.md",
+        sha256: sha256(Buffer.from("v1\n")),
+      },
+    ],
+    articles: [{ id: "Alpha", file: "wiki/Alpha.md", sourceIds: ["api.md"] }],
+  };
+  await writeFile(path.join(wikiRoot, ".wiki-manifest.json"), JSON.stringify(manifest), "utf8");
+  return { repo, wikiRoot, wiki, manifest };
+}
+
+test("closed manifest passes listing, id, sourceIds, profile, and rawPath checks", async () => {
+  const { repo, wikiRoot } = await seedClosedWiki();
+  const result = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(result.ok, true, result.errors.join("\n"));
+});
+
+test("open manifest fails unlisted article, id mismatch, unknown source, profile kind, and rawPath", async () => {
+  const repo = await mkdtemp(path.join(tmpdir(), "llm-wiki-open-"));
+  const wikiRoot = path.join(repo, "wiki-root");
+  const wiki = path.join(wikiRoot, "wiki");
+  await mkdir(wiki, { recursive: true });
+  await mkdir(path.join(repo, "docs"), { recursive: true });
+  await writeFile(path.join(repo, "docs", "api.md"), "v1\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]].\n\n## 来源\n\n- live\n", "utf8");
+  await writeFile(path.join(wiki, "Beta.md"), "# Beta\n\nSee [[Alpha]].\n\n## 来源\n\n- live\n", "utf8");
+  await writeFile(
+    path.join(wikiRoot, ".wiki-manifest.json"),
+    JSON.stringify({
+      schemaVersion: 1,
+      profile: "documents",
+      sources: [
+        {
+          id: "api.md",
+          kind: "code-surface",
+          livePath: "docs/api.md",
+          rawPath: "raw/should-not-exist.md",
+          sha256: sha256(Buffer.from("v1\n")),
+        },
+        {
+          id: "note",
+          kind: "document",
+          livePath: "docs/api.md",
+          rawPath: "",
+          sha256: sha256(Buffer.from("v1\n")),
+        },
+      ],
+      articles: [
+        {
+          id: "WrongId",
+          file: "wiki/Alpha.md",
+          sourceIds: ["api.md", "ghost"],
+        },
+      ],
+    }),
+    "utf8",
+  );
+  const result = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((line) => line.includes("UNLISTED ARTICLE") && line.includes("Beta.md")));
+  assert.ok(result.errors.some((line) => line.includes("MANIFEST ID MISMATCH") && line.includes("WrongId")));
+  assert.ok(result.errors.some((line) => line.includes("UNKNOWN SOURCE ID") && line.includes("ghost")));
+  assert.ok(result.errors.some((line) => line.includes("PROFILE KIND") && line.includes("code-surface")));
+  assert.ok(result.errors.some((line) => line.includes("RAW PATH REQUIRED") && line.includes("note")));
+  assert.ok(result.errors.some((line) => line.includes("RAW PATH FORBIDDEN") && line.includes("api.md")));
+});
+
+test("derived source requires a known extract.kind", async () => {
+  const { repo, wikiRoot, manifest } = await seedClosedWiki();
+  manifest.sources.push({
+    id: "lock",
+    kind: "derived",
+    livePath: "docs/api.md",
+    rawPath: "raw/api.md",
+    sha256: sha256(Buffer.from("v1\n")),
+  });
+  await writeFile(path.join(wikiRoot, ".wiki-manifest.json"), JSON.stringify(manifest), "utf8");
+  const missing = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(missing.ok, false);
+  assert.ok(missing.errors.some((line) => line.includes("EXTRACT REQUIRED") && line.includes("lock")));
+
+  manifest.sources.at(-1).extract = { kind: "whole-file" };
+  await writeFile(path.join(wikiRoot, ".wiki-manifest.json"), JSON.stringify(manifest), "utf8");
+  const unknown = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(unknown.ok, false);
+  assert.ok(unknown.errors.some((line) => line.includes("EXTRACT KIND") && line.includes("whole-file")));
+
+  manifest.sources.at(-1).extract = { kind: "skill-names" };
+  await writeFile(path.join(wikiRoot, ".wiki-manifest.json"), JSON.stringify(manifest), "utf8");
+  const ok = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(ok.ok, true, ok.errors.join("\n"));
+});
+
+test("document rawPath must exist on disk", async () => {
+  const { repo, wikiRoot, manifest } = await seedClosedWiki();
+  manifest.sources[0].rawPath = "raw/missing.md";
+  await writeFile(path.join(wikiRoot, ".wiki-manifest.json"), JSON.stringify(manifest), "utf8");
+  const result = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((line) => line.includes("RAW MISSING") && line.includes("raw/missing.md")));
+});

package/template/.trae/skills/to-spec/SKILL.md

@@ -16,7 +16,7 @@ If the issue tracker or triage label vocabulary is missing, tell the user to run
 
 Check with the user that these seams match their expectations.
 
-3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
+3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-human` triage label. Spec drafts need a human baseline approval before they are `approved`, and before implementation tickets may become `ready-for-agent`. Do not label the Spec itself `ready-for-agent`.
 
 <spec-template>