create-yss-spec 3.5.3 → 3.5.5

package/template/.cursor/skills/yss-design-system/assets/enterprise-craft/styles.css

@@ -0,0 +1,32 @@
+:root { font: var(--brand-font-size)/var(--brand-line-height) var(--brand-font-family); color: var(--brand-color-text); background: var(--brand-color-bg-layout); }
+* { box-sizing: border-box; } body { margin: 0; } main { max-width: 1440px; margin: auto; padding: var(--brand-size-lg); }
+.review { padding: var(--brand-size-sm) var(--brand-size); background: var(--brand-color-bg-container); border-bottom: 1px solid var(--brand-color-border); }
+.review p { margin: var(--brand-size-xs) 0; color: var(--brand-color-text-secondary); }
+.controls, .actions { display: flex; align-items: center; flex-wrap: wrap; gap: var(--brand-size-sm); }
+.controls label { display: flex; align-items: center; gap: var(--brand-size-xs); }
+h1 { font-size: var(--brand-font-size-xl); line-height: var(--brand-line-height-heading); margin: 0; }
+h2 { font-size: var(--brand-font-size-lg); margin: 0 0 var(--brand-size-sm); } p { overflow-wrap: anywhere; }
+.surface { background: var(--brand-color-bg-container); border-radius: var(--brand-border-radius-lg); padding: var(--yss-card-padding); }
+.page-heading { display: flex; justify-content: space-between; gap: var(--brand-size); align-items: start; margin-bottom: var(--brand-size); }
+.secondary { color: var(--brand-color-text-secondary); } .page-heading p { margin-bottom: 0; }
+button, input, select { font: inherit; color: inherit; background: var(--brand-color-bg-container); min-height: var(--yss-control-height); border: 1px solid var(--brand-color-border); border-radius: var(--brand-border-radius); max-width: 100%; }
+button { padding: 0 var(--brand-size-sm); cursor: pointer; } input { padding: 0 var(--brand-size-sm); width: 100%; } button:disabled { cursor: not-allowed; opacity: .5; }
+.primary { color: var(--yss-color-on-primary); background: var(--yss-color-primary-control); border-color: var(--yss-color-primary-control); }
+:focus-visible { outline: 2px solid var(--yss-color-primary-control); outline-offset: 2px; }
+label { display: block; } .query { display: flex; gap: var(--brand-size-sm); align-items: end; padding-bottom: var(--brand-size); border-bottom: 1px solid var(--brand-color-border-secondary); }
+.query label { flex: 1; max-width: 32rem; } .table-scroll { overflow-x: auto; } table { width: 100%; border-collapse: collapse; } th, td { text-align: left; padding: var(--brand-size-sm); border-bottom: 1px solid var(--brand-color-border-secondary); } th { font-weight: var(--brand-font-weight-strong); background: var(--brand-color-fill-quaternary); } td:first-child { white-space: nowrap; font-variant-numeric: tabular-nums; }
+.section { margin-block: var(--brand-size-lg); } .fields { display: grid; grid-template-columns: repeat(2,minmax(0,1fr)); gap: var(--brand-size); } .field p { margin: var(--brand-size-xs) 0; }
+.feedback { border-left: var(--brand-size-xxs) solid var(--brand-color-info); padding: var(--brand-size-sm); background: var(--brand-color-fill-quaternary); margin-block: var(--brand-size); }
+.feedback:empty { display: none; } .feedback[data-kind="error"] { border-color: var(--brand-color-error); } .feedback[data-kind="success"] { border-color: var(--brand-color-success); }
+.approval-item { display: grid; grid-template-columns: minmax(0,1fr) auto; gap: var(--brand-size); padding-block: var(--brand-size); border-bottom: 1px solid var(--brand-color-border-secondary); }
+dialog { color: inherit; background: var(--brand-color-bg-elevated); width: min(90vw,40rem); border: 1px solid var(--brand-color-border); border-radius: var(--brand-border-radius-lg); padding: var(--brand-size-lg); }
+dd { margin: 0 0 var(--brand-size); overflow-wrap: anywhere; }
+/* Deliberate hierarchy weaknesses; content, tokens and behavior stay identical. */
+.before h1, .before h2 { font-size: var(--brand-font-size); font-weight: normal; }
+.before .page-heading { display: block; } .before .page-heading .actions { margin-top: var(--brand-size-xs); }
+.before .section { margin-block: var(--brand-size-xs); } .before .secondary { color: var(--brand-color-text); }
+.before .query { border: 0; padding-bottom: var(--brand-size-xs); } .before th { background: var(--brand-color-bg-container); font-weight: normal; }
+.before .fields { gap: var(--brand-size-xs); } .before .approval-item { border: 0; padding-block: var(--brand-size-xs); }
+.before .primary { color: var(--brand-color-text); background: var(--brand-color-bg-container); border-color: var(--brand-color-border); }
+@media(max-width:576px) { main { padding: var(--brand-size-sm); } .surface { padding: var(--brand-size-sm); } .fields { grid-template-columns: 1fr; } .page-heading, .query { flex-direction: column; align-items: stretch; } .approval-item { grid-template-columns: 1fr; } .table-scroll table { min-width: 34rem; } }
+@media(prefers-reduced-motion:reduce) { * { animation: none !important; transition: none !important; } }

