create-yss-spec 3.5.3 → 3.5.4

package/template/.agents/skills/yss-design-system/references/prototype-default-theme.md

@@ -0,0 +1,26 @@
+# 高保真原型默认主题
+
+用于新高保真 H1/H2 页面，shadcn-vue + Vue 3 与原生轻量路线共用。颜色、字体、尺寸仍以当前项目根 DESIGN.md 为准；主题只选择已定义的角色和组件变体。既有批准原型不自动迁移，局部修改先登记保持项。
+
+## 密度与视觉角色
+
+新页面默认 `compact`：控件采用 `components.button-compact.height`，容器采用 `components.card-compact.padding`；窄屏恢复普通控件高度并让筛选、动作与摘要列表换行。`comfortable` 保留根规范普通控件与 Card 变体。密度不压缩正文、焦点或错误说明，不把生产 compact algorithm 的排版结果直接套给原型，也不再次运行算法。
+
+正文使用 `typography.body`，页面标题和分区标题分别使用 `heading-lg`、`heading-md`，辅助信息才用 `caption`。页面、内容、浮层分别使用对应表面角色；主操作使用 button-primary 系列，不能回退到品牌 seed。筛选、列表、表单和审批优先用边界与分组表达层次。
+
+`variables.css` 中 `--yss-colors-*`、`--yss-typography-*`、`--yss-components-*` 是规范角色投影；既有 `--brand-*` 保留运行时桥接。别名由 design-md 工具生成，不手工维护第二套值。只补视觉角色时可执行 `scripts/design-md export dtcg --write-css --write-manifest`，改动源值或生产算法时仍执行完整派生。新主题的计算样式须与当前根规范比对，历史缺少角色别名的快照不作为当前规范一致性的证据。
+
+## 默认页面结构
+
+新企业页面套用根规范 workspace 应用壳：模块、分组侧栏、页签和流式任务区。标题使用 workspace-title；既有页面保持项不被新框架覆盖。多页状态见原型技能 `references/enterprise-workspace.md`，不把页签缓存视为持久保存。
+
+- 查询：条件与筛选动作对齐；列表标题、排序/选择状态位于紧凑工具栏，分页在结果后。窄屏转为带身份、名称、状态和操作的摘要列表。
+- 表单：按任务分组，控制阅读宽度；错误靠近字段且可定位，返回保留输入，确认动作保持可见。
+- 审批：身份、状态、责任人与操作沿行组织；不可操作原因保留可读文本，失败项保持可重试。
+- 分析：指标主次与明细共用筛选；横向滚动限定在数据区域，提供提示、固定关键列与键盘访问。
+
+## 交互与检查
+
+统一 hover、active、focus-visible、disabled、selected、invalid；反馈采用语义表面和文字。动效只用于反馈且使用项目动效 Token，减少动效时取消。完整行为仍消费交互说明与状态矩阵，不由主题定义。
+
+六轴 QA 中检查当前计算样式、文字对比度、选中/错误状态、桌面和窄屏、键盘与焦点返回、200% 缩放、减少动效及 console。密度变小不能作为质量提升的证据；同时检查每屏信息量、主操作可发现性与恢复任务可完成性。前后对照必须采用相同内容、状态和视口，视觉收益需由用户确认。

package/template/.agents/skills/yss-design-system/references/search-date-theme.md

