create-yss-spec 3.5.6 → 3.5.9

package/template/.codex/skills/formily-step-flow/references/step-flow-example.md

@@ -0,0 +1,143 @@
+## 标准代码骨架
+
+```vue
+<script setup lang="ts">
+import { YButton, YFormily, type ISchema } from '@yss-ui/components';
+import { Steps as ASteps } from 'ant-design-vue';
+import { computed, reactive, ref } from 'vue';
+
+/** YFormily 对外提交能力。 */
+interface YssFormilyExpose {
+  submit: () => Promise<Record<string, any>>;
+}
+
+/** 分步表单数据。 */
+interface StepFormData {
+  step1: { name: string };
+  step2: { level: string };
+}
+
+/** 分步表单提交回调 Props。 */
+interface StepFlowProps {
+  onSubmit: (values: StepFormData) => Promise<void>;
+}
+
+/** 分步表单提交回调。 */
+const props = defineProps<StepFlowProps>();
+/** 当前步骤，从 0 开始。 */
+const currentStep = ref(0);
+/** 最终提交状态。 */
+const submitting = ref(false);
+/** 第一步表单实例。 */
+const step1Ref = ref<YssFormilyExpose>();
+/** 第二步表单实例。 */
+const step2Ref = ref<YssFormilyExpose>();
+/** 步骤导航配置。 */
+const stepItems = [{ title: '基础信息' }, { title: '策略配置' }, { title: '确认提交' }];
+/** 跨步唯一数据源。 */
+const formData = reactive<StepFormData>({
+  step1: { name: '' },
+  step2: { level: 'normal' },
+});
+
+/** 创建符合业务三层布局约定的步骤 Schema。 */
+const createStepSchema = (properties: Record<string, ISchema>): ISchema => ({
+  type: 'object',
+  properties: {
+    layout: {
+      type: 'void',
+      'x-component': 'FormLayout',
+      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
+      properties: {
+        grid: {
+          type: 'void',
+          'x-component': 'FormGrid',
+          'x-component-props': { maxColumns: 2, minColumns: 1, minWidth: 320 },
+          properties,
+        },
+      },
+    },
+  },
+});
+
+/** 第一步 Schema。 */
+const step1Schema = createStepSchema({
+  name: {
+    type: 'string',
+    title: '任务名称',
+    required: true,
+    'x-validator': [{ required: true, whitespace: true, message: '请输入任务名称' }],
+    'x-decorator': 'FormItem',
+    'x-component': 'Input',
+  },
+});
+/** 第二步 Schema。 */
+const step2Schema = createStepSchema({
+  level: {
+    type: 'string',
+    title: '策略等级',
+    required: true,
+    enum: [
+      { label: '普通', value: 'normal' },
+      { label: '严格', value: 'strict' },
+    ],
+    'x-decorator': 'FormItem',
+    'x-component': 'Select',
+  },
+});
+/** 确认步骤 Schema。 */
+const confirmSchema = createStepSchema({
+  name: { type: 'string', title: '任务名称', 'x-decorator': 'FormItem', 'x-component': 'Input' },
+  level: { type: 'string', title: '策略等级', 'x-decorator': 'FormItem', 'x-component': 'Input' },
+});
+/** 确认步骤展示数据。 */
+const confirmValues = computed(() => ({ name: formData.step1.name, level: formData.step2.level }));
+
+/** 校验当前步骤，成功后前进。 */
+const next = async () => {
+  const currentRef = currentStep.value === 0 ? step1Ref.value : step2Ref.value;
+  if (!currentRef) return;
+  try {
+    await currentRef.submit();
+    currentStep.value += 1;
+  } catch {
+    return;
+  }
+};
+
+/** 返回上一步。 */
+const back = () => {
+  currentStep.value = Math.max(0, currentStep.value - 1);
+};
+
+/** 提交全部步骤数据。 */
+const submitAll = async () => {
+  submitting.value = true;
+  try {
+    await props.onSubmit({ step1: { ...formData.step1 }, step2: { ...formData.step2 } });
+  } finally {
+    submitting.value = false;
+  }
+};
+</script>
+
+<template>
+  <ASteps :current="currentStep" :items="stepItems" />
+
+  <YFormily v-if="currentStep === 0" ref="step1Ref" v-model="formData.step1" :schema="step1Schema" />
+  <YFormily v-else-if="currentStep === 1" ref="step2Ref" v-model="formData.step2" :schema="step2Schema" />
+  <YFormily
+    v-else
+    :schema="confirmSchema"
+    :initial-values="confirmValues"
+    :mode="2"
+    :detail-options="{ bordered: true, maxColumns: 2, minColumns: 1, minWidth: 320 }"
+  />
+
+  <YButton :disabled="currentStep === 0" @click="back">上一步</YButton>
+  <YButton v-if="currentStep < 2" type="primary" @click="next">下一步</YButton>
+  <YButton v-else type="primary" :loading="submitting" @click="submitAll">提交</YButton>
+</template>
+```
+
+当 schema、步骤状态和页面编排难以独立理解或验证时，分别拆到 `constant.ts`、`hooks/useStepFlow.ts`；以职责清晰和状态可测试为准，不按固定行数拆分。

