create-yss-spec 3.5.6 → 3.5.8

package/template/.agents/skills/formily-mode-slot-detail/SKILL.md

@@ -3,7 +3,7 @@ name: formily-mode-slot-detail
 description: 指导 YFormily 新增、编辑、查看三态与插槽渲染；当配置 mode 0/1/2、查看态只读、详情页 Descriptions 展示、detail-options、Schema Slot 或详情字段插槽时使用。
 ---
 
-# Formily Mode Slot Detail Skill
+# YFormily 三态与插槽
 
 ## 触发条件
 
@@ -35,87 +35,9 @@ description: 指导 YFormily 新增、编辑、查看三态与插槽渲染；当
 - 加载详情的 Orval API 错误已由 `mutator.ts` 统一 `message.error` 并 reject，业务 `else`/`catch` 禁止重复提示。
 - 分步需求默认走 `formily-step-flow`，不在本 skill 中给 `FormStep` 默认方案。
 
-## 标准代码骨架
+## 按需示例
 
-```vue
-<script setup lang="ts">
-import { YMonaco, YFormily, type ISchema } from '@yss-ui/components';
-import { ref } from 'vue';
-
-/** YFormily 业务模式。 */
-type FormMode = 0 | 1 | 2;
-
-/** 当前表单模式。 */
-const mode = ref<FormMode>(0);
-
-/** 编辑和查看回填值。 */
-const initialValues = {
-  user: { email: 'user@example.com' },
-  sql: 'select * from users',
-};
-
-/** 编辑与详情共用的 Schema。 */
-const schema: 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: {
-            user: {
-              type: 'object',
-              properties: {
-                email: {
-                  type: 'string',
-                  title: '邮箱',
-                  'x-decorator': 'FormItem',
-                  'x-component': 'Input',
-                },
-              },
-            },
-            sql: {
-              type: 'string',
-              title: 'SQL',
-              'x-decorator': 'FormItem',
-              'x-decorator-props': { gridSpan: 2 },
-              'x-component': 'Slot',
-              'x-component-props': { name: 'sql' },
-            },
-          },
-        },
-      },
-    },
-  },
-};
-</script>
-
-<template>
-  <YFormily
-    :schema="schema"
-    :initial-values="initialValues"
-    :mode="mode"
-    :detail-options="{ bordered: true, maxColumns: 3, minColumns: 1, minWidth: 260 }"
-  >
-    <template #sql="{ value, onChange }">
-      <YMonaco :model-value="value" language="sql" @change="onChange" />
-    </template>
-
-    <template #detail-user-email="{ value }">
-      <a :href="`mailto:${value}`">{{ value }}</a>
-    </template>
-
-    <template #detail-sql="{ value }">
-      <YMonaco :model-value="value" language="sql" readonly />
-    </template>
-  </YFormily>
-</template>
-```
+首次组合三态、编辑 Slot 与详情插槽，或排查字段路径时，读取 [三态与双通道插槽示例](references/mode-slot-example.md)。示例不替代目标工程的导出与版本核验。
 
 ## 交付检查清单
 

package/template/.agents/skills/formily-mode-slot-detail/references/mode-slot-example.md

@@ -0,0 +1,81 @@
+## 标准代码骨架
+
+```vue
+<script setup lang="ts">
+import { YMonaco, YFormily, type ISchema } from '@yss-ui/components';
+import { ref } from 'vue';
+
+/** YFormily 业务模式。 */
+type FormMode = 0 | 1 | 2;
+
+/** 当前表单模式。 */
+const mode = ref<FormMode>(0);
+
+/** 编辑和查看回填值。 */
+const initialValues = {
+  user: { email: 'user@example.com' },
+  sql: 'select * from users',
+};
+
+/** 编辑与详情共用的 Schema。 */
+const schema: 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: {
+            user: {
+              type: 'object',
+              properties: {
+                email: {
+                  type: 'string',
+                  title: '邮箱',
+                  'x-decorator': 'FormItem',
+                  'x-component': 'Input',
+                },
+              },
+            },
+            sql: {
+              type: 'string',
+              title: 'SQL',
+              'x-decorator': 'FormItem',
+              'x-decorator-props': { gridSpan: 2 },
+              'x-component': 'Slot',
+              'x-component-props': { name: 'sql' },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+</script>
+
+<template>
+  <YFormily
+    :schema="schema"
+    :initial-values="initialValues"
+    :mode="mode"
+    :detail-options="{ bordered: true, maxColumns: 3, minColumns: 1, minWidth: 260 }"
+  >
+    <template #sql="{ value, onChange }">
+      <YMonaco :model-value="value" language="sql" @change="onChange" />
+    </template>
+
+    <template #detail-user-email="{ value }">
+      <a :href="`mailto:${value}`">{{ value }}</a>
+    </template>
+
+    <template #detail-sql="{ value }">
+      <YMonaco :model-value="value" language="sql" readonly />
+    </template>
+  </YFormily>
+</template>
+```

package/template/.agents/skills/formily-step-flow/SKILL.md

@@ -3,7 +3,7 @@ name: formily-step-flow
 description: 指导 YSS UI 分步表单与流程录入；当需要 Ant Design Vue Steps、多 YFormily 独立校验、跨步数据保留、确认预览或最终聚合提交时使用。
 ---
 
-# Formily Step Flow Skill
+# YFormily 分步流程
 
 ## 触发条件
 
@@ -32,149 +32,9 @@ description: 指导 YSS UI 分步表单与流程录入；当需要 Ant Design Vu
 - 最终 API 提交只聚合业务步骤，禁止把纯确认步骤当作新数据源。
 - Orval API 的网络错误及 `success === false` 业务错误已由 `mutator.ts` 统一 `message.error` 并 reject；最终提交的 `else`/`catch` 禁止重复提示，loading 放在 `finally` 恢复。
 
-## 标准代码骨架
+## 按需示例
 
-```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`；以职责清晰和状态可测试为准，不按固定行数拆分。
+首次组织分步实例、聚合数据和确认页，或排查步骤回填时，读取 [分步表单组合示例](references/step-flow-example.md)。按业务阶段拆 schema、Hook 与私有视图，不按固定行数拆分。
 
 ## 交付检查清单
 

package/template/.agents/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/.agents/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/.agents/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/.agents/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/.agents/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/.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,