package/template/.cursor/skills/yss-design-system/references/data-quality-theme.md

@@ -4,9 +4,9 @@
 
 采用 Data Quality `packages/src/store/theme.ts` 的全局浅色主题：主色 / info `#3371ff`，正文14px，默认 / small / large控件32 / 24 / 40px，圆角6 / 4 / 8px，Card内距20px。`isDarkMode=false`、`isCompactMode=false`。页面玻璃效果、广大发行主题与人保红色 JSP 主题均为局部选择。
 
-Ant Design v6 提供设计语义与 HTML 原型算法参考；Data Quality 真实运行时为 Vue3 + ant-design-vue4.2.6 + YSS UI。实现主题通过目标库公开 ConfigProvider API 适配，不能把 React API 或 v6版本号移植为 Vue 依赖结论。
+Ant Design v6 提供设计语义与历史算法来源参考；Data Quality 真实运行时为 Vue3 + ant-design-vue4.2.6 + YSS UI。实现主题通过目标库公开 ConfigProvider API 适配，不能把 React API 或 v6版本号移植为 Vue 依赖结论。
 
-`primary-control` / hover 是 YSS 为白色小字保留的可访问性变体，品牌 seed 保持 Data Quality 蓝；它们是已声明适配，不是 Data Quality 原值。默认32px，显式 compact28px，seed不得以28px再次压缩。暗色使用算法生成中性色，不能把浅色 text/surface 固定覆盖带入暗色。
+`primary-control` / hover 是 YSS 为白色小字保留的可访问性变体，品牌 seed 保持 Data Quality 蓝；它们是已声明适配，不是 Data Quality 原值。生产默认使用根规范普通控件，显式 compact 才应用算法一次；新原型默认采用命名紧凑变体，窄屏和 comfortable 使用普通变体，不应用生产 compact 算法。暗色使用算法生成中性色，不能把浅色 text/surface 固定覆盖带入暗色。
 
 更新顺序：修改根 DESIGN.md → 更新 design-system-sync.yaml 摘要 → 在独立作者目录提供固定 antd6.6.4 → `node .template-source/tooling/node/scripts/design-md.mjs export dtcg --write --write-manifest --antd-toolchain <作者目录>` → lint / drift → 刷新 frontend scaffold baseline → 浏览器核对 HTML 和 Vue 两条实现。禁止手改 token 快照或生成投影。
 

package/template/.cursor/skills/yss-design-system/references/design-qa-theme.md