@@ -0,0 +1,19 @@
+# 搜索选择、日期范围与重排
+
+本配方消费根 DESIGN 与现有 Token，不新增颜色或生命周期门禁。原型语义和规则由 `yss-prototype-stage/references/search-date-patterns.md` 持有。
+
+| 表面 | 当前角色与检查 |
+|---|---|
+| 搜索输入/列表 | 使用当前密度控件、输入边框、主次文字、浮层表面；长中文允许换行，编号保持可辨；选中反馈与搜索文字分开 |
+| 错误/加载/禁用 | 复用错误文字、持续反馈和禁用角色；解释原因，不仅变色或降低透明度 |
+| 日期范围 | 端点用高对比主操作颜色，区间用浅主色与正文；同日仍可辨，键盘焦点独立于选中状态 |
+| 日历/浮层 | 七列均分且点击区域实测；内容限制在视口与可用高度，内部可滚动；应用/取消可达，定位错误不被覆盖 |
+| 窄屏 | 控件与筛选堆叠；日期输入单列；长标签、分页、主操作可重排；仅必要二维表格允许自身横向滚动 |
+
+compact/comfortable 分别核对实际计算样式；控件高度不等于点击区域，检查至少 24 CSS px 的实际目标或满足标准的间距例外，并记录依据。增加像素值前先确认是否已有 Token；确需稳定新角色时先登记根 `DESIGN.md`，再用既有工具生成派生值，禁止手改投影。
+
+320 CSS px 等效重排与实际 200% 浏览器缩放分别留证。重排检查筛选、分页、日期浮层、主操作和错误定位；二维数据表例外不能扩展至外围控件。按 [W3C Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) 记录不适用依据；像素截图或自动扫描不自动证明 WCAG 符合性。
+
+焦点关闭时先检查原触发器仍存在且可见；触发器被隐藏/移除时转向当前页面主区域或明确后继，不能回到隐藏 KeepAlive 页面。键盘检查焦点环、自动滚动、固定栏遮挡、操作结果；减少动效独立核验。
+
+目标人群使用读屏，或动态错误、复合输入、范围选择、焦点恢复有高风险时，追加人工读屏：记录 OS、浏览器、辅助技术及版本；依次听取名称/角色/值、同名 ID、加载/失败、选中反馈、日期端点、应用/取消和离页后焦点。环境缺失写“未执行”及受影响结论；不能把自动扫描写成读屏通过。边界参考 [Playwright accessibility testing](https://playwright.dev/docs/accessibility-testing)。

package/template/.agents/skills/yss-design-system/scripts/export-craft-examples.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { existsSync, realpathSync } from 'node:fs';
+import { readFile, writeFile, mkdir, readdir, lstat, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+const digest = value => `sha256:${createHash('sha256').update(value).digest('hex')}`;
+export async function exportCraftExamples({ projectRoot, output }) {
+  const root = await realpath(projectRoot);
+  const target = path.resolve(output);
+  try { if ((await lstat(target)).isSymbolicLink()) throw new Error('示例输出不允许符号链接'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  try { if ((await readdir(target)).length) throw new Error('示例目录非空，拒绝覆盖'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const tokenRef = '.template-spec/design/tokens/variables.css';
+  const tokens = await readFile(path.join(root, tokenRef)); const design = await readFile(path.join(root, 'DESIGN.md'));
+  await mkdir(target, { recursive: true });
+  for (const file of ['index.html','styles.css','app.js','scenarios.js']) {
+    const text = await readFile(new URL(`../assets/enterprise-craft/${file}`, import.meta.url), 'utf8');
+    await writeFile(path.join(target,file), text.replace('../../../../../.template-spec/design/tokens/variables.css','tokens.css'));
+  }
+  await writeFile(path.join(target,'tokens.css'), tokens);
+  const files = {};
+  for (const file of (await readdir(target)).sort()) files[file] = digest(await readFile(path.join(target,file)));
+  await writeFile(path.join(target,'example-provenance.json'), JSON.stringify({ purpose:'teaching-only', design_source:{ref:'DESIGN.md',digest:digest(design)}, token_source:{ref:tokenRef,digest:digest(tokens)}, files },null,2)+'\n');
+  return { root:target, entry:path.join(target,'index.html') };
+}
+if (process.argv[1] && existsSync(process.argv[1]) && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  try { const { values } = parseArgs({ options: {'project-root':{type:'string'},output:{type:'string'}} }); console.log(JSON.stringify(await exportCraftExamples({projectRoot:values['project-root'],output:values.output}))); }
+  catch (error) { console.error(error.message); process.exitCode=1; }
+}

package/template/.agents/skills/yss-hook/SKILL.md

@@ -38,113 +38,19 @@ description: Use when YSS Vue 页面涉及 vue-hooks-plus/useRequest、分页、
 
 ## 2. 列表 / 分页 Hook
 
-下面示例仅说明**已批准**的 `useRequest` 具有 `manual`、`run`、`onSuccess`、`onError` 时的组织方式；`vue-hooks-plus` 的专属契约见第 3 节，其他请求库以实际 API 为准。
-
-```ts
-export function useReportTable() {
-  const tableData = ref<any[]>([]);
-  const currentParams = ref({ pageIndex: 1, pageSize: 20 });
-  const pagination = reactive({
-    current: 1, pageSize: 20, total: 0,
-    showSizeChanger: true, showQuickJumper: true,
-  });
-
-  const { loading, run: fetchList } = useRequest(apiFn, {
-    manual: true,
-    onSuccess: (res) => {
-      tableData.value = res?.data || [];
-      pagination.total = res?.totalCount || 0;
-    },
-    onError: () => {
-      tableData.value = [];
-      pagination.total = 0;
-    },
-  });
-  const query = (params: Record<string, any>) => {
-    currentParams.value = { ...currentParams.value, ...params };
-    return fetchList(currentParams.value);
-  };
-  // YTable emits one object; adapt it at this boundary.
-  const handlePageChange = ({ current, pageSize }: { current: number; pageSize: number }) => {
-    pagination.current = current;
-    pagination.pageSize = pageSize;
-    return query({ pageIndex: current, pageSize });
-  };
-  return { loading, tableData, currentParams, pagination, query, handlePageChange };
-}
-```
-
-- 仅当项目已批准的请求库支持时使用 `useRequest`；通常使用 `manual: true`，除非需求明确要求挂载即请求。
-- `currentParams` 是唯一参数源。筛选变化重置 `pageIndex: 1`；翻页只改 `pageIndex/pageSize`；刷新、导出和编辑后重载复用它。
-- 在 Hook 内处理成功、失败、空数据和响应映射；旧列表会误导时才在失败时清空。
-- 树数据同样由 Hook 暴露 `treeData`、`treeLoading`、`selectedKey`、`handleSelect`，并在其中处理会触发加载的选中副作用。
+实现列表、筛选、树数据或分页时，读取 [列表与分页模式](references/list-pagination.md)。`currentParams` 保持唯一参数源；筛选回到第一页，刷新、导出和重载复用它。
 
 ## 3. `vue-hooks-plus/useRequest`（项目已批准时）
 
 仅项目已批准且当前任务使用该库时，读取 [useRequest 实现细则](references/use-request.md)，覆盖返回值、错误处理、取消、缓存、刷新、重试和轮询。不得因技能示例引入未批准依赖；调用 `runAsync` 必须捕获拒绝，业务失败提示遵循 mutator 的唯一所有权。
 
-## 4. 单一异步动作：`useLoading`
-
-`useLoading(initialValue?)` 返回 `loading`、`setLoading`、`toggleLoading` 与 `withLoading`。用 `withLoading` 包装提交、删除、导出等动作，并把刷新或状态修正写在回调中。
-
-```ts
-const { loading: removeLoading, withLoading } = useLoading();
-
-async function remove(id: string) {
-  // `withLoading` 不等同于去重锁；快速重复点击须显式短路。
-  if (removeLoading.value) return;
-  await withLoading(() => deleteReport(id), {
-    onSuccess: async () => { await query(currentParams.value); },
-    onError: (error) => { actionError.value = error; },
-  });
-}
-```
-
-- 确认弹窗属于页面 / 组件交互层；Hook 接收“已确认”的业务意图并负责执行、loading、结果更新和最小动作面。
-- `withLoading` 默认捕获异常并返回 `undefined`；调用方确实需要捕获时才设置 `rethrowError: true`。可用 `onSuccess`、`onError`、`onFinally` 或 `keepLoadingOnError` 定义行为。
-- 不要让一个全局 `loading` 掩盖多个互不相关动作；为删除、保存、导出等分别暴露必要状态。
-
-## 5. 搜索竞态、取消与并行详情
-
-`@yss-ui/hooks` 没有通用防抖、取消、缓存或重试 Hook。项目已批准 Vue Hooks Plus 时，优先遵循第 3 节；否则先确认项目请求库是否已提供这些能力，再在业务 Hook 中以最小实现处理：
-
-- 搜索建议：维护 timer、递增请求序号和（仅当客户端支持时）`AbortController`；新输入先清除旧 timer、递增序号并取消旧请求；响应写入前比较序号；在 `onScopeDispose` 清理 timer 并中止请求。不要把这些逻辑放在页面组件。
-- 并行详情：每个独立区域返回自己的 `{ data, loading, error, refresh }`，`refreshAll` 可以用 `Promise.allSettled` 聚合；某一区域失败不得清空或阻塞其他区域，也必须可单独刷新。
-- 提交类动作应回滚局部乐观状态；查询类动作只在旧数据会误导时清空。
-
-```ts
-function createDetailPanel<T>(load: () => Promise<T>) {
-  const data = ref<T>();
-  const error = ref<unknown>();
-  const { loading, withLoading } = useLoading();
-  const refresh = () => withLoading(load, {
-    onSuccess: (result) => { data.value = result; error.value = undefined; },
-    onError: (cause) => { error.value = cause; },
-  });
-  return { data, error, loading, refresh };
-}
-
-const refreshAll = () => Promise.allSettled([
-  profile.refresh(), permissions.refresh(), audit.refresh(),
-]);
-```
-
-## 6. 轮询：`usePollingTask`
-
-`usePollingTask` 是通用调度器，不管理业务数据、loading 或错误状态，也不能替代请求 Hook。它在本轮任务结束后用 `setTimeout` 安排下一轮，避免 `setInterval` 造成重叠堆积。若同一数据源已采用第 3.2 节的 `useRequest` 请求轮询，不得再使用本 Hook。
-
-```ts
-const polling = usePollingTask(async ({ isCurrent, signal }) => {
-  const result = await fetchStatus({ signal }); // 仅在客户端支持 signal 时传入
-  if (!isCurrent()) return;
-  status.value = result;
-}, { interval: 5_000, autoStart: true, pauseWhenHidden: true });
-```
-
-- `start`、`stop`、`restart` 会推进 generation；异步结果写入前必须调用 `isCurrent()`。`signal` 只有请求库真正支持时才能中止网络请求。
-- `stop()` 停止但保留 interval；`setInterval(0)` 停止并把当前 interval 置零。`runNow()` 可立即执行，`restart({ immediate: false })` 可避免手动刷新后紧接着重复请求。
-- 手动搜索 / 刷新时：先 `stop()`，走带 loading 的手动请求，再按需要 `restart()`；不可让轮询与手动请求同时竞争同一状态。
-- 默认页面隐藏时暂停后续调度；正在执行的任务不会自动取消。`continueOnError`、`resumeMode` 和 `concurrent` 必须按接口语义显式选择。
+## 4. 异步动作与竞态
+
+实现提交/删除/导出、搜索竞态或并行详情时，读取 [异步动作与竞态](references/async-actions.md)。确认属于交互层；Hook 只执行已确认意图，各独立区域保留自己的状态。
+
+## 6. 轮询
+
+实现后台刷新或多接口轮询时，读取 [轮询调度](references/polling.md)。同一数据源只有一个调度器；写入前检查 `isCurrent()`，并协调手动请求。
 
 ## 7. URL、全屏与高度类 Hooks
 

package/template/.agents/skills/yss-hook/references/async-actions.md

@@ -0,0 +1,49 @@
+# 异步动作与竞态
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。示例代码属于目标工程，模块相对导入按所示文件位置解析。
+
+## 4. 单一异步动作：`useLoading`
+
+`useLoading(initialValue?)` 返回 `loading`、`setLoading`、`toggleLoading` 与 `withLoading`。用 `withLoading` 包装提交、删除、导出等动作，并把刷新或状态修正写在回调中。
+
+```ts
+const { loading: removeLoading, withLoading } = useLoading();
+
+async function remove(id: string) {
+  // `withLoading` 不等同于去重锁；快速重复点击须显式短路。
+  if (removeLoading.value) return;
+  await withLoading(() => deleteReport(id), {
+    onSuccess: async () => { await query(currentParams.value); },
+    onError: (error) => { actionError.value = error; },
+  });
+}
+```
+
+- 确认弹窗属于页面 / 组件交互层；Hook 接收“已确认”的业务意图并负责执行、loading、结果更新和最小动作面。
+- `withLoading` 默认捕获异常并返回 `undefined`；调用方确实需要捕获时才设置 `rethrowError: true`。可用 `onSuccess`、`onError`、`onFinally` 或 `keepLoadingOnError` 定义行为。
+- 不要让一个全局 `loading` 掩盖多个互不相关动作；为删除、保存、导出等分别暴露必要状态。
+
+## 5. 搜索竞态、取消与并行详情
+
+`@yss-ui/hooks` 没有通用防抖、取消、缓存或重试 Hook。项目已批准 Vue Hooks Plus 时，优先遵循[useRequest 实现细则](use-request.md)；否则先确认项目请求库是否已提供这些能力，再在业务 Hook 中以最小实现处理：
+
+- 搜索建议：维护 timer、递增请求序号和（仅当客户端支持时）`AbortController`；新输入先清除旧 timer、递增序号并取消旧请求；响应写入前比较序号；在 `onScopeDispose` 清理 timer 并中止请求。不要把这些逻辑放在页面组件。
+- 并行详情：每个独立区域返回自己的 `{ data, loading, error, refresh }`，`refreshAll` 可以用 `Promise.allSettled` 聚合；某一区域失败不得清空或阻塞其他区域，也必须可单独刷新。
+- 提交类动作应回滚局部乐观状态；查询类动作只在旧数据会误导时清空。
+
+```ts
+function createDetailPanel<T>(load: () => Promise<T>) {
+  const data = ref<T>();
+  const error = ref<unknown>();
+  const { loading, withLoading } = useLoading();
+  const refresh = () => withLoading(load, {
+    onSuccess: (result) => { data.value = result; error.value = undefined; },
+    onError: (cause) => { error.value = cause; },
+  });
+  return { data, error, loading, refresh };
+}
+
+const refreshAll = () => Promise.allSettled([
+  profile.refresh(), permissions.refresh(), audit.refresh(),
+]);
+```

package/template/.agents/skills/yss-hook/references/list-pagination.md

@@ -0,0 +1,46 @@
+# 列表与分页 Hook
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。示例代码属于目标工程，模块相对导入按所示文件位置解析。
+
+## 2. 列表 / 分页 Hook
+
+下面示例仅说明**已批准**的 `useRequest` 具有 `manual`、`run`、`onSuccess`、`onError` 时的组织方式；`vue-hooks-plus` 的专属契约见[useRequest 实现细则](use-request.md)，其他请求库以实际 API 为准。
+
+```ts
+export function useReportTable() {
+  const tableData = ref<any[]>([]);
+  const currentParams = ref({ pageIndex: 1, pageSize: 20 });
+  const pagination = reactive({
+    current: 1, pageSize: 20, total: 0,
+    showSizeChanger: true, showQuickJumper: true,
+  });
+
+  const { loading, run: fetchList } = useRequest(apiFn, {
+    manual: true,
+    onSuccess: (res) => {
+      tableData.value = res?.data || [];
+      pagination.total = res?.totalCount || 0;
+    },
+    onError: () => {
+      tableData.value = [];
+      pagination.total = 0;
+    },
+  });
+  const query = (params: Record<string, any>) => {
+    currentParams.value = { ...currentParams.value, ...params };
+    return fetchList(currentParams.value);
+  };
+  // YTable emits one object; adapt it at this boundary.
+  const handlePageChange = ({ current, pageSize }: { current: number; pageSize: number }) => {
+    pagination.current = current;
+    pagination.pageSize = pageSize;
+    return query({ pageIndex: current, pageSize });
+  };
+  return { loading, tableData, currentParams, pagination, query, handlePageChange };
+}
+```
+
+- 仅当项目已批准的请求库支持时使用 `useRequest`；通常使用 `manual: true`，除非需求明确要求挂载即请求。
+- `currentParams` 是唯一参数源。筛选变化重置 `pageIndex: 1`；翻页只改 `pageIndex/pageSize`；刷新、导出和编辑后重载复用它。
+- 在 Hook 内处理成功、失败、空数据和响应映射；旧列表会误导时才在失败时清空。
+- 树数据同样由 Hook 暴露 `treeData`、`treeLoading`、`selectedKey`、`handleSelect`，并在其中处理会触发加载的选中副作用。

package/template/.agents/skills/yss-hook/references/polling.md

@@ -0,0 +1,20 @@
+# 轮询调度
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。示例代码属于目标工程，模块相对导入按所示文件位置解析。
+
+## 6. 轮询：`usePollingTask`
+
+`usePollingTask` 是通用调度器，不管理业务数据、loading 或错误状态，也不能替代请求 Hook。它在本轮任务结束后用 `setTimeout` 安排下一轮，避免 `setInterval` 造成重叠堆积。若同一数据源已采用[useRequest 实现细则](use-request.md) 的请求轮询，不得再使用本 Hook。
+
+```ts
+const polling = usePollingTask(async ({ isCurrent, signal }) => {
+  const result = await fetchStatus({ signal }); // 仅在客户端支持 signal 时传入
+  if (!isCurrent()) return;
+  status.value = result;
+}, { interval: 5_000, autoStart: true, pauseWhenHidden: true });
+```
+
+- `start`、`stop`、`restart` 会推进 generation；异步结果写入前必须调用 `isCurrent()`。`signal` 只有请求库真正支持时才能中止网络请求。
+- `stop()` 停止但保留 interval；`setInterval(0)` 停止并把当前 interval 置零。`runNow()` 可立即执行，`restart({ immediate: false })` 可避免手动刷新后紧接着重复请求。
+- 手动搜索 / 刷新时：先 `stop()`，走带 loading 的手动请求，再按需要 `restart()`；不可让轮询与手动请求同时竞争同一状态。
+- 默认页面隐藏时暂停后续调度；正在执行的任务不会自动取消。`continueOnError`、`resumeMode` 和 `concurrent` 必须按接口语义显式选择。

package/template/.agents/skills/yss-implementation-contract-compiler/SKILL.md

@@ -51,9 +51,8 @@ Slice v3 的当前执行结果须按 `references/yss-skill-execution-result.md`
 - Harness 内实现路径必须落在 `apps/backend/<project>/` 或 `apps/frontend/<project>/` 的具体项目目录；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径一律阻断。外部实现仓库使用其登记的真实项目根路径。`git-submodule` 使用 `implementation_path_policy: git-submodule-harness-apps`，空 gitlink、detached HEAD 或 `--force` 覆盖挂载点不得脚手架；`inspectWorkingTreeScope.writable` 必须为显式布尔值。
 - 当前用户、缓存、审计、Excel、分布式 ID、请求校验、错误映射、加解密或网关韧性命中时，必须按 `compiler-contract.yaml` 的 `impact_to_capabilities` 补齐入口 capability；不能只在 `boundaries.md` 中提及。仅复用已经验证的平台认证 / 授权能力不算 component impact，不自动增加权限专项 skill。
 - 业务行为使用 `behavior-tdd`；只有机械脚手架/生成物可用 `controlled-generation`，并记录例外和验证。
-- 阶段 5 若命中交付面且无已有工程，按 Project Scaffold Contract schema v4 编译 `controlled-generation` 合同 draft。后端先读取已通过 `gate.backend-architecture-platform-approved` 的架构与精确 Spring Boot 版本决定，并以原始字节 digest 绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision（新建 v2；历史 v1 只读兼容，准备与迁移见 `.template-spec/process/contract-reading.md`） 及 `gate.engineering-contract-approved` 真实批准记录；编译器不得自行默认、提问或批准。既有工程核验并复用当前登记架构及固定工程基线/POM 中的实际版本，不重新询问或生成。API `required` 时工程批准还必须直接绑定冻结 OpenAPI YAML 的版本与摘要，`not-applicable` 时必须有影响评估、明确原因和证据。前端绑定标准模板精确 commit、应用标识、路由、OpenAPI 影响、目标路径和 `init_git` 决定。合同经生命周期批准并持久化后才能运行生成器。历史后端 schema v3 只允许 Manifest 只读恢复审计，并须补齐 API 对账，不得新生成；前端只接受 v4。生成与验证完成、仓库登记并通过 `check.implementation-repositories-ready` 后，才编译 Ticket 与业务 Slice Contract。
-- 脚手架合同在编译阶段只能是 `draft` / `ready-for-lifecycle-review` / `blocked`；只有生命周期编排器可以把已持久化脚手架合同标记为 `approved`。脚手架合同只覆盖业务代码前的工程骨架工作单元；生成、基线校验和合同重编译完成后，它不能替代脚手架后的 Slice Implementation Contract。
-- 脚手架输出消费批准的脚手架合同；脚手架后的所有生成后端代码都必须绑定当前批准且版本当前的 Slice Implementation Contract、主 YSS skill、依赖闭包、允许写路径、预期证据和 YSS Skill Execution Result。打印命令、`./mvnw validate` 单项通过或脚手架成功不能替代合同批准；生成范围从机械内容变成业务行为时触发完整重路由。
+- 无工程且需要机械生成时，先读取 [脚手架合同编译](references/scaffold-compilation.md)。只起草 Project Scaffold Contract schema v4，由生命周期批准并持久化后运行；既有工程不重新生成。脚手架合同不能替代后续批准的 Slice Contract，业务行为必须重路由。
+
 - 专项结果中的越界路径、缺失证据、`drift`、`violation` 或 `new_impacts` 必须阻断或重路由。
 - 前后端子任务必须使用同一 `contract_id/contract_version`，并在任务包中记录 `role_id`、`runtime_id`、`execution_state`、`allowed_write_paths`、`downstream_consumers` 和 `convergence_ref`；版本不一致或汇合引用缺失时输出 `blocked`。
 - 长尾 skill 不可用时显式 `blocked`，不得用通用知识假装已应用 YSS 规范。
@@ -77,3 +76,7 @@ Slice v3 的当前执行结果须按 `references/yss-skill-execution-result.md`
 消费生命周期已确认的架构与 `platform_configuration` v2；不得自行选择、批准或静默升级 Boot/Java。平台清单执行 `scripts/backend-platforms` 查询；只允许已验证 YSS 组合，新生成缺少配置或证据即阻断。决定、合同、Manifest 与下游架构身份须绑定同一平台及兼容摘要。详见 仓库共享合同 `.template-spec/engineering/backend-platforms.md`。
 
 后端 Slice 解析出 `component_binding: required` 的 capability 或其主 Skill 时，必须在同一平台兼容条目中逐项解析 `component_capabilities`。编译结果保存 `component_bindings` 与 `component_bindings_digest`；未登记、未验证、架构证据缺失、构件坐标冲突或摘要漂移均阻断。旧合同含组件 Skill 但没有组件绑定时直接 `stale`，重新编译并交生命周期批准，禁止自动补字段后沿用原批准。
+
+## 业务来源
+
+按 `.template-spec/process/business-tickets.md` 执行 Spec 业务草案、Design 校准与业务正式化。业务票放在 `business-tickets/`，集合引用进入 Spec / map / checkpoint；业务票不授予实现资格。实现票仍在 `issues/`，受工程准备、当前 Slice 合同批准和完整就绪检查约束。 新规则项目必须验证 business_ticket_refs 与 acceptance_refs，使用现有 basis.business_ticket_set 绑定当前集合原字节；原始验收仍从 basis.spec 定位，不升级 Slice 主 schema。业务票及阶段工作项不能充当实现票。来源过期返回战略/技术分析，不由编译器重写批准。

package/template/.agents/skills/yss-implementation-contract-compiler/references/scaffold-compilation.md

@@ -0,0 +1,7 @@
+# 脚手架合同编译
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
+
+- 阶段 5 若命中交付面且无已有工程，按 Project Scaffold Contract schema v4 编译 `controlled-generation` 合同 draft。后端先读取已通过 `gate.backend-architecture-platform-approved` 的架构与精确 Spring Boot 版本决定，并以原始字节 digest 绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision（新建 v2；历史 v1 只读兼容，准备与迁移见 `.template-spec/process/contract-reading.md`） 及 `gate.engineering-contract-approved` 真实批准记录；编译器不得自行默认、提问或批准。既有工程核验并复用当前登记架构及固定工程基线/POM 中的实际版本，不重新询问或生成。API `required` 时工程批准还必须直接绑定冻结 OpenAPI YAML 的版本与摘要，`not-applicable` 时必须有影响评估、明确原因和证据。前端绑定标准模板精确 commit、应用标识、路由、OpenAPI 影响、目标路径和 `init_git` 决定。合同经生命周期批准并持久化后才能运行生成器。历史后端 schema v3 只允许 Manifest 只读恢复审计，并须补齐 API 对账，不得新生成；前端只接受 v4。生成与验证完成、仓库登记并通过 `check.implementation-repositories-ready` 后，才编译 Ticket 与业务 Slice Contract。
+- 脚手架合同在编译阶段只能是 `draft` / `ready-for-lifecycle-review` / `blocked`；只有生命周期编排器可以把已持久化脚手架合同标记为 `approved`。脚手架合同只覆盖业务代码前的工程骨架工作单元；生成、基线校验和合同重编译完成后，它不能替代脚手架后的 Slice Implementation Contract。
+- 脚手架输出消费批准的脚手架合同；脚手架后的所有生成后端代码都必须绑定当前批准且版本当前的 Slice Implementation Contract、主 YSS skill、依赖闭包、允许写路径、预期证据和 YSS Skill Execution Result。打印命令、`./mvnw validate` 单项通过或脚手架成功不能替代合同批准；生成范围从机械内容变成业务行为时触发完整重路由。

package/template/.agents/skills/yss-openapi-draft-review/SKILL.md

@@ -20,16 +20,7 @@ Use this skill after OpenAPI Draft creation and before Engineering Baseline / YS
 
 ## Review Flow
 
-1. Recompute the Draft SHA-256 and verify `<feature>-validation.yaml`. The record must bind a pnpm-lockfile-pinned Redocly version, the exact lint command, exit code, execution time and readable evidence; its structural checks and lint must all pass. Custom parser evidence may supplement this record but cannot replace locked Redocly lint.
-2. Build a P0 traceability matrix from Spec functional requirements and interaction actions to OpenAPI paths, schemas, errors, and contract tests. Each UI action must map to a stable `operationId` and `x-yss-action-key` or an equivalent traceability entry. For P0 write/configuration models and read models that affect a key interaction, trace the exact property path, type/nesting, operation-specific requiredness, nullable/default/enum/format rules, source locator and error/test seam.
-3. Check page action coverage: every action has `actionKey`, endpoint or explicit non-goal, state transition, idempotency/concurrency rule, and error codes. When the Spec explicitly changes authentication or authorization behavior, trace that behavior through the same matrix.
-4. Check object lifecycle coverage: manage/maintain/configure/create/update/archive/retry/cancel/publish/export/create-draft semantics have endpoints or explicit scope downgrades.
-   When create/update or other lifecycle operations share one schema, verify that omission and requiredness semantics match for every operation; otherwise require split schemas or an explicit conditional contract. For credentials, distinguish create, update, masked readback, omit-to-preserve and explicit-clear behavior instead of imposing a universal required rule.
-5. Check YSS API baseline: REST shape, `x-yss-response-wrapper` values `SingleResult|MultiResult|PageResult`, `YssResultMeta` plus `allOf` concrete schemas, and stable DTO/schema names. The Java generic notation is a review shorthand only; it must not appear as an OpenAPI type or `$ref`.
-6. Check DTO wire shape against the profile: `success` is boolean, `dataType` is `string|null`, `code` is only `string|integer|null`, list/page `data` is an array, and single `data` points to the endpoint schema with explicit nullability. Check response/request direction separately.
-7. Check pagination input: only `pageIndex/pageSize/orderBy/orderDirection/groupBy` are client fields; `orderDirection` is `ASC|DESC`; `orderBy` / `groupBy` use endpoint whitelists; `offset`, `needTotalCount`, and `tempTotalCount` are negative assertions. `totalPages` is mapper-dependent and cannot enter a shared schema without fresh wire evidence.
-8. Check error contracts: field-level errors, model-level errors, disabled reasons, gate failures, and conflict responses. When the Spec explicitly changes authentication or authorization behavior, include its `401` / `403` and resource-filtering semantics here.
-9. Output a persistent review artifact under `docs/.scratch/<feature>/architecture/` or update the existing one.
+开始语义审查时读取 [P0 追踪与审查步骤](references/semantic-review.md)，逐项覆盖当前 Spec / UI 命中的字段、操作、错误和测试 seam。当前 SHA 与锁定 lint 证据通过后才可能得出 Approved。
 
 ## Automation Boundary
 
@@ -58,42 +49,4 @@ Block if any of these are true:
 
 ## Output Contract
 
-```markdown
-### Review Result
-<Approved / Blocked>
-
-### Structural Validation
-<Passed / Blocked; validation record, Draft SHA-256, locked Redocly version, command and evidence>
-
-### Semantic Review
-<Passed / Blocked; P0 field traceability and remaining semantic findings>
-
-### Blocking Findings
-- <file:line grounded finding>
-
-### Non-Blocking Suggestions
-- <can wait until architecture/design>
-
-### Contract Coverage
-- <P0 requirement -> endpoint/schema/error/test mapping summary>
-- <P0 field source -> operationId/schema/property path/shape/requiredness/constraints/error/test mapping summary>
-
-### YSS Baseline
-- <`x-yss-response-wrapper` map and `YssResultMeta` / `allOf` conformance>
-- <profile version, concrete `data` schemas, nullability, request/response direction and computed-field evidence>
-- <DDD boundary implications, implementation feasibility>
-
-### Contract Test Checklist
-- <wrapper meta fields: success/code/message/tips/dataType, including code string/integer/null cases>
-- <single object, non-page list empty array, page empty array and page boundary cases>
-- <PageQuery allowed fields, ASC/DESC and endpoint whitelist; negative assertions for offset/needTotalCount/tempTotalCount>
-- <target HTTP mapper identity and computed-field fixture, if totalPages or another getter is included>
-- <minimum contract tests before OpenAPI Freeze>
-
-### Next Action
-- <return to OpenAPI Draft / enter Engineering Baseline / architecture design / request YAML-to-JSON export after Freeze>
-```
-
-`Review Result` 只有在 `Structural Validation` 与 `Semantic Review` 均为 `Passed` 时才能是 `Approved`；不使用 `Conditionally Approved` 或 `Semantic Approved` 作为顶层结论。
-
-Prefer `.template-spec/api/templates/openapi-draft-review-checklist.md` when a tabular checklist is useful.
+形成持久化结论时读取 [审查输出契约](references/review-output.md)。`Review Result` 仅在 `Structural Validation` 和 `Semantic Review` 均为 `Passed` 时可为 `Approved`；否则 `Blocked`，不使用条件批准。

package/template/.agents/skills/yss-openapi-draft-review/references/review-output.md

@@ -0,0 +1,45 @@
+# OpenAPI Draft 审查输出
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
+
+## Output Contract
+
+```markdown
+### Review Result
+<Approved / Blocked>
+
+### Structural Validation
+<Passed / Blocked; validation record, Draft SHA-256, locked Redocly version, command and evidence>
+
+### Semantic Review
+<Passed / Blocked; P0 field traceability and remaining semantic findings>
+
+### Blocking Findings
+- <file:line grounded finding>
+
+### Non-Blocking Suggestions
+- <can wait until architecture/design>
+
+### Contract Coverage
+- <P0 requirement -> endpoint/schema/error/test mapping summary>
+- <P0 field source -> operationId/schema/property path/shape/requiredness/constraints/error/test mapping summary>
+
+### YSS Baseline
+- <`x-yss-response-wrapper` map and `YssResultMeta` / `allOf` conformance>
+- <profile version, concrete `data` schemas, nullability, request/response direction and computed-field evidence>
+- <DDD boundary implications, implementation feasibility>
+
+### Contract Test Checklist
+- <wrapper meta fields: success/code/message/tips/dataType, including code string/integer/null cases>
+- <single object, non-page list empty array, page empty array and page boundary cases>
+- <PageQuery allowed fields, ASC/DESC and endpoint whitelist; negative assertions for offset/needTotalCount/tempTotalCount>
+- <target HTTP mapper identity and computed-field fixture, if totalPages or another getter is included>
+- <minimum contract tests before OpenAPI Freeze>
+
+### Next Action
+- <return to OpenAPI Draft / enter Engineering Baseline / architecture design / request YAML-to-JSON export after Freeze>
+```
+
+`Review Result` 只有在 `Structural Validation` 与 `Semantic Review` 均为 `Passed` 时才能是 `Approved`；不使用 `Conditionally Approved` 或 `Semantic Approved` 作为顶层结论。
+
+Prefer `.template-spec/api/templates/openapi-draft-review-checklist.md` when a tabular checklist is useful.

package/template/.agents/skills/yss-openapi-draft-review/references/semantic-review.md

@@ -0,0 +1,16 @@
+# OpenAPI Draft 语义审查
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
+
+## Review Flow
+
+1. Recompute the Draft SHA-256 and verify `<feature>-validation.yaml`. The record must bind a pnpm-lockfile-pinned Redocly version, the exact lint command, exit code, execution time and readable evidence; its structural checks and lint must all pass. Custom parser evidence may supplement this record but cannot replace locked Redocly lint.
+2. Build a P0 traceability matrix from Spec functional requirements and interaction actions to OpenAPI paths, schemas, errors, and contract tests. Each UI action must map to a stable `operationId` and `x-yss-action-key` or an equivalent traceability entry. For P0 write/configuration models and read models that affect a key interaction, trace the exact property path, type/nesting, operation-specific requiredness, nullable/default/enum/format rules, source locator and error/test seam.
+3. Check page action coverage: every action has `actionKey`, endpoint or explicit non-goal, state transition, idempotency/concurrency rule, and error codes. When the Spec explicitly changes authentication or authorization behavior, trace that behavior through the same matrix.
+4. Check object lifecycle coverage: manage/maintain/configure/create/update/archive/retry/cancel/publish/export/create-draft semantics have endpoints or explicit scope downgrades.
+   When create/update or other lifecycle operations share one schema, verify that omission and requiredness semantics match for every operation; otherwise require split schemas or an explicit conditional contract. For credentials, distinguish create, update, masked readback, omit-to-preserve and explicit-clear behavior instead of imposing a universal required rule.
+5. Check YSS API baseline: REST shape, `x-yss-response-wrapper` values `SingleResult|MultiResult|PageResult`, `YssResultMeta` plus `allOf` concrete schemas, and stable DTO/schema names. The Java generic notation is a review shorthand only; it must not appear as an OpenAPI type or `$ref`.
+6. Check DTO wire shape against the profile: `success` is boolean, `dataType` is `string|null`, `code` is only `string|integer|null`, list/page `data` is an array, and single `data` points to the endpoint schema with explicit nullability. Check response/request direction separately.
+7. Check pagination input: only `pageIndex/pageSize/orderBy/orderDirection/groupBy` are client fields; `orderDirection` is `ASC|DESC`; `orderBy` / `groupBy` use endpoint whitelists; `offset`, `needTotalCount`, and `tempTotalCount` are negative assertions. `totalPages` is mapper-dependent and cannot enter a shared schema without fresh wire evidence.
+8. Check error contracts: field-level errors, model-level errors, disabled reasons, gate failures, and conflict responses. When the Spec explicitly changes authentication or authorization behavior, include its `401` / `403` and resource-filtering semantics here.
+9. Output a persistent review artifact under `docs/.scratch/<feature>/architecture/` or update the existing one.

package/template/.agents/skills/yss-openapi-governance/SKILL.md

@@ -45,57 +45,11 @@ YSS DTO 的可复用 HTTP/JSON 映射由 `.agents/skills/yss-dto/references/open
 
 ## 受控工具链
 
-在持有冻结 YAML 与派生记录的项目工作区中，将 `@redocly/cli` 固定在 `devDependencies` 并提交对应的 pnpm lockfile。使用项目脚本或下列等价命令；不得使用浮动 `npx --yes`、全局安装或未记录版本的转换器。
-
-```bash
-pnpm exec redocly lint docs/.scratch/<feature>/api/<feature>.yaml
-
-pnpm exec redocly bundle \
-  docs/.scratch/<feature>/api/<feature>.yaml \
-  --output docs/.scratch/<feature>/api/<feature>.json \
-  --ext json \
-  --component-renaming-conflicts-severity=error \
-  --metafile docs/.scratch/<feature>/api/<feature>.bundle-metafile.json
-```
-
-默认 bundle 保留内部 `$ref`，不要为图省事加入 `--dereferenced`；递归模型或循环引用需要保留其可表示的 `$ref` 结构。若项目将命令包装为 `pnpm openapi:bundle`，该脚本必须实际执行上述 `redocly bundle` 语义，并在记录中写明脚本和已锁定的包版本。
-
-`$ref` 默认只允许引用本 feature API 目录内的相对文件；禁止远程 URL、绝对路径以及越出该目录的路径遍历。需要共享组件或例外时，先在治理 / 架构记录中列出允许位置、所有者与 Freeze 影响，再执行 bundle。
+执行 lint / bundle 前读取 [锁定工具链](references/locked-toolchain.md)。只用项目 pnpm lockfile 固定的 Redocly；默认 `$ref` 限本 feature API 目录，例外先登记。
 
 ## 治理流程
 
-1. **建立或读取 YAML Draft**
-   - 读取 Spec、产品设计 / 状态矩阵、架构约束和既有 Freeze 记录。
-   - 在 `docs/.scratch/<feature>/api/<feature>.yaml` 创建或更新单一 OAS 3.1 文档；生命周期状态写入相邻 Markdown 记录，不写入 YAML 前置元数据。
-   - 所有操作使用稳定、可生成客户端的 `operationId`；页面动作可通过 `x-yss-action-key` 或同路径的追踪矩阵关联。
-
-2. **运行结构与治理校验**
-   - 先执行项目 lockfile 锁定版本的 `pnpm exec redocly lint`；CI 可以包装调用，但 validation record 必须记录这条实际命令与退出码。
-   - 检查 YAML 可解析、`$ref` 可解析、路径参数完整、operationId 唯一、examples 合法、schema 命名稳定。
-   - 从 `.template-spec/api/templates/openapi-draft-validation-record-template.yaml` 创建 `<feature>-validation.yaml`，记录 YAML SHA-256 与 lint 工具链；运行 `scripts/verify-openapi-draft-validation-record --root <project-root> <record>`。自定义解析脚本可以补充诊断，但不能代替锁定的 Redocly lint evidence。
-   - 对每个 P0 写模型、配置模型及影响关键交互的读模型建立字段级追踪：`Spec/交互来源 → operationId → request/response schema → property path → 类型与嵌套形状 → create/update requiredness → nullable/default/enum/format → error/test seam`。数组元素使用 `items[].property` 一类稳定 property path。
-   - create/update 或其他不同生命周期操作复用同一写 schema 时，逐操作证明 requiredness 与省略语义一致；若不一致，拆分 schema 或明确条件契约。凭据类字段还要说明创建、更新、掩码回显、省略保留与显式清空语义，不能仅凭字段名统一设为必填。
-   - 先运行 `scripts/verify-yss-dto-openapi-profile`，并记录 profile 版本；检查 `/api/v1/` 版本策略（或记录例外）、`x-yss-response-wrapper`、`YssResultMeta` + `allOf` 具体 schema、统一错误结构、分页、幂等 / 乐观锁和契约测试 seam。
-   - 每个响应都必须落成具体 endpoint schema：`SingleResult` 的 `data` 是具体对象或显式 nullable schema，`MultiResult` / `PageResult` 的 `data` 是数组；Java 的 `SingleResult<T>` / `PageResult<T>` 只能作为语义说明，不能直接写成 OAS type 或 `$ref`。
-   - `code` 按 profile 只允许 `string | integer | null`，`dataType` 按 profile 为 `string | null`；`offset`、`needTotalCount`、`tempTotalCount` 不得进入客户端分页输入；`totalPages` 只有目标 HTTP mapper / fixture 证明后才能进入契约。Spec 明确改变认证或授权行为时，把对应 `401` / `403`、资源过滤和错误语义作为普通 API 行为检查。
-
-3. **独立 Draft Review 与 Freeze**
-   - 将通过 verifier 且 SHA-256 与当前 YAML 一致的 validation record 交给 `yss-openapi-draft-review`。缺锁定 lint 时可以先做语义预审，但独立 Review 总结果必须为 `Blocked`；不能用“Freeze 前补 lint”支持 `Approved`。
-   - YAML、validation record 或 lint ruleset 变化后，旧结构证据与旧 Review 立即失效，必须重新校验和审查。阻断项未关闭前，YAML 仍是 review-only Draft，不得生成生产客户端。
-   - Freeze 记录必须引用 YAML 路径、Git ref（如适用）和 YAML SHA-256。冻结后 API 行为变更必须先回到 YAML Draft 与审查。
-   - 将同一 YAML 的版本与摘要、validation record、独立 Review 和 Freeze 写入 API Contract Decision（新建 v2；历史 v1 只读兼容，准备与迁移见 `.template-spec/process/contract-reading.md`）。`gate.engineering-contract-approved` 一次批准同时绑定 Technical Design、Data Architecture Decision、API Contract Decision；API `required` 时还必须直接绑定冻结 YAML。不得另造字符串 URI 或仅凭 `status: approved` 关闭门禁。
-
-4. **从冻结 YAML 派生 JSON**
-   - 使用上面的锁定 `redocly bundle` 命令生成 `docs/.scratch/<feature>/api/<feature>.json`，JSON 不纳入人工编辑面。
-   - 对输出 JSON 重新执行解析 / lint（按项目工具链），确认 bundle 未产生组件重名冲突或无法解析的引用。
-   - 写入 `docs/.scratch/<feature>/api/<feature>-json-export.md`，可从 `.template-spec/api/templates/openapi-json-export-record-template.md` 创建。
-   - 记录 YAML SHA-256、JSON SHA-256、OAS 版本、Redocly CLI 版本与 lockfile 引用、完整命令、metafile、`$ref` 例外以及结果。
-
-5. **交给下游前端**
-   - 仅当 Freeze、JSON 派生记录和 JSON 校验均通过时，才把派生 JSON 交给 `yss-api-integration` 与目标前端实现仓库。
-   - JSON 的治理产物固定为 `docs/.scratch/<feature>/api/<feature>.json`。跨仓库时只能由批准的 Cross-repo 子合同或项目脚本将同一字节内容物化为 `<frontend>/openapi/openapi.json`，并记录两端相同的 SHA-256 与交接路径。
-   - 本模板不读取、修改或验证目标前端项目的客户端生成配置，不执行客户端生成，也不把生成动作加入 CI；目标前端项目在需要时手动运行其既有代码生成命令。
-   - 接口调整回写 YAML，而不是编辑 JSON 或生成的 TypeScript。
+当前任务涉及 Draft、结构校验、Review / Freeze 或派生交接时，读取 [治理分阶段步骤](references/governance-workflow.md) 中对应步骤。阶段顺序保持 Draft → 校验 → 独立 Review / Freeze → JSON → 下游；任何前置证据缺失不得越过阶段。前端 profile 仅消费后端权威，不能执行后端批准。
 
 ## 阻断规则
 

package/template/.agents/skills/yss-openapi-governance/references/governance-workflow.md

@@ -0,0 +1,38 @@
+# OpenAPI 治理步骤
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
+
+## 治理流程
+
+1. **建立或读取 YAML Draft**
+   - 读取 Spec、产品设计 / 状态矩阵、架构约束和既有 Freeze 记录。
+   - 在 `docs/.scratch/<feature>/api/<feature>.yaml` 创建或更新单一 OAS 3.1 文档；生命周期状态写入相邻 Markdown 记录，不写入 YAML 前置元数据。
+   - 所有操作使用稳定、可生成客户端的 `operationId`；页面动作可通过 `x-yss-action-key` 或同路径的追踪矩阵关联。
+
+2. **运行结构与治理校验**
+   - 先执行项目 lockfile 锁定版本的 `pnpm exec redocly lint`；CI 可以包装调用，但 validation record 必须记录这条实际命令与退出码。
+   - 检查 YAML 可解析、`$ref` 可解析、路径参数完整、operationId 唯一、examples 合法、schema 命名稳定。
+   - 从 `.template-spec/api/templates/openapi-draft-validation-record-template.yaml` 创建 `<feature>-validation.yaml`，记录 YAML SHA-256 与 lint 工具链；运行 `scripts/verify-openapi-draft-validation-record --root <project-root> <record>`。自定义解析脚本可以补充诊断，但不能代替锁定的 Redocly lint evidence。
+   - 对每个 P0 写模型、配置模型及影响关键交互的读模型建立字段级追踪：`Spec/交互来源 → operationId → request/response schema → property path → 类型与嵌套形状 → create/update requiredness → nullable/default/enum/format → error/test seam`。数组元素使用 `items[].property` 一类稳定 property path。
+   - create/update 或其他不同生命周期操作复用同一写 schema 时，逐操作证明 requiredness 与省略语义一致；若不一致，拆分 schema 或明确条件契约。凭据类字段还要说明创建、更新、掩码回显、省略保留与显式清空语义，不能仅凭字段名统一设为必填。
+   - 先运行 `scripts/verify-yss-dto-openapi-profile`，并记录 profile 版本；检查 `/api/v1/` 版本策略（或记录例外）、`x-yss-response-wrapper`、`YssResultMeta` + `allOf` 具体 schema、统一错误结构、分页、幂等 / 乐观锁和契约测试 seam。
+   - 每个响应都必须落成具体 endpoint schema：`SingleResult` 的 `data` 是具体对象或显式 nullable schema，`MultiResult` / `PageResult` 的 `data` 是数组；Java 的 `SingleResult<T>` / `PageResult<T>` 只能作为语义说明，不能直接写成 OAS type 或 `$ref`。
+   - `code` 按 profile 只允许 `string | integer | null`，`dataType` 按 profile 为 `string | null`；`offset`、`needTotalCount`、`tempTotalCount` 不得进入客户端分页输入；`totalPages` 只有目标 HTTP mapper / fixture 证明后才能进入契约。Spec 明确改变认证或授权行为时，把对应 `401` / `403`、资源过滤和错误语义作为普通 API 行为检查。
+
+3. **独立 Draft Review 与 Freeze**
+   - 将通过 verifier 且 SHA-256 与当前 YAML 一致的 validation record 交给 `yss-openapi-draft-review`。缺锁定 lint 时可以先做语义预审，但独立 Review 总结果必须为 `Blocked`；不能用“Freeze 前补 lint”支持 `Approved`。
+   - YAML、validation record 或 lint ruleset 变化后，旧结构证据与旧 Review 立即失效，必须重新校验和审查。阻断项未关闭前，YAML 仍是 review-only Draft，不得生成生产客户端。
+   - Freeze 记录必须引用 YAML 路径、Git ref（如适用）和 YAML SHA-256。冻结后 API 行为变更必须先回到 YAML Draft 与审查。
+   - 将同一 YAML 的版本与摘要、validation record、独立 Review 和 Freeze 写入 API Contract Decision（新建 v2；历史 v1 只读兼容，准备与迁移见 `.template-spec/process/contract-reading.md`）。`gate.engineering-contract-approved` 一次批准同时绑定 Technical Design、Data Architecture Decision、API Contract Decision；API `required` 时还必须直接绑定冻结 YAML。不得另造字符串 URI 或仅凭 `status: approved` 关闭门禁。
+
+4. **从冻结 YAML 派生 JSON**
+   - 使用 [锁定工具链](locked-toolchain.md) 中的 `redocly bundle` 命令生成 `docs/.scratch/<feature>/api/<feature>.json`，JSON 不纳入人工编辑面。
+   - 对输出 JSON 重新执行解析 / lint（按项目工具链），确认 bundle 未产生组件重名冲突或无法解析的引用。
+   - 写入 `docs/.scratch/<feature>/api/<feature>-json-export.md`，可从 `.template-spec/api/templates/openapi-json-export-record-template.md` 创建。
+   - 记录 YAML SHA-256、JSON SHA-256、OAS 版本、Redocly CLI 版本与 lockfile 引用、完整命令、metafile、`$ref` 例外以及结果。
+
+5. **交给下游前端**
+   - 仅当 Freeze、JSON 派生记录和 JSON 校验均通过时，才把派生 JSON 交给 `yss-api-integration` 与目标前端实现仓库。
+   - JSON 的治理产物固定为 `docs/.scratch/<feature>/api/<feature>.json`。跨仓库时只能由批准的 Cross-repo 子合同或项目脚本将同一字节内容物化为 `<frontend>/openapi/openapi.json`，并记录两端相同的 SHA-256 与交接路径。
+   - 本模板不读取、修改或验证目标前端项目的客户端生成配置，不执行客户端生成，也不把生成动作加入 CI；目标前端项目在需要时手动运行其既有代码生成命令。
+   - 接口调整回写 YAML，而不是编辑 JSON 或生成的 TypeScript。