create-yss-spec 3.5.5 → 3.5.8

package/template/.agents/skills/implement/SKILL.md

@@ -10,6 +10,6 @@ Use /tdd where possible, at pre-agreed seams.
 
 Run typechecking regularly, single test files regularly, and the full test suite once at the end.
 
-Once done, use /code-review to review the work.
+Once implementation and applicable verification are ready, return the candidate and evidence to the lifecycle owner, who dispatches an independent reviewer using /code-review. The implementer fixes reported findings and supplies fresh evidence for the affected conclusions; it does not review its own work or declare acceptance.
 
-Do not commit or push. Implementation authorization does not include git commit/push. Natural language such as "do it and commit" is not structured Git authorization. Stop after review unless a structured Git authorization is already present.
+Git commit and push require separate explicit authorization under the existing user-decision protocol selected by root `AGENTS.md` and the lifecycle owner. The Agent may normalize a real, readable user reply that identifies the Git action and repository/change scope into the required authorization, scope and source-reference fields; do not ask the user to fill internal fields again. Implementation authorization or a generic request to continue does not authorize Git actions, and commit authorization does not authorize push. If the source is unreadable, authorization was revoked or the action exceeds its scope, do not execute that Git action; return the checkpoint judgment for the lifecycle owner.

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

@@ -30,7 +30,7 @@ node <skill-root>/scripts/transaction.mjs apply --wiki <root> --repo <repo> --pl
 
 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、日志最后发布；未完成期间查询拒绝读取混合版本。
+apply 先核验全部输入摘要，变化即 PLAN_STALE，必须重新计划。只写计划内文件；内部 `.wiki-staging/<id>/` 保存候选与完成收据，`.wiki-transaction.json` 是恢复记录，`.wiki-lock` 是事务锁，`.wiki-runner-lock` 防止并发恢复。`template-source` 的 journal、staging、锁和备份由项目 `scripts/lib/maintenance-storage.mjs` 解析到仓外 `maintenance:wiki/<wiki-id>/`；其它 wiki 沿用同一 wiki-root。这些内部文件纳入写操作授权；不分发或公开其中的来源原文/备份。共享 index/log/manifest 由主控生成。manifest、日志最后发布；未完成期间查询拒绝读取混合版本。
 
 ## 恢复和取消
 
@@ -41,7 +41,7 @@ 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。
+相同计划重放复用完成收据，不重复追加日志。aborted 计划是终态，重新执行用新计划 ID。保留内部 journal/staging/收据用于追溯。模板源仓内 `log.md` 只保存最新运行入口，不追加历史；详细计划、旧日志与原字节保存在仓外事务包中。最终做结构 lint + status + advise，明确剩余 freshness，结构维护完成不等于所有知识 current。
 
 ## 人工反馈
 

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

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { readFile, writeFile, rename, lstat, realpath, mkdir, access } from "node:fs/promises";
 import path from "node:path";
+import { pathToFileURL } from 'node:url';
 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");
@@ -69,6 +70,41 @@ async function safePath(root, ref, { write = false } = {}) {
   }
   return target;
 }