@@ -7,7 +7,7 @@
 - 规范：根 `DESIGN.md`
 - 治理说明：`.template-spec/design/design.md`
 - Token 投影：`.template-spec/design/tokens/theme.json`、`.template-spec/design/tokens/tokens.default.json`、`.template-spec/design/tokens/variables.css`
-- 主题选择：默认采用根 `DESIGN.md` 的 Data Quality 浅色主题；仅显式暗色 / 紧凑模式使用对应的 `tokens.dark.json` / `variables.dark.css` / `tokens.compact.json`，以实际消费文件记录摘要。
+- 主题选择：新原型默认浅色 compact，从根 `DESIGN.md` 的命名变体与 variables.css 选择密度；comfortable 使用普通变体，不消费生产 tokens.compact.json 算法结果。生产主题按实现合同选择。暗色只保留未验证历史快照入口，启用前重新派生与核验；摘要登记实际消费文件。
 - 实现截图：当前原型或页面在同一 viewport / 主题 / 状态下的渲染
 
 官方 `https://ant.design/design.md` 只是上游默认。项目覆盖与官方不同时，以根 `DESIGN.md` 为准；本清单不复制规范值。

package/template/.cursor/skills/yss-design-system/references/design-system.md

@@ -88,7 +88,7 @@
 执行规则：
 
 - 间距只使用 `spacing.*`，不要补写未登记的中间值。
-- 默认采用 Data Quality 浅色、32px 控件；仅显式紧凑模式叠加一次 compact algorithm；seed 与计算结果从规范源和派生快照读取，不得二次 compact。
+- 原型新页面默认使用 [紧凑主题](prototype-default-theme.md) 中的根规范命名变体；生产主题仍按其合同，compact algorithm 仅显式选择时应用一次。
 - 表单、筛选区、工具栏、表格、详情页使用密集但有节奏的布局。
 - 控件圆角不得明显大于容器圆角。
 - 不使用任意 magic number；确需新增尺寸时，先说明为什么 token 不够。
@@ -179,7 +179,7 @@
 
 ## 前端落地
 
-React + Ant Design：
+历史来源或明确采用 React + Ant Design 的生产实现（新原型已退役此路线）：
 
 - 使用 `ConfigProvider` 注入主题。
 - 默认采用 Data Quality 浅色与 32px 控件；仅显式紧凑模式使用 `theme.compactAlgorithm`；暗色紧凑模式组合 `theme.darkAlgorithm` 与 `theme.compactAlgorithm`，不手工反转色值或逐组件压缩。
@@ -218,7 +218,7 @@ YSS UI / Vue：
 
 - 是否消费 token，而不是硬编码颜色和尺寸。
 - 是否以 semantic token 表达颜色、圆角、阴影和状态层级。
-- 是否使用当前 `DESIGN.md` 与所选主题快照的排版、控件和间距值；默认使用 default，仅显式紧凑模式使用 compact，且没有重复 compact。
+- 是否使用当前 `DESIGN.md` 与所选主题快照的排版、控件和间距值；原型按登记密度使用根规范命名变体，生产按合同选择算法快照，没有重复 compact。
 - 是否保留 hover、focus、active、disabled、loading、empty、error 状态。
 - 是否只保留一个 single primary action，并让每个关键操作提供 interaction feedback。
 - 是否在目标字号和背景下复核 accessibility contrast。

package/template/.cursor/skills/yss-design-system/references/enterprise-craft.md