package/template/.codex/skills/handoff/SKILL.md

@@ -5,7 +5,9 @@ argument-hint: "What will the next session be used for?"
 disable-model-invocation: true
 ---
 
-Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
+Write a handoff document so a fresh agent can continue the current objective. Save to the temporary directory of the user's OS, then return its actual absolute path.
+
+Record the current objective, completed work, remaining work and blockers, existing authorization scope, and the next executable action. Distinguish verified results from planned or unexecuted checks. Preserve the references and versions needed to resume; a handoff does not grant approval, implementation, commit, push or release authority.
 
 Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
 

package/template/.codex/skills/i-have-adhd/SKILL.md

@@ -10,13 +10,13 @@ license: MIT
 
 ## 触发与作用域
 
-调用者在当前工作包含研究结论、Plan、Spec、设计说明、契约解释正文、Ticket、审查、交接、发布或复盘时，设置条件 `lifecycle-document-output` 并加载本技能。进度与会签表达也属于文档输出；纯代码修改、命令执行和后续无关会话不激活此条件。
+调用者在当前工作包含研究结论、Plan、Spec、设计说明、契约解释正文、Ticket、审查、PR / MR 描述、交接、发布或复盘时，设置条件 `lifecycle-document-output` 并加载本技能。进度与会签表达也属于文档输出；纯代码修改、命令执行和后续无关会话不激活此条件。
 
 每次调用只覆盖输入指定的文档或报告。工作结束即结束本次作用域；用户后续要求正常表达或不使用本技能时遵从当前要求，不继承先前启用状态。不假设读者具有任何诊断。
 
 ## 执行
 
-1. 接收产物类型、读者、允许改动范围和可读权威输入；先读共用规范，再读取对应阶段指引。字段、版本或规则来源不明确时保留缺口并回交原所有者，不补造业务决定。
+1. 接收产物类型、读者、允许改动范围和可读权威输入；先读共用规范，再读取对应阶段或 PR / MR 描述指引。字段、版本或规则来源不明确时保留缺口并回交原所有者，不补造业务决定。
 2. 先写当前问题、结论或交付行为，再提供依据和必要细节；按顺序动作、规则比较和因果说明选择编号、表格或段落。删除无信息的修饰和重复，不设置字数或规则数量上限。
 3. 对照输入核查主体、条件、例外、量词、范围、数值、证据、未决项、责任、时点和依赖。保持原 API 标识、schema、冻结行为、状态及批准证据；发现冲突时交回所有者，不以润色名义修复事实。
 4. 返回调整后的正文及必要的缺口说明，由原工作单元执行现有验证。明确区分已验证结果、估算和未知原因；未执行测试不写通过，多项实质阻塞全部保留。已授权工作由原执行者继续，不把可完成的操作转交用户。

package/template/.codex/skills/i-have-adhd/references/yss-adaptation.md

@@ -1,8 +1,8 @@
 # i-have-adhd 的 YSS 适配
 
-上游：`ayghri/i-have-adhd`；固定 revision：`7b9069b39972e269e61bd95c2f66ebb90cac6a02`；许可证见技能目录 `LICENSE`。
+上游：`ayghri/i-have-adhd`；固定 revision：`839872f9d1cd634fed642b4589ce7226199cc15f`；许可证见技能目录 `LICENSE`。
 