+async function wikiHistoryRoot(wikiRoot) {
+  let cursor = path.resolve(wikiRoot);
+  while (true) {
+    const identity = path.join(cursor, 'yss-project.yaml');
+    if (await exists(identity)) {
+      const source = await readFile(identity, 'utf8');
+      if (!/^repository_mode:\s*template-source\s*$/m.test(source)) return null;
+      const helper = path.join(cursor, 'scripts/lib/maintenance-storage.mjs');
+      if (!await exists(helper)) fail('MAINTENANCE_STORAGE_MISSING', 'template-source requires its registered maintenance storage helper');
+      const { resolveMaintenanceOutput } = await import(pathToFileURL(helper).href);
+      return resolveMaintenanceOutput(`maintenance:wiki/${sha256(path.resolve(wikiRoot))}`, { root: cursor });
+    }
+    const parent = path.dirname(cursor);
+    if (parent === cursor) return null;
+    cursor = parent;
+  }
+}
+async function wikiInternalPath(wikiRoot, ref, options = {}) {
+  if (typeof ref === 'string' && /^\.wiki-(?:staging\/|backups\/|transaction\.json$|lock$|runner-lock$)/.test(ref)) {
+    // Validate the same relative path contract before resolving an external file.
+    if (ref.includes('\\') || ref.split('/').some(part => ['..', '.', ''].includes(part))) fail('PATH_INVALID', ref);
+    const historyRoot = await wikiHistoryRoot(wikiRoot);
+    if (historyRoot) {
+      const target = path.join(historyRoot, ref);
+      let cursor = target;
+      while (inside(historyRoot, cursor)) {
+        if (await exists(cursor) && (await lstat(cursor)).isSymbolicLink()) fail('SYMLINK_WRITE', ref);
+        if (cursor === historyRoot) break;
+        cursor = path.dirname(cursor);
+      }
+      return target;
+    }
+  }
+  return safePath(wikiRoot, ref, options);
+}
 async function atomicWrite(file, content) {
   await mkdir(path.dirname(file), { recursive: true });
   const temp = `${file}.${randomUUID()}.tmp`;
@@ -204,8 +240,8 @@ async function loadManifest(wikiRoot, { repoRoot = process.cwd(), validate = tru
 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(await wikiInternalPath(wikiRoot, ".wiki-lock"))) return { state: "locked", incomplete: true };
+  const file = await wikiInternalPath(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) };
@@ -252,6 +288,8 @@ export {
   frontmatter,
   json,
   loadManifest,
+  wikiHistoryRoot,
+  wikiInternalPath,
   ownership,
   safePath,
   sha256,

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

@@ -2,7 +2,7 @@
 import { readFile, writeFile, mkdir, rm, readdir, lstat } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { sha256, json, safePath, atomicWrite, digestFile, exists, loadManifest, validateManifest, checkPaths, ownership, sourceClosure, sourceSection, frontmatter, fail, args, cliError } from "./core.mjs";
+import { sha256, json, wikiInternalPath, wikiHistoryRoot, atomicWrite, digestFile, exists, loadManifest, validateManifest, checkPaths, ownership, sourceClosure, sourceSection, frontmatter, fail, args, cliError } from "./core.mjs";
 import { observeSource, sameVersion } from "./sources.mjs";
 import { extractLinks } from "./lint-wikilinks.mjs";
 const MANIFEST = ".wiki-manifest.json", JOURNAL = ".wiki-transaction.json", LOCK = ".wiki-lock";
@@ -16,7 +16,7 @@ function stripLinks(text) {
   return text.replace(/\[\[[^\]\n]+\]\]/g, "[[LINK]]");
 }
 async function getText(root, ref) {
-  const file = await safePath(root, ref);
+  const file = await wikiInternalPath(root, ref);
   try {
     return await readFile(file, "utf8");
   } catch (e) {
@@ -50,7 +50,7 @@ async function createPlan({ wikiRoot, repoRoot = process.cwd(), request }) {
   if (proposed.size !== (request.writes || []).length) fail("PLAN_INVALID", "duplicate writes");
   const inputs = {}, writes = [];
   const bind = async (kind, root, ref) => {
-    const p = await safePath(root, ref);
+    const p = await wikiInternalPath(root, ref);
     const digest = await digestFile(p);
     inputs[`${kind}:${ref}`] = digest;
     return p;
@@ -82,7 +82,7 @@ async function createPlan({ wikiRoot, repoRoot = process.cwd(), request }) {
   }
   for (const s of prior?.sources || []) if (!manifest.sources.some((x) => x.id === s.id)) fail("SOURCE_REMOVAL_FORBIDDEN", `retain tombstone and snapshot: ${s.id}`);
   for (const [ref, content] of proposed) {
-    await safePath(wikiRoot, ref, { write: true });
+    await wikiInternalPath(wikiRoot, ref, { write: true });
     if ([MANIFEST, "wiki/log.md", LOCK, JOURNAL].includes(ref) || ref.startsWith(".wiki-staging/")) fail("PLAN_INVALID", `reserved ${ref}`);
     if (typeof content !== "string") fail("PLAN_INVALID", "deletion or non-text content");
     const isKnown = manifest.articles.some((a) => a.file === ref) || manifest.sources.some((s) => s.rawPath === ref) || ["wiki/index.md", "wiki/CLAUDE.md", "wiki/AGENTS.md", "wiki/concept-table.md"].includes(ref) || operation === "migrate" && ref.startsWith(".wiki-backups/");
@@ -165,8 +165,8 @@ async function createPlan({ wikiRoot, repoRoot = process.cwd(), request }) {
     for (const id2 of extractLinks(content).ids) if (!manifest.articles.some((x) => x.id === id2)) fail("WIKILINK_MISSING", id2);
     if (extractLinks(content).invalid.length) fail("WIKILINK_INVALID", a.id);
   }
-  if (await exists(await safePath(wikiRoot, "wiki"))) {
-    for (const file of await readdir(await safePath(wikiRoot, "wiki"))) if (file.endsWith(".md") && !["index.md", "log.md", "claude.md", "agents.md", "soul.md", "concept-table.md"].includes(file.toLowerCase()) && !manifest.articles.some((a) => a.file === `wiki/${file}`)) fail("UNLISTED_ARTICLE", file);
+  if (await exists(await wikiInternalPath(wikiRoot, "wiki"))) {
+    for (const file of await readdir(await wikiInternalPath(wikiRoot, "wiki"))) if (file.endsWith(".md") && !["index.md", "log.md", "claude.md", "agents.md", "soul.md", "concept-table.md"].includes(file.toLowerCase()) && !manifest.articles.some((a) => a.file === `wiki/${file}`)) fail("UNLISTED_ARTICLE", file);
   }
   const index = proposed.get("wiki/index.md") ?? await getText(wikiRoot, "wiki/index.md");
   if (index === null) fail("INDEX_MISSING", "wiki/index.md");
@@ -177,14 +177,15 @@ async function createPlan({ wikiRoot, repoRoot = process.cwd(), request }) {
   proposed.set(MANIFEST, json(manifest));
   const id = request.id || sha256(JSON.stringify({ operation, inputs, proposed: [...proposed] })).slice(0, 24);
   if (!/^[a-zA-Z0-9_-]+$/.test(id)) fail("PLAN_INVALID", "id");
-  const priorLog = await getText(wikiRoot, "wiki/log.md") || "# log\n";
+  const historyRoot = await wikiHistoryRoot(wikiRoot);
+  const priorLog = historyRoot ? "# Wiki 当前运行\n" : await getText(wikiRoot, "wiki/log.md") || "# log\n";
   proposed.set("wiki/log.md", `${priorLog.trimEnd()}
 
 ## [${(request.at || (/* @__PURE__ */ new Date()).toISOString()).slice(0, 10)}] ${operation.toUpperCase()} | ${id}
 
 - Changed articles: ${[...compiled].join(", ") || "none"}
 - Remaining freshness must be read from status.
-`);
+${historyRoot ? `- 运行材料：maintenance:wiki/${sha256(path.resolve(wikiRoot))}/.wiki-staging/${id}/completed.json\n` : ""}`);
   for (const [ref, content] of proposed) {
     const old = await getText(wikiRoot, ref);
     if (old === content) continue;
@@ -204,28 +205,30 @@ async function verifyInputs(plan, options, { during = false } = {}) {
   for (const [key, expected] of Object.entries(plan.inputs)) {
     const colon = key.indexOf(":"), kind = key.slice(0, colon), ref = key.slice(colon + 1);
     if (!["repo", "wiki"].includes(kind)) fail("PLAN_INVALID", key);
-    const p = await safePath(kind === "wiki" ? options.wikiRoot : options.repoRoot, ref, { write: kind === "wiki" }), actual = await digestFile(p);
+    const p = await wikiInternalPath(kind === "wiki" ? options.wikiRoot : options.repoRoot, ref, { write: kind === "wiki" }), actual = await digestFile(p);
     const w = kind === "wiki" ? plan.writes.find((w2) => w2.path === ref) : null;
     if (actual !== expected && !(during && w && actual === w.after)) fail("PLAN_STALE", key);
   }
 }
 async function loadJournal(wikiRoot) {
-  const j = JSON.parse(await readFile(await safePath(wikiRoot, JOURNAL), "utf8"));
+  const j = JSON.parse(await readFile(await wikiInternalPath(wikiRoot, JOURNAL), "utf8"));
   if (j.schemaVersion !== 1 || !phases.includes(j.phase) || j.id !== j.plan?.id || !Array.isArray(j.applied)) fail("JOURNAL_INVALID", "invalid journal");
   validatePlan(j.plan);
   return j;
 }
 async function saveJournal(wikiRoot, j) {
-  await atomicWrite(await safePath(wikiRoot, JOURNAL, { write: true }), json(j));
+  await atomicWrite(await wikiInternalPath(wikiRoot, JOURNAL, { write: true }), json(j));
 }
 async function assertLock(wikiRoot, id) {
-  const lock = JSON.parse(await readFile(await safePath(wikiRoot, LOCK), "utf8"));
+  const lock = JSON.parse(await readFile(await wikiInternalPath(wikiRoot, LOCK), "utf8"));
   if (lock.id !== id) fail("LOCK_CONFLICT", "another writer owns the lock");
 }
 async function acquire(wikiRoot, id) {
   await mkdir(wikiRoot, { recursive: true });
   try {
-    await writeFile(await safePath(wikiRoot, LOCK, { write: true }), json({ id }), { flag: "wx" });
+    const file = await wikiInternalPath(wikiRoot, LOCK, { write: true });
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, json({ id }), { flag: "wx" });
   } catch (e) {
     if (e.code === "EEXIST") fail("LOCKED", "explicit resume/abort; never steal a lock");
     throw e;
@@ -233,15 +236,15 @@ async function acquire(wikiRoot, id) {
 }
 async function stage(wikiRoot, plan) {
   for (const [i, w] of plan.writes.entries()) {
-    await atomicWrite(await safePath(wikiRoot, `.wiki-staging/${plan.id}/${i}.txt`, { write: true }), w.content);
+    await atomicWrite(await wikiInternalPath(wikiRoot, `.wiki-staging/${plan.id}/${i}.txt`, { write: true }), w.content);
   }
 }
 async function install(options, j, w, index) {
-  const target = await safePath(options.wikiRoot, w.path, { write: true });
+  const target = await wikiInternalPath(options.wikiRoot, w.path, { write: true });
   const actual = await digestFile(target);
   if (actual !== w.before && actual !== w.after) fail("MANUAL_MODIFICATION", w.path);
   if (actual !== w.after) {
-    const content = await readFile(await safePath(options.wikiRoot, `.wiki-staging/${j.id}/${index}.txt`));
+    const content = await readFile(await wikiInternalPath(options.wikiRoot, `.wiki-staging/${j.id}/${index}.txt`));
     if (sha256(content) !== w.after) fail("STAGING_CHANGED", w.path);
     await atomicWrite(target, content);
   }
@@ -262,7 +265,7 @@ async function applyPlan({ wikiRoot, repoRoot = process.cwd(), plan, stopAfter }
     const j2 = await loadJournal(wikiRoot);
     if (j2.id === plan.id && j2.plan.digest === plan.digest) {
       if (j2.phase === "finalized") {
-        for (const w of j2.plan.writes) if (await digestFile(await safePath(wikiRoot, w.path)) !== w.after) fail("MANUAL_MODIFICATION", w.path);
+        for (const w of j2.plan.writes) if (await digestFile(await wikiInternalPath(wikiRoot, w.path)) !== w.after) fail("MANUAL_MODIFICATION", w.path);
         return { id: j2.id, phase: "finalized", replayed: true };
       }
       fail("TRANSACTION_INCOMPLETE", "use explicit resume");
@@ -281,16 +284,16 @@ async function resumeInternal({ wikiRoot, repoRoot = process.cwd(), stopAfter })
   const j = await loadJournal(wikiRoot);
   const options = { wikiRoot, repoRoot };
   if (["finalized", "aborted"].includes(j.phase)) {
-    if (await exists(await safePath(wikiRoot, LOCK))) {
+    if (await exists(await wikiInternalPath(wikiRoot, LOCK))) {
       await assertLock(wikiRoot, j.id);
-      await rm(await safePath(wikiRoot, LOCK, { write: true }));
+      await rm(await wikiInternalPath(wikiRoot, LOCK, { write: true }));
     }
     return { id: j.id, phase: j.phase, replayed: true };
   }
   await assertLock(wikiRoot, j.id);
   await verifyInputs(j.plan, options, { during: true });
   for (const [i, w] of j.plan.writes.entries()) {
-    const p = await safePath(wikiRoot, `.wiki-staging/${j.id}/${i}.txt`, { write: true });
+    const p = await wikiInternalPath(wikiRoot, `.wiki-staging/${j.id}/${i}.txt`, { write: true });
     if (!await exists(p)) await atomicWrite(p, w.content);
   }
   if (j.phase === "prepared") {
@@ -300,7 +303,7 @@ async function resumeInternal({ wikiRoot, repoRoot = process.cwd(), stopAfter })
     if (stopAfter === "applied") return { id: j.id, phase: j.phase };
   }
   if (j.phase === "applied") {
-    for (const w of j.plan.writes.filter((w2) => ![MANIFEST, "wiki/log.md"].includes(w2.path))) if (await digestFile(await safePath(wikiRoot, w.path)) !== w.after) fail("VERIFY_FAILED", w.path);
+    for (const w of j.plan.writes.filter((w2) => ![MANIFEST, "wiki/log.md"].includes(w2.path))) if (await digestFile(await wikiInternalPath(wikiRoot, w.path)) !== w.after) fail("VERIFY_FAILED", w.path);
     const candidate = j.plan.writes.find((w) => w.path === MANIFEST);
     if (candidate) {
       const errors = validateManifest(JSON.parse(candidate.content));
@@ -315,10 +318,10 @@ async function resumeInternal({ wikiRoot, repoRoot = process.cwd(), stopAfter })
     await install(options, j, w, i);
     if (stopAfter === w.path) return { id: j.id, phase: j.phase };
   }
-  await atomicWrite(await safePath(wikiRoot, `.wiki-staging/${j.id}/completed.json`, { write: true }), json({ id: j.id, digest: j.plan.digest, phase: "finalized", writes: j.plan.writes.map(({ path: path2, before, after }) => ({ path: path2, before, after })) }));
+  await atomicWrite(await wikiInternalPath(wikiRoot, `.wiki-staging/${j.id}/completed.json`, { write: true }), json({ id: j.id, digest: j.plan.digest, phase: "finalized", writes: j.plan.writes.map(({ path: path2, before, after }) => ({ path: path2, before, after })) }));
   j.phase = "finalized";
   await saveJournal(wikiRoot, j);
-  await rm(await safePath(wikiRoot, LOCK, { write: true }));
+  await rm(await wikiInternalPath(wikiRoot, LOCK, { write: true }));
   return { id: j.id, phase: j.phase };
 }
 async function abortInternal({ wikiRoot }) {
@@ -327,12 +330,12 @@ async function abortInternal({ wikiRoot }) {
   if (j.phase === "finalized") fail("TRANSACTION_FINALIZED", "cannot abort published transaction");
   await assertLock(wikiRoot, j.id);
   for (const w of j.plan.writes) {
-    const digest = await digestFile(await safePath(wikiRoot, w.path, { write: true }));
+    const digest = await digestFile(await wikiInternalPath(wikiRoot, w.path, { write: true }));
     if (digest !== w.before && digest !== w.after) fail("MANUAL_MODIFICATION", w.path);
     if (w.before !== null && (typeof w.original !== "string" || sha256(w.original) !== w.before)) fail("BACKUP_INVALID", w.path);
   }
   for (const w of [...j.plan.writes].reverse()) {
-    const p = await safePath(wikiRoot, w.path, { write: true });
+    const p = await wikiInternalPath(wikiRoot, w.path, { write: true });
     if (await digestFile(p) === w.after) {
       if (w.before === null) await rm(p);
       else await atomicWrite(p, w.original);
@@ -340,11 +343,11 @@ async function abortInternal({ wikiRoot }) {
   }
   j.phase = "aborted";
   await saveJournal(wikiRoot, j);
-  await rm(await safePath(wikiRoot, LOCK, { write: true }));
+  await rm(await wikiInternalPath(wikiRoot, LOCK, { write: true }));
   return { id: j.id, phase: j.phase };
 }
 async function exclusive(options, run) {
-  const file = await safePath(options.wikiRoot, ".wiki-runner-lock", { write: true });
+  const file = await wikiInternalPath(options.wikiRoot, ".wiki-runner-lock", { write: true });
   try {
     await writeFile(file, json({ pid: process.pid }), { flag: "wx" });
   } catch (e) {

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

@@ -1,9 +1,9 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtemp, mkdir, readFile, writeFile, rm, readdir, symlink } from "node:fs/promises";
+import { mkdtemp, mkdir, readFile, writeFile, rm, readdir, symlink, cp, realpath } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { sha256, json, loadManifest, sourceClosure, validateManifest, safePath } from "./core.mjs";
+import { sha256, json, loadManifest, sourceClosure, validateManifest, safePath, wikiInternalPath, wikiHistoryRoot } from "./core.mjs";
 import { createPlan, applyPlan, resumeTransaction, abortTransaction, planDigest } from "./transaction.mjs";
 import { drift, hashSources } from "./inventory.mjs";
 import { migrate } from "./migrate.mjs";
@@ -352,3 +352,39 @@ test("query: publication changes during reads cannot produce a mixed answer",asy
 });
 test('ownership: renewing proof for unchanged human content does not rewrite it',async t=>{const f=await fixture(t);const m=await loadManifest(f.wikiRoot,f);m.articles[0].humanOwned=true;await writeFile(path.join(f.wikiRoot,'.wiki-manifest.json'),json(m));const p=await createPlan({...f,request:{operation:'refresh',compilations:[proof()],authorization}});assert.equal(p.writes.some(w=>w.path==='wiki/Alpha.md'),false);await applyPlan({...f,plan:p});assert.equal((await drift(f)).articleStates[0].state,'current');});
 test('schema: malformed references and evidence are validation errors',async t=>{const f=await fixture(t);const m=await loadManifest(f.wikiRoot,f);m.articles[0].sourceIds={};m.articles[0].verification.evidence={};assert.ok(validateManifest(m).some(e=>e.includes('SOURCE_REFS_INVALID')));assert.ok(validateManifest(m).some(e=>e.includes('EVIDENCE_INVALID')));});
+
+test('template-source transactions and migration keep history outside; current log has one run', async t => {
+  const f = await fixture(t, {init:false});
+  const home = await realpath(await mkdtemp(path.join(tmpdir(), 'wiki-external-history-')));
+  const previousHome = process.env.YSS_RUNTIME_HOME;
+  process.env.YSS_RUNTIME_HOME = home;
+  t.after(async () => { if (previousHome === undefined) delete process.env.YSS_RUNTIME_HOME; else process.env.YSS_RUNTIME_HOME = previousHome; await rm(home,{recursive:true,force:true}); });
+  await writeFile(path.join(f.repoRoot,'yss-project.yaml'),'schema_version: 1\nrepository_mode: template-source\n');
+  const sourceRoot = path.resolve(import.meta.dirname,'../../../..');
+  await mkdir(path.join(f.repoRoot,'scripts/lib'),{recursive:true});
+  await mkdir(path.join(f.repoRoot,'scripts/vendor'),{recursive:true});
+  for (const name of ['maintenance-storage.mjs','runtime-store.mjs','repository-mode.mjs']) await cp(path.join(sourceRoot,'scripts/lib',name),path.join(f.repoRoot,'scripts/lib',name));
+  await cp(path.join(sourceRoot,'scripts/vendor/yaml.mjs'),path.join(f.repoRoot,'scripts/vendor/yaml.mjs'));
+  const initial = await createPlan({...f,request:f.request});
+  await applyPlan({...f,plan:initial,stopAfter:'prepared'});
+  const history = await wikiHistoryRoot(f.wikiRoot);
+  assert.ok(history.startsWith(home+path.sep));
+  const journal = JSON.parse(await readFile(await wikiInternalPath(f.wikiRoot,'.wiki-transaction.json'),'utf8'));
+  assert.equal(journal.phase,'prepared');
+  assert.equal((await readdir(f.wikiRoot)).some(name=>name.startsWith('.wiki-')),false);
+  await resumeTransaction(f);
+  const next = await refresh(f);
+  await applyPlan({...f,plan:next});
+  const log = await readFile(path.join(f.wikiRoot,'wiki/log.md'),'utf8');
+  assert.equal((log.match(/^## /gm)||[]).length,1);
+  assert.ok(log.includes(next.id)); assert.ok(!log.includes(initial.id));
+  assert.ok(log.includes('maintenance:wiki/'));
+  assert.equal((await drift(f)).articleStates[0].state,'current');
+  const prior = {schemaVersion:1,profile:'documents',sources:[{id:'guide',kind:'document',livePath:'docs.md',rawPath:'raw/guide.md',sha256:sha256(await readFile(path.join(f.repoRoot,'docs.md')))}],articles:[{id:'Alpha',file:'wiki/Alpha.md',sourceIds:['guide'],humanOwned:false}]};
+  const bytes=json(prior); await writeFile(path.join(f.wikiRoot,'.wiki-manifest.json'),bytes);
+  const migration = await migrate({...f,apply:true});
+  assert.equal(await readFile(await wikiInternalPath(f.wikiRoot,migration.backup),'utf8'),bytes);
+  assert.equal((await readdir(f.wikiRoot)).includes('.wiki-backups'),false);
+  assert.equal((await loadManifest(f.wikiRoot,f)).schemaVersion,2);
+  assert.equal((await drift(f)).articleStates[0].state,'unverified');
+});

package/template/.agents/skills/lombok/SKILL.md

@@ -4,6 +4,8 @@ description: "配置或排查 Lombok 注解、构造器、Builder 和注解处
 ---
 # Project Lombok
 
+只读排障先核验实际对象、工程基线和处理器配置，缺批准 Slice 时记录缺口；写入仍消费批准且当前的工作单元与允许路径。
+
 ## YSS 阶段 7 执行结果
 
 - 消费工程 Java 与处理器基线；Java 语法、API、处理器与测试工具消费批准的精确平台配置。MapStruct binding 进入 annotationProcessorPaths，不作为业务依赖单独引入；示例不授权升级依赖。MVC PO 的身份/敏感字段风险与 DDD 相同，不能默认全量 @Data。

package/template/.agents/skills/mapstruct/SKILL.md

@@ -4,6 +4,8 @@ description: "实现或排查 MapStruct DTO、PO、Domain 映射及 Lombok 集
 ---
 # MapStruct Object Mapping
 
+只读排障先核验实际对象、工程基线和处理器配置，缺批准 Slice 时记录缺口；写入仍消费批准且当前的工作单元与允许路径。
+
 ## YSS 阶段 7 执行结果
 
 - Java、依赖与处理器版本来自工程基线，不从下面通用示例推断。Java 语法、API、处理器与测试工具均消费批准的精确平台配置；MVC 的 wire/internal 转换在 server，core/service 不依赖 client，Repository 不依赖上层 DTO。采用 Spring Bean 和构造器注入，显式映射或忽略字段；禁止通过全局 IGNORE 掩盖合同字段遗漏。

package/template/.agents/skills/tdd/SKILL.md

@@ -19,9 +19,9 @@ See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking g
 
 A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
 
-**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything — agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
+**Test only at pre-agreed seams.** Before writing tests, first read the current approved contract (the Slice Implementation Contract for YSS implementation), its public seam references and the applicable user-decision evidence. Reuse confirmed seams covered by the same valid contract/decision version, scope and basis without asking the user again; follow the existing user-decision protocol selected by root `AGENTS.md` and the lifecycle owner when checking approval continuation.
 
-Ask: "What's the public interface, and which seams should we test?"
+If a seam is missing, newly introduced or materially changed, the contract is `stale`, or confirmation cannot be proved from readable evidence, stop tests and implementation that depend on that seam and return to the lifecycle owner to update the contract and obtain any required decision. Independent work may continue. Elapsed time and unrelated file changes do not expire seam confirmation; changed relevant inputs require freshness and scope checks under the same protocol. No test is written at an unconfirmed seam. Agreeing seams directs testing effort to critical paths and complex logic.
 
 When the shape of that interface is itself in question — how deep the module is, where the seam belongs, what the interface should expose — use the `/codebase-design` skill for the vocabulary. It is the shared source of the module, interface, depth, seam, adapter, leverage and locality terms, and it is a reference to consult, not a session to run.
 

package/template/.agents/skills/theme-token-usage/SKILL.md

@@ -20,12 +20,12 @@ description: "实现或修复 Vue3 YSS UI 主题、交互状态色与动态换
 
 ## 开发前检查
 
-1. 读取当前微应用的 `packages/src/styles/variables.less`、主题 store/config 和相近页面，确认真实 Token 名称与运行时同步逻辑。
+1. 从目标工程实际的主题入口、store/config 和相近页面定位 Token 声明与同步逻辑；`variables.less` 只作为存在时的路径线索。当前 bundled 骨架使用 `packages/src/config/theme.json`、`packages/src/store/theme.ts`、`packages/src/styles/index.less` 与 `ThemeScope.vue`。
 2. 确认主应用传入的 `colorPrimary` 最终是否同步到 Ant Design ConfigProvider、YSS CSS 变量和 VXE 变量。
 3. 搜索本次改动涉及的硬编码色值，覆盖 SFC style、`style.less`、内联 `style`、`:style`、TS 配置、SVG `fill/stroke`。
 4. 区分“主题消费代码”和“主题定义代码”；禁止机械替换主题源文件中的合法默认色板。
 
-> 变量在 `:root` 中声明，不代表它会随运行时主题更新。必须同时检查主题同步代码是否写入该变量。
+> 变量在 `:root` 或应用容器中声明，不代表它会随运行时主题更新。必须同时检查主题同步代码是否写入该变量，以及消费节点是否处于相同作用域。
 
 ## Token 选择
 
@@ -65,8 +65,9 @@ box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color, #3371ff) 15%, tran
 
 ## 标准代码骨架
 
+下面只说明语义 Token 的消费方式；变量名称、fallback 与默认值须先核对目标工程。主题已由应用入口注入时，不另加不存在的 Less 导入。
+
 ```less
-@import url('@/styles/variables.less');
 
 .module-card {
   color: var(--text-color, rgba(0, 0, 0, 0.88));
@@ -94,7 +95,7 @@ box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color, #3371ff) 15%, tran
 }
 ```
 
-仅在 JS、图表或 Canvas 必须读取计算后色值时，优先使用 Ant Design Vue `theme.useToken()`；若消费微应用 CSS 变量，则通过 `getComputedStyle(document.documentElement)` 读取，不复制默认色板到业务常量。
+仅在 JS、图表或 Canvas 必须读取计算后色值时，优先使用当前 ConfigProvider 内的 Ant Design Vue `theme.useToken()`。消费 CSS 变量时，对实际获得主题变量的应用容器或其消费节点调用 `getComputedStyle()`；当前 bundled 微应用只向自己的容器同步变量，不读取或写入宿主 `documentElement`。只有已核验主题同步到文档根节点的独立应用，才从该根节点读取。不复制默认色板到业务常量。
 
 ## 验证流程
 
@@ -117,7 +118,7 @@ box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color, #3371ff) 15%, tran
 
 ## 失败兜底策略
 
-- 找不到 Token 时，先查项目 `variables.less`、主题 store/config 和 `llms-full.txt`；禁止猜测变量名。
+- 找不到 Token 时，先查项目实际主题入口、store/config 和匹配版本的文档；`variables.less` 存在时才读取，禁止猜测变量名或创建同名文件充当输入。
 - 只有颜色值但没有语义 Token 时，先在统一主题源补充语义变量和运行时同步，再在页面消费。
 - 第三方组件不跟随主题时，优先通过 ConfigProvider/component token 或其官方 CSS 变量桥接；最后才使用受控的深度样式覆盖。
 - 浏览器目标不支持 `color-mix()` 时，在主题层生成并同步明确的透明态变量；不要在各页面散落固定透明色。

package/template/.agents/skills/wayfinder/references/chart-map.md

@@ -7,8 +7,8 @@
 User invokes with a loose idea.
 
 1. **Name the destination.** Run a `/grilling` and `/domain-modeling` session to pin down what this map is finding its way to — the spec, decision, or change. The destination fixes the scope, so it's settled first.
-2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed.
+2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. If no open decision remains and the work fits one session, return the settled destination, scope and evidence to the active orchestrator. Continue within the existing authorization; ask only for a missing real decision or new authorization.
 3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
 4. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section.
-5. **Fire the research subagents.** For each `research` ticket you just created, spin up a `/yss-research` subagent to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket. `/research` remains only as a deprecated compatibility alias.
+5. **Dispatch research.** Route independent research tickets to `yss-research` when the runtime supports delegation; otherwise research in the current session. Follow the registered task-package and evidence contracts, and link the resulting sources from the ticket. Read-only intake uses schema v2 with empty write scope; formal research requires a new owner-issued task package. Template maintenance evidence stays in the registered external maintenance directory. Research does not require creating a Git branch.
 6. Stop — charting is one session's work; it hand-resolves nothing.

package/template/.agents/skills/wayfinder/references/ticket-types.md

@@ -6,7 +6,7 @@
 
 Every ticket is either **HITL** — human in the loop, worked _with_ a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
 
-- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/yss-research` **subagent** (`/research` is a deprecated alias). Use when knowledge outside the current working directory is required.
+- **Research** (AFK): Reading documentation, third-party APIs, or local resources to surface a fact a decision waits on. Route to `yss-research`, delegating independent reading when supported. Use when a decision needs evidence unavailable in the current inputs; local evidence and external sources follow the same source policy.
 - **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
 - **Grilling** (HITL): Conversation. The default case. Always invoke the /grilling and /domain-modeling skills.
 - **Task** (HITL or AFK): Manual work that must happen before a _decision_ can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that _does_ rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.

package/template/.agents/skills/yss-api-integration/SKILL.md

@@ -5,24 +5,22 @@ description: "在 Vue3 YSS UI 中对接 Orval API；核验生成方法、mutator
 
 # API 集成 Skill
 
-本目录是 API 集成的 canonical 技能；历史名称 `api-integration` 仅通过注册表和 实现合同编译器 alias 解析，不再维护第二份内容。
+本技能的 canonical 名称为 `yss-api-integration`。历史名称 `api-integration` 只由注册表与实现合同编译器解析，不维护第二份内容。
 
-目录、frontmatter、注册表 ID 和 实现合同编译器 canonical 闭包键均为 `yss-api-integration`；历史名称 `api-integration` 只在注册表和 实现合同编译器 alias 表中解析为本技能。
-
-## 📋 目标
+## 目标
 
 帮助 AI 正确使用基于 **Orval** 生成的 API 客户端：
 
-- ✅ 正确导入 API 函数
-- ✅ 统一错误处理与 Toast 门禁
-- ✅ Loading 状态管理
-- ✅ 长整型 ID 精度保持
-- ✅ TypeScript 类型安全
+- 正确导入 API 函数
+- 统一错误处理与 Toast 门禁
+- Loading 状态管理
+- 长整型 ID 精度保持
+- TypeScript 类型安全
 
-## 🔍 前置条件
+## 前置条件
 
 1. **契约状态已明确**：
-   - 已有生成客户端：可以直接集成。
+   - 已有生成客户端：先核验冻结契约、JSON 派生记录和真实导出，输入当前且一致时可以直接集成。
    - 新增或变更 API：必须先在 `docs/.scratch/<feature>/api/<feature>.yaml` 形成 OpenAPI Draft，经工程基线 / 架构 / Spec Delta 设计和设计审查后 Freeze。冻结的 OpenAPI YAML 是唯一权威，JSON 仅为它的受控派生物。
    - 如果接口尚未冻结、JSON 派生记录缺失或生成函数不存在，先回到 `yss-product-lifecycle` / `yss-openapi-governance`，不要手写临时路径、DTO 或响应结构。
 2. **API 已生成**：在目标前端实现仓库中，按其既有的手动代码生成命令（例如 `pnpm generate:api`）刷新 API；本 Harness 不配置、不执行该命令，也不把它加入 CI。
@@ -41,9 +39,9 @@ description: "在 Vue3 YSS UI 中对接 Orval API；核验生成方法、mutator
 ```
 
 1. 读取 `yss-openapi-governance` 产出的 OpenAPI Freeze 记录和 `docs/.scratch/<feature>/api/<feature>-json-export.md`；确认 YAML SHA-256、JSON SHA-256、Redocly CLI 版本、lockfile 引用和 JSON 校验均通过。治理 JSON 的唯一产物路径是 `docs/.scratch/<feature>/api/<feature>.json`。
-2. JSON 导出由 `yss-openapi-governance` 负责。`api-integration` 只接受该 skill 留下的派生记录；记录中的锁定 `redocly bundle` 命令是治理导出证据，不是前端集成任意重跑的入口。
+2. JSON 导出由 `yss-openapi-governance` 负责。`yss-api-integration` 只接受该 skill 留下的派生记录；记录中的锁定 `redocly bundle` 命令是治理导出证据，不是前端集成任意重跑的入口。
 3. **受控交接**：若前端实现仓库需要本地输入，批准的 Cross-repo 子合同或项目脚本只能将上述治理 JSON 原样物化为 `<frontend>/openapi/openapi.json`；物化后的 SHA-256 必须与派生记录一致。禁止从 URL、Draft YAML、后端运行时或任意本地文件临时替换输入。
-4. `api-integration` 只核对 JSON 派生记录、交接路径和 SHA-256，并把原始 JSON 交给既有前端代码生成流程；本 Harness 可只读核对目标前端的生成器配置与真实导出，但不修改该配置，不在此仓库执行生成，也不建立生成 CI 门禁。若 JSON SHA 与派生记录不一致，停止交接并回到治理流程。
+4. `yss-api-integration` 只核对 JSON 派生记录、交接路径和 SHA-256，并把原始 JSON 交给既有前端代码生成流程；本 Harness 可只读核对目标前端的生成器配置与真实导出，但不修改该配置，不在此仓库执行生成，也不建立生成 CI 门禁。若 JSON SHA 与派生记录不一致，停止交接并回到治理流程。
 5. 目标前端项目在需要时手动运行其既有生成命令、类型检查和受影响组件 / API 测试；将实际命令、结果、生成输入 SHA 和偏离写入 `YSS Skill Execution Result`。
 
 ## 真实 mutator 响应契约
@@ -81,44 +79,9 @@ pnpm generate:api
 - 不得根据文档示例假定工厂一定名为 `getApi()`；Orval `title` 配置会影响真实名称。
 - 请求/响应 DTO 必须从当前生成的 `schemas` 导入，禁止重复声明。
 
-## 标准代码骨架
-
-以微应用的真实 `getApiApi()` 产物为例：
-
-```typescript
-import { reactive, ref } from 'vue';
-import { getApiApi } from '@/api/generated/quality';
-import type { QualityBusinessRuleVO, QualityRulePage } from '@/api/generated/quality/schemas';
-
-const { pageQualityRule } = getApiApi();
-
-/** 管理质量规则列表请求和分页状态。 */
-export const useQualityRuleList = () => {
-  const loading = ref(false);
-  const dataList = ref<QualityBusinessRuleVO[]>([]);
-  const query = reactive<QualityRulePage>({ pageIndex: 1, pageSize: 20, ruleName: '' });
-  const total = ref(0);
-
-  /** 加载规则列表。 */
-  const fetchData = async (): Promise<void> => {
-    loading.value = true;
-    try {
-      const res = await pageQualityRule(query);
-      dataList.value = res.data ?? [];
-      total.value = res.totalCount ?? 0;
-    } catch {
-      dataList.value = [];
-      total.value = 0;
-    } finally {
-      loading.value = false;
-    }
-  };
-
-  return { loading, dataList, query, total, fetchData };
-};
-```
+## 按需示例
 
-> 如果所在项目已生成 `pageQualityRule` 具名导出，直接导入该函数，删除上面的工厂实例行。
+首次组织列表请求或需比较具名导出与工厂导出时，读取 [Orval 列表示例](references/orval-list-example.md)。示例中的业务名称与响应字段仅作已核验版本的用法说明，目标工程仍消费自己的冻结 DTO 和真实导出。
 
 ## 长整型与数值类型
 

package/template/.agents/skills/yss-api-integration/references/orval-list-example.md

@@ -0,0 +1,38 @@
+## 标准代码骨架
+
+以微应用的真实 `getApiApi()` 产物为例：
+
+```typescript
+import { reactive, ref } from 'vue';
+import { getApiApi } from '@/api/generated/quality';
+import type { QualityBusinessRuleVO, QualityRulePage } from '@/api/generated/quality/schemas';
+
+const { pageQualityRule } = getApiApi();
+
+/** 管理质量规则列表请求和分页状态。 */
+export const useQualityRuleList = () => {
+  const loading = ref(false);
+  const dataList = ref<QualityBusinessRuleVO[]>([]);
+  const query = reactive<QualityRulePage>({ pageIndex: 1, pageSize: 20, ruleName: '' });
+  const total = ref(0);
+
+  /** 加载规则列表。 */
+  const fetchData = async (): Promise<void> => {
+    loading.value = true;
+    try {
+      const res = await pageQualityRule(query);
+      dataList.value = res.data ?? [];
+      total.value = res.totalCount ?? 0;
+    } catch {
+      dataList.value = [];
+      total.value = 0;
+    } finally {
+      loading.value = false;
+    }
+  };
+
+  return { loading, dataList, query, total, fetchData };
+};
+```
+
+> 如果所在项目已生成 `pageQualityRule` 具名导出，直接导入该函数，删除上面的工厂实例行。