@@ -0,0 +1,33 @@
+# 企业后台设计方法与示例
+
+在已有 `DESIGN.md` 与当前行为合同内改善层级、密度和反馈。本参考不定义新的 Token、组件 API、业务规则或评分门禁。
+
+## 三个判断
+
+1. 主任务能否直接定位？首屏呈现当前任务、关键数据及主操作；辅助说明不与主操作竞争。
+2. 数据、动作与说明的权重是否合适？用项目已有排版、间距、分组和表面角色组织信息；密集不等于挤压所有间距，清晰不等于无限增加留白。
+3. 状态是否说明原因和下一步？错误靠近受影响内容，阻断和权限用明确文本，失败保留输入并说明恢复途径。装饰与动效不得延迟高频操作。
+
+先生成完整页面，再同批检查桌面与窄屏，集中修整并复验受影响场景。记录 visual/layout/interaction/content/accessibility/cross-platform 原有六轴中的发现。预算是停止继续迭代的条件，不是通过条件；关键缺陷仍阻断。代码扫描、画面观察与真实用户证据分别报告。
+
+局部修改先核对设计输入中的保持项：在相同视口与状态对照原页面的区域、字段顺序和操作位置。可读性修复不能顺带重排被要求保持的布局；若确有必要，先记录范围变化并按既有用户决定协议处理。该核对属于现有 layout/interaction QA，不新增评审门禁。
+
+## 可运行示例
+
+`assets/enterprise-craft/index.html` 提供查询列表、表单详情、审批异常三组前后对照，直接打开即可运行。它从当前仓库的派生 CSS 读取 Token；需要脱离仓库携带时运行：
+
+```bash
+node .agents/skills/yss-design-system/scripts/export-craft-examples.mjs --project-root <项目根> --output <新的空目录>
+```
+
+导出器复制当前项目 Token 并绑定 `DESIGN.md` 摘要。两侧共享数据、场景和交互实现；差异仅在内容组织、层级及反馈位置。示例使用虚构资料和固定失败/权限/冲突场景，不代表产品需求、已批准原型或生产组件能力。窄屏与键盘交互也需要实际检查。
+
+观察重点：列表中查询/重置与业务主操作的分区；表单中字段分组和错误定位；审批中待处理项、阻断原因、恢复动作的关联。对照前态刻意保留层级问题，仅供教学，不是可复用的推荐模板。
+
+## 来源与边界
+
+方法参考 Impeccable [Operate](https://github.com/pbakaus/impeccable/blob/114ea1d3838fca73b253af45f873b9c4f5f213c8/.github/skills/impeccable/reference/operate.md)（Apache-2.0）与 [Interface Design](https://github.com/Dammyjay93/interface-design/blob/2f9be3206855bcb2d1d0af262c8bae25cba6658d/.claude/skills/interface-design/SKILL.md)（MIT）。示例为本项目独立编写；不复制外部字体/数值默认值，不引入第二份设计系统或第二套 QA。
+
+## 从观察到任务模式
+
+需要完整交互时，按需读取 `yss-prototype-stage/references/business-patterns.md`：查询层级对应查询详情，字段分组对应分步表单，阻断与恢复对应审批及冲突模式。窄屏检查必须实际定位并操作按钮；无整体溢出不能证明操作可发现。高密度分析保留必要表格时，同时提供可键盘滚动的区域和稳定的资料定位入口。

package/template/.cursor/skills/yss-design-system/references/page-composition.md

@@ -0,0 +1,24 @@
+# 企业页面组合与主题适配
+
+此文只说明使用规范角色的方法。先读根 DESIGN.md、已有页面保持项、交互说明和状态矩阵；数值以规范派生变量为准。
+
+- 页面按任务阶段分组：筛选区回答范围，工具栏回答可执行动作，结果区回答对象状态，详情承接次要字段。Card 表示有独立标题/责任的区域，不以 Card 套 Card 制造层级；Separator 分隔相邻内容，不替代标题。
+- 紧凑工具栏保持单个主操作；次要动作进入 DropdownMenu 时保留可发现入口。结果数、筛选范围、选中数量和剩余事项可扫描，窄屏按字段组换行，不压缩正文。
+- Field 同时组织标签、说明和错误，错误定位到控件；长说明自然换行。InputGroup 只承载输入附加信息或相关操作，外层统一边框与焦点，内层禁止重复尺寸。
+- Sheet 承接列表详情，Dialog 承接短决策，AlertDialog 承接现有合同要求的确认。标题、说明、退出和焦点返回齐全；窄屏操作不被浮层边缘遮挡。
+- 持续权限/冲突/部分失败原因用 Alert，Badge 仅补充状态。Tooltip 不承载唯一必要信息。Empty 给原因和下一步，Skeleton/Spinner 配可读加载状态。
+- 指标只突出任务相关主次；Tabs 不隐藏必须同时比较的信息。必要横向表格保留关键列和滚动提示，外层页面不滚动溢出。
+
+新原型默认浅色 compact；comfortable 显式选择，既有局部修改遵守保持项。映射层消费命名组件变体及 body/spacing/rounded 角色，不再应用生产 compact 算法。暗色入口仅供历史参考，未完成当前规范验证。
+
+组件使用条件、依赖、状态和键盘配方见 `yss-prototype-stage/references/component-recipes.md`。三组正反例见 [enterprise-craft.md](enterprise-craft.md)；五类可运行模式和组件状态展示由原型技能导出。预览 `.template-source/design/preview.html` 只展示主题与组件状态，不能当作已批准产品页面。
+
+## Vue 高保真组件适配
+
+新页面优先使用原型技能登记的 shadcn-vue 组件，按任务借鉴 Blocks；样式映射仍消费根 DESIGN 角色。Select/Menu/Sheet 的交互由 Reka UI 承担，主题层只改变外观，不删焦点环、禁用反馈或退出路径。玻璃仅用于已选择的局部表面，正文与表格保持稳定底色，实测背景合成对比度并支持减少透明；不把研究外观写成规范默认。
+
+## 企业应用壳
+
+模块导航 → 分组侧栏 → 已打开页面 Tag → 页面任务，只呈现真实可操作入口。根 DESIGN 的 workspace 角色规定尺寸和标题；主工作区流式填充，表单内部保留阅读宽度，去除装饰性大标题与重复说明。详情选中后才占位，关闭归还空间；窄屏由 Sheet 承接导航和详情，不保留桌面侧栏挤压正文。主内容、详情和表格滚动职责分开，固定工具栏不遮住焦点和错误。状态见原型技能 `references/enterprise-workspace.md`。
+
+页面导航 Tag 使用独立轮廓、主色浅底当前态以及分开的激活/关闭按钮；不套用页内 Tabs 下划线。页内 Tabs 只用主色文字和指示线，不叠加灰底分段控件。收起导航图标居中，当前项有标记，Tooltip 的反相背景与箭头一致。尺寸与动效读取根规范，减少动效时取消过渡。

package/template/.cursor/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/.cursor/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/.cursor/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/.cursor/skills/yss-harness-upgrade/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: yss-harness-upgrade
+description: 升级既有 YSS 模板实例，规划同家族版本迁移、定制合并、持久归档、验证与恢复；用于 create-yss-spec 及 design/backend/frontend CLI 实例升级，不处理业务代码或数据库迁移。
+---
+
+# YSS 实例升级
+
+先读取根 `yss-project.yaml`、`CONTEXT.md` 和 [统一协议](../../../.template-spec/process/harness-upgrade.md)。目标必须是已登记的同家族 `project-instance`；身份/schema 不支持时只诊断，不能重新 init 或猜测身份。模板源的技能维护由 `maintaining-skills` 处理。
+
+## 工作顺序
+
+1. 确认目标绝对路径、用户授权范围、实际 CLI 路径及版本、模板 metadata、工作区已有改动。依据 [家族适配](references/cli-families.md) 选定 CLI。未指定目标版本时查询同家族稳定版本并固定精确包版本和摘要，执行期间不再引用 `latest`。CLI 程序升级和项目实例迁移分别记录，不自动安装全局版本。
+2. 用固定 CLI 的 `migrate status` 检查中断事务。有中断时先 `migrate recover` 预览，按既有授权执行 `--apply`，然后重新规划。不得删除状态目录绕过恢复。
+3. `migrate plan --target-dir <绝对路径> --output <项目外全新计划.json>`。旧治理布局迁移显式附加 `--migrate-layout`；退出分发文件清理显式附加 `--prune`。计划阶段不修改项目；检查计划中的版本、变化路径、保留项和归档位置。
+4. 冲突时在项目外起草候选差异和 `--resolutions` 文件。只使用计划报告的可信受管冲突；`preserve` 保留原文，`merge` 提供候选内容并绑定原文件及新模板摘要。向用户展示新的语义取舍，复用已有范围授权；未获授权的新决定保持等待。不能使用 `--force` 批量覆盖，不能先修改项目来消除冲突。
+5. 用相同固定 CLI 执行 `migrate apply --plan <计划>`。执行器重新生成候选并验证计划、归档、身份和输入摘要；`STALE_PLAN` 时重新规划，不能手改摘要续跑。迁移不自动 commit、stash、reset、push 或发布。
+6. 查看回执和实例验证结果，执行相同选项的新计划验证无重复迁移。核对业务文件与既有工作区改动保持，说明保留的定制和现有失败。输出实际版本、归档/回执位置、验证证据和剩余问题；结构检查不能代替真实 CLI 或 Agent 行为验证。
+
+## 恢复与边界
+
+- `migrate recover` 恢复未完成事务；`migrate rollback` 预览最近一次成功迁移的整体回退。两者仅加 `--apply` 才写入。回退遇到后续修改或损坏归档必须保留现场，不覆盖新工作。
+- Spec、Ticket、合同、人工回复、批准和正式验证默认保留。路径迁移不产生新批准；语义或批准绑定变化交回原生命周期，不补造旧状态。
+- 不执行跨家族转换、任意历史版本跳转、业务重构或数据库迁移。未知基线不能由 Agent 猜测；归档不能作为扩大写入授权的理由。
+- 旧实例缺少本技能时，从已固定 CLI 包的 `resources/upgrade-skill/` 在项目外读取入口及相邻协议。不得先同步目标项目来安装升级技能。
+
+本技能只编排，不复制迁移执行器。研究新技术事实时用 `yss-research`；结论输出按 `lifecycle-document-output` 使用 `i-have-adhd`。不批准 Slice、不设置 `ready-for-agent`、不宣称可发布。

package/template/.cursor/skills/yss-harness-upgrade/references/cli-families.md

@@ -0,0 +1,14 @@
+# 同家族升级适配
+
+| CLI | 实例 metadata |
+|---|---|
+| create-yss-spec | .yss-template.json |
+| create-yss-harness-design | .yss-harness-design.json |
+| create-yss-harness-backend | .yss-harness-backend.json |
+| create-yss-harness-frontend | .yss-harness-frontend.json |
+
+身份还需通过各 CLI 原有 profile/schema 检查。多个 metadata、旧 dev 家族、未知 schema、符号链接或矛盾 profile 均不能自动接管。`migrate` 不是降级或跨家族工具。
+
+四类 CLI 的新入口一致：`migrate plan|apply|status|recover|rollback`，支持 `--json`。`migrate plan` 只向显式指定的项目外新文件输出；`apply --plan <文件>` 显式写入。recover/rollback 默认只读，写入需 `--apply`。不要从旧 `sync` 推断新接口：主 CLI 普通 sync 会写入，专职 CLI sync 默认预览。
+
+目标模板来自当前固定 CLI 包，不接受计划中的下载地址或脚本。版本、模板和执行器摘要不匹配时更换为生成计划的原包，或重新规划；不得修改计划来绕过。已有 `update/upgrade` 仅更新 CLI 程序，既有 `recover` 仍只恢复原事务。

package/template/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/skills/yss-implementation-contract-compiler/references/boundaries.md

@@ -114,6 +114,7 @@
 | `yss-implementation-contract-compiler` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-openapi-governance` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-stage-decision` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
+| `yss-harness-upgrade` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-research` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-product-lifecycle` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `code-review` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |

package/template/.cursor/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` 单项通过或脚手架成功不能替代合同批准；生成范围从机械内容变成业务行为时触发完整重路由。