-原始文件来自 [固定版本目录](https://github.com/ayghri/i-have-adhd/tree/7b9069b39972e269e61bd95c2f66ebb90cac6a02/skills/i-have-adhd)。未经改写的来源基线保存在模板维护证据中；`upstream-files.json` 记录逐文件 SHA-256，`skills-lock.json` 记录上游目录哈希和当前技能目录哈希。基线不进入实例默认加载面。
+原始文件来自 [固定版本目录](https://github.com/ayghri/i-have-adhd/tree/839872f9d1cd634fed642b4589ce7226199cc15f/skills/i-have-adhd)。2026-10-03 核验该提交与先前 `7b9069b39972e269e61bd95c2f66ebb90cac6a02` 的技能目录树和三个文件原字节一致；本轮更新来源记录并修复 YSS 消费指引。未经改写的来源基线保存在模板维护证据中；`upstream-files.json` 记录逐文件 SHA-256，`skills-lock.json` 记录上游目录哈希和当前技能目录哈希。基线不进入实例默认加载面。
 
 | 上游行为 | YSS 适配 |
 |---|---|

package/template/.codex/skills/i-have-adhd/tests/verify-integration.mjs

@@ -15,11 +15,13 @@ assert.ok(registry.invocation_contract.overrides['i-have-adhd'].exclusion_condit
 assert.ok(registry.invocation_contract.overrides['i-have-adhd'].exclusion_conditions.includes('user-disabled'));
 const entry=read('.agents/skills/i-have-adhd/SKILL.md');
 assert.ok(!entry.includes('disable-model-invocation: true'));
+assert.ok(entry.includes('PR / MR 描述'),'PR / MR description remains current document work');
 assert.equal(parse(read('.agents/skills/i-have-adhd/agents/openai.yaml')).policy.allow_implicit_invocation,true);
 const lock=JSON.parse(read('skills-lock.json'));
 const locked=lock.skills.shared['i-have-adhd'];
 assert.equal(locked.source,'ayghri/i-have-adhd');
-assert.equal(locked.sourceRevision,'7b9069b39972e269e61bd95c2f66ebb90cac6a02');
+assert.equal(locked.sourceRevision,'839872f9d1cd634fed642b4589ce7226199cc15f');
+assert.ok(read('.agents/skills/i-have-adhd/references/yss-adaptation.md').includes(locked.sourceRevision),'adaptation provenance follows the locked source revision');
 assert.notEqual(locked.upstreamHash,locked.effectiveHash);
 const {treeHash}=await import(pathToFileURL(path.join(root,'scripts/lib/skill-supply-chain.mjs')));
 assert.equal(treeHash(path.join(root,'.agents/skills/i-have-adhd')),locked.effectiveHash);
@@ -58,6 +60,9 @@ if(fs.existsSync(compiler)) {
   assert.ok(on.required_skills.includes('i-have-adhd'));
   assert.ok(!next.required_skills.includes('i-have-adhd'));
   assert.equal(on.status,'draft');
-  console.log('PASS: actual resolver excludes code-only, includes document output, does not persist condition or approve the contract.');
+  // PR / MR drafting uses the same caller-provided document condition exercised by on/next.
+  assert.deepEqual(next.required_skills,off.required_skills);
+  assert.equal(next.status,'draft');
+  console.log('PASS: actual resolver excludes code-only, includes the caller-provided document condition also used for PR / MR drafts, does not persist that condition or approve the contract. Model classification of PR / MR work is not measured.');
 } else console.log('N/A: this strategic-only template has no implementation compiler; conditional route verified in registry and orchestration contract.');
 console.log(`PASS: source, license metadata, ${locked.targets.length} projections, ${callers.length} callers, scope and readable writing inputs. Model output quality not measured.`);

package/template/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/skills/product-design/references/communication-protocol.md

@@ -11,7 +11,7 @@ Default response shape:
 - Explain what changed in plain product or design language.
 - Give the clickable preview URL when there is one.
 - Name trade-offs or misses plainly.
-- End with one concise suggested next step for the user's current task or goal.
+- State the next actions needed for the user's current goal, keeping all material blockers and required decisions visible.
 - Avoid walls of bullets and overwhelming the user.
 - Prioritize pithy, explicit prose that is helpful and minimizes jargon.
 
@@ -32,9 +32,9 @@ Use technical detail only when:
 
 Final response continuation:
 
-- Every final response should end with exactly one useful next action, phrased as a natural sentence or question in the ordinary prose of the response.
+- When concrete work remains, end with the useful next actions or required decisions, phrased naturally in the ordinary prose of the response. Do not invent a follow-up after the requested work is complete.
 - Make the next step specific to the active Product Design goal, such as reviewing a preview, choosing a direction, approving an implementation pass, tightening one screen, or sharing a target route or reference.
-- If the response is blocked on missing input, make the unresolved question the final next step.
+- If the response is blocked on missing input, explain each material gap and the decision or source needed to resolve it; do not hide independent questions to fit a fixed count.
 - Do not end with only a bare confirmation, file path, preview link, or "done" message while a concrete Product Design next step remains.
 - Skip the next step only when the user explicitly asks for no follow-up, clearly closes the task, or another active workflow already owns the final next action.