npm - create-yss-spec - Versions diffs - 3.5.0 → 3.5.3 - Mend

create-yss-spec 3.5.0 → 3.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (882) hide show

package/template/{docs → .template-spec}/design/design.md RENAMED Viewed

@@ -5,13 +5,13 @@
 ## 与 DESIGN.md 的职责边界
 - `DESIGN.md`：机器可读的颜色、排版、圆角、间距和组件视觉变体规范；使用 Google `design.md` alpha 格式。
-- `docs/design/tokens/*`：由规范源投影的运行时快照，禁止直接修改后作为规范依据；使用 `scripts/design-md` 执行漂移检查。
+- `.template-spec/design/tokens/*`：由规范源投影的运行时快照，禁止直接修改后作为规范依据；使用 `scripts/design-md` 执行漂移检查。
 - 本文件：解释 YSS UI / Ant Design 双轨、页面设计约束、原型证据和生命周期门禁，不重新定义规范 token 的具体值。
 - Spec、交互说明和状态矩阵：继续承载业务状态、API、权限、并发、失败恢复和页面验收，不写入 `DESIGN.md`。
 ## 来源与定位
-本文件基于本地设计系统包首次分析整理，并在后续用项目 Ant Design 5 Less / `:root` CSS 变量覆盖默认亮色主题。紧凑密度、间距和容器规格同时参考既有 YSS 实现。视觉 token 的规范源改为根目录 `DESIGN.md`；本文件和 `docs/design/tokens/*` 是治理说明与派生视图。外部目录只作为历史输入或实现样本，不作为后续工程依赖，也不作为实现语言。
+本文件基于本地设计系统包首次分析整理，并在后续用项目 Ant Design 5 Less / `:root` CSS 变量覆盖默认亮色主题。紧凑密度、间距和容器规格同时参考既有 YSS 实现。视觉 token 的规范源改为根目录 `DESIGN.md`；本文件和 `.template-spec/design/tokens/*` 是治理说明与派生视图。外部目录只作为历史输入或实现样本，不作为后续工程依赖，也不作为实现语言。
 关键来源：
@@ -21,11 +21,11 @@
 | 历史 `Product-Design-System` 包 | 首次引入 Ant Design 企业级语义、状态矩阵和验收习惯 | 仅保留原则、组件规则和审查清单 |
 | 项目 Ant Design 5 Less / `:root` 变量 | 品牌主色、运行时切换别名、色板与布局 token 的历史项目覆盖 | 保留经批准的品牌覆盖；不作为 v6 / Antdv Next API 事实 |
 | `yss-meta` 的 `packages/src/styles` | 已落地的紧凑间距、Card 圆角、CSS 变量桥接和客户主题案例 | 只提取稳定语义；utility class、客户覆盖和兼容补丁不进入默认规范 |
-| `docs/design/tokens/tokens.default.json` | 默认亮色主题派生 token | 作为实现 token 基线 |
-| `docs/design/tokens/tokens.dark.json` | 暗色主题派生 token | 暗色仍走 `darkAlgorithm`；本轮未按新 seed 重派生完整暗色色板 |
-| `docs/design/tokens/tokens.compact.json` | 紧凑密度主题派生 token | 共享亮色 seed，紧凑高度算法保持现状 |
-| `docs/design/tokens/variables.css` | `--brand-*` 与运行时别名 | 前端实现时优先转换为项目 token |
-| `docs/design/tokens/theme.json` | Ant Design `ConfigProvider` theme 配置 | React + Ant Design 项目可直接参考 |
+| `.template-spec/design/tokens/tokens.default.json` | 默认亮色主题派生 token | 作为实现 token 基线 |
+| `.template-spec/design/tokens/tokens.dark.json` | 暗色主题派生 token | 暗色仍走 `darkAlgorithm`；本轮未按新 seed 重派生完整暗色色板 |
+| `.template-spec/design/tokens/tokens.compact.json` | 紧凑密度主题派生 token | 共享亮色 seed，紧凑高度算法保持现状 |
+| `.template-spec/design/tokens/variables.css` | `--brand-*` 与运行时别名 | 前端实现时优先转换为项目 token |
+| `.template-spec/design/tokens/theme.json` | Ant Design `ConfigProvider` theme 配置 | React + Ant Design 项目可直接参考 |
 历史 Less 输入曾存在互相覆盖的默认值；裁定结果已迁入根 `DESIGN.md`。本文件不保留第二份值表。历史值、上游默认或客户覆盖只能作为追溯输入，不能反向覆盖 `DESIGN.md`；需要改变裁定时先改规范源，再重新生成 Token/CSS 投影并更新同步摘要。
@@ -35,11 +35,11 @@
 ## 原型设计依据的优先级
-当前原型以项目根 `DESIGN.md` 为视觉规范源，`docs/design/design.md` 解释治理规则，`docs/design/tokens/*` 是派生实现视图。需要真实 AntD 控件辅助评审时，上游资料只提供组件事实，不覆盖项目规范；在 `prototype-evidence.yaml` 中记录根规范与 Token digest，不把上游默认直接写回项目实现。
+当前原型以项目根 `DESIGN.md` 为视觉规范源，`.template-spec/design/design.md` 解释治理规则，`.template-spec/design/tokens/*` 是派生实现视图。需要真实 AntD 控件辅助评审时，上游资料只提供组件事实，不覆盖项目规范；在 `prototype-evidence.yaml` 中记录根规范与 Token digest，不把上游默认直接写回项目实现。
 项目覆盖与官方默认的差异直接读取根 `DESIGN.md` 并用 `design-md diff` 核验；本文件不复制差异值。上游预设色板可以保留其自身颜色谱，但**色板预设 ≠ 品牌 seed**。
-Codex `$design-qa` 的 Colors/tokens 与 Fonts/typography 对照必须以根 `DESIGN.md` 为 source visual truth，并用 `docs/design/tokens/*` 复核实际投影；不得回退到上游默认或历史品牌值。执行清单见 `.agents/skills/yss-design-system/references/design-qa-theme.md`。
+Codex `$design-qa` 的 Colors/tokens 与 Fonts/typography 对照必须以根 `DESIGN.md` 为 source visual truth，并用 `.template-spec/design/tokens/*` 复核实际投影；不得回退到上游默认或历史品牌值。执行清单见 `.agents/skills/yss-design-system/references/design-qa-theme.md`。
 原型 H1/H2 默认使用 `html-css-js`，以本地 Token CSS 保留 YSS 企业后台视觉语言；复杂交互影响评审结论时可按集成说明选用 `react-antd-prebuilt`。生产实现只在目标工程按 lockfile 核验组件 API；原型阶段不调用 `yss-ui`。已有项目中冻结的组件库原型及其事实证据保持只读；模板不再预置 Antdv Next fact pack，也不生成新的 Provider 事实包。
@@ -60,7 +60,7 @@ HTML 直接使用 DESIGN.md 当前默认尺寸与主题 CSS，不要求 ConfigPr
 ## Token 基线
-本文件不再抄写视觉 Token 的具体值。规范值只从根 `DESIGN.md` 读取，运行时名称和值只从 `docs/design/tokens/*` 派生快照读取；两者不一致时视为 drift，不在本文件中重新裁定。
+本文件不再抄写视觉 Token 的具体值。规范值只从根 `DESIGN.md` 读取，运行时名称和值只从 `.template-spec/design/tokens/*` 派生快照读取；两者不一致时视为 drift，不在本文件中重新裁定。
 ### 颜色角色映射
@@ -141,7 +141,7 @@ HTML 直接使用 DESIGN.md 当前默认尺寸与主题 CSS，不要求 ConfigPr
 | 表格 / 列表 | 容器 `0` 或 `spacing.sm` | 工具栏与表格 `spacing.xs` | 表格内部 cell padding 使用组件紧凑规格，不用页面 CSS 逐列覆盖 |
 | Modal / Drawer | `spacing.md` | 内容区块 `spacing.sm`；操作区 `spacing.xs` | 复杂多步流程不塞入 Modal，改用独立页面或 Drawer 分区 |
-紧凑模式的计算值以 `docs/design/tokens/tokens.compact.json` 为准，它来自 `docs/design/tokens/theme.json` 的 seed 叠加一次 compact algorithm。业务页面只消费计算后的语义层级，不复制外部样例中的 `.m-*` / `.p-*` utility class，也不再次缩放。
+紧凑模式的计算值以 `.template-spec/design/tokens/tokens.compact.json` 为准，它来自 `.template-spec/design/tokens/theme.json` 的 seed 叠加一次 compact algorithm。业务页面只消费计算后的语义层级，不复制外部样例中的 `.m-*` / `.p-*` utility class，也不再次缩放。
 Margin 使用规则：组件自身默认不声明外部 margin，兄弟元素之间优先由父级 `gap` 管理；只有文档流语义或无法使用布局容器时才使用 margin，并仍限定在 `spacing.*` 阶梯内。禁止用负 margin 修补布局。
@@ -164,7 +164,7 @@ Margin 使用规则：组件自身默认不声明外部 margin，兄弟元素之
 | `borderRadius` | 6 | 默认控件圆角 |
 | `borderRadiusLG` | 8 | Card、大容器 / 浮层 |
-保持“控件圆角小于或等于容器圆角”：控件使用 `rounded.sm/md`，Card 与普通容器使用 `rounded.lg`。更大的 panel 圆角属于局部产品扩展，不作为紧凑型默认值；确需使用时必须先登记规范角色，不能让同一页面任意混用。实现时以根 `DESIGN.md` 与 `docs/design/tokens/tokens.default.json` 为默认基线。
+保持“控件圆角小于或等于容器圆角”：控件使用 `rounded.sm/md`，Card 与普通容器使用 `rounded.lg`。更大的 panel 圆角属于局部产品扩展，不作为紧凑型默认值；确需使用时必须先登记规范角色，不能让同一页面任意混用。实现时以根 `DESIGN.md` 与 `.template-spec/design/tokens/tokens.default.json` 为默认基线。
 ### 动效
@@ -265,12 +265,12 @@ Margin 使用规则：组件自身默认不声明外部 margin，兄弟元素之
 如果前端使用 React + Ant Design：
-- 使用 `ConfigProvider` 注入 `docs/design/tokens/theme.json` 中的 theme 配置。
+- 使用 `ConfigProvider` 注入 `.template-spec/design/tokens/theme.json` 中的 theme 配置。
 - 默认采用 Data Quality 浅色与 32px 控件；仅显式紧凑模式使用 `compactAlgorithm`；暗色工作界面组合 `darkAlgorithm` 与 `compactAlgorithm`。seed 与计算结果分别从 `theme.json`、`tokens.compact.json` 读取。
 - 组件样式优先通过 Ant Design token、component token、CSS variables 或主题算法表达。
 - 消息、通知、Modal 静态方法应使用 `App`、hook API 或 context holder，避免主题上下文丢失。
-- 暗色模式使用 `darkAlgorithm` 或 `docs/design/tokens/variables.dark.css`，不要手工反转颜色。本轮只同步了暗色的字体栈和圆角 seed；完整暗色色板仍是历史算法结果，启用暗色前应再派生一次。
-- 紧凑模式默认使用 `compactAlgorithm` 或 `docs/design/tokens/tokens.compact.json`，不要逐组件压缩高度；选择紧凑模式的原型交付物按紧凑 token 验收实际 padding、gap、Card 圆角和控件高度。
+- 暗色模式使用 `darkAlgorithm` 或 `.template-spec/design/tokens/variables.dark.css`，不要手工反转颜色。本轮只同步了暗色的字体栈和圆角 seed；完整暗色色板仍是历史算法结果，启用暗色前应再派生一次。
+- 紧凑模式默认使用 `compactAlgorithm` 或 `.template-spec/design/tokens/tokens.compact.json`，不要逐组件压缩高度；选择紧凑模式的原型交付物按紧凑 token 验收实际 padding、gap、Card 圆角和控件高度。
 H1/H2 原型使用 HTML/CSS/JavaScript：
@@ -280,7 +280,7 @@ H1/H2 原型使用 HTML/CSS/JavaScript：
 如果前端不是 Ant Design：
-- 先把 `docs/design/tokens/tokens.default.json` 转为项目设计 token，再映射到目标 UI 库。
+- 先把 `.template-spec/design/tokens/tokens.default.json` 转为项目设计 token，再映射到目标 UI 库。
 - 保留组件语义和状态语义，不要只复制颜色。
 - 保持 `theme.json` 的基础 seed，并映射 `tokens.compact.json` 的计算结果；排版、间距和表面角色从根 `DESIGN.md` 读取。
 - 运行时动态换肤使用 `--primary-color` 等短名别名，或直接改 `--brand-*`。
@@ -300,9 +300,9 @@ H1/H2 原型使用 HTML/CSS/JavaScript：
 ## 后续落地 TODO
-- 将 `docs/design/tokens/theme.json` 作为 Data Quality 默认主题接入原型主题配置。
-- 将 `docs/design/tokens/variables.css` 中的 `--brand-*` 与运行时别名纳入项目 token 管理。
-- 如果项目启用暗色模式，用 `darkAlgorithm` 按新 seed 重派生 `docs/design/tokens/tokens.dark.json`，并补充截图验收。
+- 将 `.template-spec/design/tokens/theme.json` 作为 Data Quality 默认主题接入原型主题配置。
+- 将 `.template-spec/design/tokens/variables.css` 中的 `--brand-*` 与运行时别名纳入项目 token 管理。
+- 如果项目启用暗色模式，用 `darkAlgorithm` 按新 seed 重派生 `.template-spec/design/tokens/tokens.dark.json`，并补充截图验收。
 - 让 H1/H2 原型适配器默认接入项目 Token，并在浏览器证据中记录实际计算后的 padding、gap、Card 圆角和控件高度。
 ## HTML 原型补充基线

package/template/{docs/design/templates/interaction-spec-template.md → .template-spec/design/templates/examples/model-publishing-interaction.example.md} RENAMED Viewed

@@ -1,4 +1,6 @@
-# <功能名称> 交互说明模板
+> 示例：模型发布。仅展示填写方式，不构成真实需求、已批准规则或可复制的项目事实。
+# 模型发布：交互说明填写示例
 > 适用时机：Spec 初稿和产品总体设计 / 功能架构完成之后，Spec 校准 / API 影响分析 / 契约草案之前；仅用于有用户界面影响的功能。
@@ -9,7 +11,7 @@
 | Spec 初稿 | `docs/.scratch/<feature>/spec.md` | 原型评审后需要回填和校准 |
 | 产品总体设计 / 功能架构 | `docs/.scratch/<feature>/design/<feature>-product-overview-design.md` | 必需；缺失时先返回产品总体设计阶段 |
 | 领域术语 | `CONTEXT.md` | 核心名词、状态和业务规则 |
-| Plan | `docs/.scratch/<feature>/plan/<feature>-discovery.md` | 可选 |
+| Plan | `<实际 Plan 资产引用>` | 按当前项目范围填写 |
 | 原型阶段合同 / 视觉来源 | `yss-prototype-stage`；`source_visual.kind=design-system` 或 `visual-reference` | 默认 DESIGN.md 规范直出；独立视觉稿才条件使用 Product Design focused skill |
 | 原型 / 线框图 | `<链接或导出图片路径>` | Excalidraw / Figma / Penpot / tldraw / Axure / Markdown |
 | H1/H2 原型交付物 | `docs/.scratch/<feature>/design/prototypes/index.html` 与本地资源 | 低保真评审后按档位补齐；默认原生 HTML，复杂控件影响评审结论时选择 AntD 预构建；产出后须用户确认 |
@@ -80,7 +82,7 @@
 ## 5. 状态矩阵
-引用或复制 `docs/design/templates/state-matrix-template.md`。
+引用或复制 `.template-spec/design/templates/state-matrix-template.md`。
 ## 6. OpenAPI 反推清单

package/template/{docs/design/templates/state-matrix-template.md → .template-spec/design/templates/examples/model-publishing-state-matrix.example.md} RENAMED Viewed

@@ -1,4 +1,6 @@
-# <功能名称> 状态矩阵模板
+> 示例：模型发布。仅展示填写方式，不构成真实需求、已批准规则或可复制的项目事实。
+# 模型发布：状态矩阵填写示例
 > 适用时机：由 `yss-prototype-stage` 统一消费；规范直出与条件独立视觉稿使用同一状态矩阵，在 Spec 校准和 API 影响分析 / 契约草案之前补齐页面状态。

package/template/.template-spec/design/templates/interaction-spec-template.md ADDED Viewed

@@ -0,0 +1,61 @@
+# <功能名称> 交互说明
+> 适用时机：Spec 初稿和产品总体设计 / 功能架构完成之后；仅用于有用户界面影响的功能。填写示例见 `examples/model-publishing-interaction.example.md`，示例不构成需求。
+## 1. 输入与范围
+| 资产 | 当前引用 / 版本 | 用途或未决项 |
+|---|---|---|
+| Spec 初稿 | <可读引用> | 交互发现须回填 Spec |
+| 产品总体设计 / 功能架构 | <可读引用> | 页面与功能边界 |
+| Plan 决策 | <实际资产引用；不适用则说明> | 目标、非目标与已确认取舍 |
+| 领域词汇 | `CONTEXT.md` | 稳定术语 |
+| 视觉来源 | `DESIGN.md` 或已批准的独立视觉来源 | 原型档位选择依据 |
+| 已有原型或 API 草案 | <引用或不适用原因> | 仅用作当前阶段输入 |
+- 本次用户、任务与 UI 影响：<待填写>
+- 不在本次范围内的交互：<待填写>
+## 2. 页面地图
+引用总体设计的当前页面地图与边界；本节只细化交互入口、操作和后续流转。未变化的页面可引用上游对应行，当前阅读仍须能定位完整路径；发现边界、角色或目标变化时记录差异并回填 Spec / 总体设计，不重复定义另一份范围。
+| 页面 / 区域 | 入口与角色 | 用户目标 | 关键操作 | 下一步 |
+|---|---|---|---|---|
+| <待填写> | <待填写> | <待填写> | <待填写> | <待填写> |
+## 3. 主流程与恢复
+| 步骤 / 触发 | 用户操作 | 系统反馈 | 失败或异常 | 恢复路径 | Spec 规则引用 |
+|---|---|---|---|---|---|
+| <待填写> | <待填写> | <待填写> | <待填写> | <待填写> | <待填写> |
+## 4. 页面细节
+| 页面 / 区域 | 信息或字段 | 数据来源 | 可用条件 / 权限 | 校验与反馈 | 待确认项 |
+|---|---|---|---|---|---|
+| <待填写> | <待填写> | <待填写> | <待填写> | <待填写> | <待填写> |
+## 5. 状态与原型
+- 状态矩阵：<引用 `.template-spec/design/templates/state-matrix-template.md` 的当前实例；不适用则说明原因>。
+- 低保真评审：<证据引用或待完成>。
+- H1/H2 档位及触发理由：<待选择；不预填批准结果>。
+- 原型交付物与 schema v4 验证：<实际引用；产出前写待完成>。
+- 生产组件待验事项：<交给前端实现计划的清单；无则说明>。
+## 6. API 影响与 Spec 回填
+| 交互需求 / 原型发现 | API 或数据影响 | 需回填的 Spec 规则 / 验收 | 负责人 | 状态 |
+|---|---|---|---|---|
+| <待填写> | <待评估> | <待填写> | <待登记> | 待确认 |
+## 7. 验收与未决问题
+- 页面主流程、失败状态和恢复路径有可核验的交互说明，或记录不适用原因。
+- 字段、操作与权限条件均有来源；不能用示例或组件默认行为代替产品决定。
+- 原型档位、浏览器与 Design QA 证据按 `yss-prototype-stage` 的当前合同验收；此文档不批准原型或实现。
+| 问题 / 决定 | 当前选项与依据 | 负责人 | 解决时点 | 状态 |
+|---|---|---|---|---|
+| <待填写> | <待填写> | <待登记> | <待登记> | 待确认 |

package/template/{docs → .template-spec}/design/templates/product-overview-design-template.md RENAMED Viewed

@@ -8,7 +8,7 @@ owner: ai
 # <功能名称> 产品总体设计与功能架构
 > 适用时机：Spec 初稿之后、页面 / 原型 / 交互设计之前。
-> 本文用于明确功能域、模块边界、MVP 范围、页面清单、低保真原型、状态 / 权限影响、OpenAPI 反推点和 Spec 回填项；它是页面 / 原型 / 交互设计的上游输入，不替代 Spec、交互说明、契约草案 / OpenAPI Draft 或系统概要设计。
+> 本文用于明确功能域、模块边界、MVP 范围、页面或流程草图、状态 / 权限影响、OpenAPI 反推点和 Spec 回填项；它是正式低保真原型与交互设计的上游输入，不替代产品设计阶段的原型评审、Spec 或工程契约。
 ## 1. 输入资产
@@ -22,11 +22,11 @@ owner: ai
 ## 2. 设计目标
-- 目标用户：
-- 核心场景：
-- MVP 目标：
-- 非目标范围：
-- 成功标准：
+引用 Plan / Spec 中已确认的目标用户、核心场景、MVP、非目标和成功标准，写明章节或规则 ID。本节说明这些目标对功能边界与设计的约束；仅记录新增细化或差异，不重新批准上游范围。必要摘录绑定同一来源；引用不可读或标准未确认时列为开放问题。
+| 上游目标 / 规则引用 | 本设计承接的约束 | 本阶段新增细化 / 差异与处理 |
+|---|---|---|
+| <当前资产及章节 / ID> | <对模块、流程或验收的约束> | <细化；无差异则说明沿用> |
 ## 3. 用户主流程
@@ -68,9 +68,9 @@ owner: ai
 |------|----------|----------|----------|------------------|------|
 |  |  |  |  |  |  |
-## 8. 低保真原型 / 页面草图
+## 8. 页面结构 / 流程草图（条件适用）
-> 本节用于在产品总体设计阶段先验证页面结构、核心操作和跨页面流转，不展开到高保真视觉、组件实现或完整字段级交互；后续页面 / 原型 / 交互设计需基于本节继续细化。无 UI 功能仍保留本节，用流程 / 能力草图和“不适用原因”说明用户或系统如何完成任务。
+> 有 UI 影响时记录早期页面结构、核心操作和跨页面流转。正式 `artifact.low-fidelity-prototype` 由后续 `stage.product-design` 产出与评审。无 UI 影响时写明依据和不适用原因，按需要给出业务流程或能力草图，不生成空页面线框。
 ### 8.1 页面地图
@@ -78,7 +78,7 @@ owner: ai
 |-------------|------|----------|----------|--------|
 |  |  |  |  |  |
-### 8.2 低保真线框
+### 8.2 早期结构草图（有 UI 影响时填写）
 ```text
 页面名称：
@@ -90,7 +90,7 @@ owner: ai
 [反馈区：校验结果 / 错误提示 / 空态]
 ```
-### 8.3 原型评审关注点
+### 8.3 后续原型评审关注点（有 UI 影响时填写）
 | 页面 / 流程 | 需要验证的问题 | 关联 P0 需求 | 关联 API / 数据 / 权限影响 | 后续交互设计待细化 |
 |-------------|----------------|--------------|-----------------------------|--------------------|
@@ -115,7 +115,7 @@ owner: ai
 - [ ] 功能域、模块边界和优先级清楚。
 - [ ] 业务边界与协作检查已完成，或明确说明本次变更不影响业务责任边界。
 - [ ] 页面、API、数据、权限和审计影响已显式标注。
-- [ ] 低保真原型 / 页面草图已覆盖 P0 页面、主流程和关键异常路径，并能支撑后续交互设计。
+- [ ] 有 UI 影响时，早期页面草图覆盖 P0 页面、主流程和关键异常路径，并列出正式低保真原型待验证事项；无 UI 时记录不适用原因与必要的流程说明。
 - [ ] Spec 回填项已列出，并分清阻断项和非阻断项。
 - [ ] 风险影响、验证证据和责任人已记录。
 - [ ] 可进入页面 / 原型 / 交互设计，或明确阻断项。

package/template/{docs → .template-spec}/design/templates/prototype-evidence-template.yaml RENAMED Viewed

@@ -33,12 +33,12 @@ source_visual:
 design_baseline:
   canonical_design_ref: DESIGN.md
   canonical_design_digest: <sha256>
-  project_design_ref: docs/design/design.md
+  project_design_ref: .template-spec/design/design.md
   project_token_refs:
     # 默认 Data Quality 浅色；显式暗色 / 紧凑模式改为实际消费的对应快照，并同步摘要和视觉基线 cases[].theme。
-    - docs/design/tokens/theme.json
-    - docs/design/tokens/tokens.default.json
-    - docs/design/tokens/variables.css
+    - .template-spec/design/tokens/theme.json
+    - .template-spec/design/tokens/tokens.default.json
+    - .template-spec/design/tokens/variables.css
   project_token_baseline_digest: <sha256>
   project_override_reviewed: false
 visual_baseline:

package/template/{docs → .template-spec}/design/templates/prototype-review-checklist.md RENAMED Viewed

@@ -10,7 +10,7 @@
 | 交互说明 | `docs/.scratch/<feature>/design/<feature>-interaction-spec.md` |  |
 | 原型 / 线框图 | `<链接或导出图片路径>` |  |
 | 状态矩阵 | `docs/.scratch/<feature>/design/<feature>-state-matrix.md` |  |
-| 视觉规范与主题快照 | 根 `DESIGN.md`、`docs/design/design.md`、实际消费的 Token 快照 | 默认 Data Quality 浅色；显式暗色 / 紧凑模式注明选择依据 |
+| 视觉规范与主题快照 | 根 `DESIGN.md`、`.template-spec/design/design.md`、实际消费的 Token 快照 | 默认 Data Quality 浅色；显式暗色 / 紧凑模式注明选择依据 |
 | 原型阶段合同 / Product Design 路由记录 | `yss-prototype-stage`；规范直出或条件独立视觉稿路线 |  |
 | 原型验证清单 | `docs/.scratch/<feature>/verification/prototype-evidence.yaml` | 档位确定后补齐 schema v4 共同与档位证据，并引用 Visual Baseline Bundle v1 |
 | 现有 API 草案 | `docs/.scratch/<feature>/api/<feature>.yaml` | 可选 |

package/template/.template-spec/design/templates/state-matrix-template.md ADDED Viewed

@@ -0,0 +1,29 @@
+# <功能名称> 状态矩阵
+> 由 `yss-prototype-stage` 消费，在 Spec 校准及 API 影响分析前记录当前页面状态。填写示例见 `examples/model-publishing-state-matrix.example.md`；示例不构成需求。
+状态矩阵同时承担轻量状态机合同。实际可进入的每个状态须有触发、允许转换、guard、动作和退出路径；不另建第二份状态机资产。按真实影响覆盖 loading、empty、error、readonly、disabled、no-permission、conflict 等状态，未命中项写明原因。
+## 页面状态
+| 页面 / 组件 | 状态 | 触发条件 | 界面反馈 | API / 数据来源 | 验收点 / 规则引用 |
+|---|---|---|---|---|---|
+| <待填写> | <待填写> | <待填写> | <待填写> | <待填写> | <待填写> |
+## 状态转换与恢复
+| 当前状态 | 事件 | Guard | 下一状态 | 进入 / 退出动作 | 恢复或退出路径 |
+|---|---|---|---|---|---|
+| <待填写> | <待填写> | <待填写> | <待填写> | <待填写> | <待填写> |
+## 待确认的产品决定
+| 决定 | 方案与依据 | 负责人 | 解决时点 | 状态 |
+|---|---|---|---|---|
+| <待填写> | <待填写> | <待登记> | <待登记> | 待确认 |
+## OpenAPI 与 Spec 回填
+| 状态 / 转换 | 契约影响 | Spec 规则或验收回填 | 处理状态 |
+|---|---|---|---|
+| <待填写> | <待评估> | <待填写> | 待确认 |

package/template/.template-spec/design/tokens/.design-md-projection.json ADDED Viewed

@@ -0,0 +1,13 @@
+{
+  "schema_version": 1,
+  "source": "DESIGN.md",
+  "source_sha256": "e84a6c175840efe9663a2d0aba37f5635c053f47452bb146d1025d65665b1bec",
+  "files": {
+    ".template-spec/design/tokens/theme.json": "740f80c2c55763564ac5e1cf4159e0d5f0965548d53e0eb0de0ff380e74f0a93",
+    ".template-spec/design/tokens/tokens.default.json": "4e6446ee85195e3a75676a763cb8be2c625dc86b2b0676cbc8b45b2221135a71",
+    ".template-spec/design/tokens/tokens.dark.json": "826391c5dafaef4d924003052bcfa9b38943e589120b0ff740214a12c9981ae1",
+    ".template-spec/design/tokens/tokens.compact.json": "1a943c1354487addc67e399ededc122337d278a9ff61cb12d36a2f8202e26d9c",
+    ".template-spec/design/tokens/variables.css": "028c24f9e935f5c4b1392d131a4cd13482e6572a2ced4360ffa833aa3fbeaf66",
+    ".template-spec/design/tokens/variables.dark.css": "38132db701cd1e9793b6320baba20645a2cf577edc75b25aadb211f65bf05767"
+  }
+}

package/template/{docs → .template-spec}/engineering/backend-platforms.md RENAMED Viewed

@@ -25,7 +25,7 @@ Project Scaffold Contract v4 新增 `platform_configuration` v2，两个脚手
 配置可由 `platformBinding(profile, entry)` 机械构造；该函数把 Profile 中规范化的 `component_platform_line` 持久化到 v2 binding，并由 schema、解析器、架构身份摘要和 Slice 组件绑定摘要共同校验。组件平台线表示可消费的双平台源码索引，不承载 `maintenance`、`candidate` 或 `blocked` 生命周期；生命周期继续由 compatibility 与 capability 状态表达。当前 Boot 2 与 Boot 3 分别固定为 `boot2-java8`、`boot3-java17`。Boot 4 没有现有组件平台线，不生成可批准的 v2 `platform_configuration`，继续在选择阶段阻断。该函数不批准用户选择或开放支持。修改平台、YSS 坐标或依赖配方会使绑定失效；仅更新同配方证据不改变用户选择摘要。历史 Manifest 继续只读验证，不自动补字段或重写批准。仅继承架构不等于继承平台批准。
-`resolveBackendPlatform(binding, { root })` 在未显式传入 catalog 时读取该 `root` 下的 `docs/engineering/backend-platforms.json`；未传 `root` 时读取模板仓目录。这样 Slice freshness 与隔离 fixture 使用各自的目录事实，不会意外回退到模板工作区。
+`resolveBackendPlatform(binding, { root })` 在未显式传入 catalog 时读取该 `root` 下的 `.template-spec/engineering/backend-platforms.json`；未传 `root` 时读取模板仓目录。这样 Slice freshness 与隔离 fixture 使用各自的目录事实，不会意外回退到模板工作区。
 ## 组件能力绑定

package/template/{docs → .template-spec}/plan/entry-review.md RENAMED Viewed

@@ -2,11 +2,13 @@
 正式 Spec 起草之前必须通过 `node scripts/verify-plan-spec-entry <state.yaml>`；显式 `to-spec`、恢复、任务包派发和下一路由均不得绕过。Plan 不通过时可继续无依赖调研，不创建正式 Spec 草稿。此检查复用 `gate.plan-approved` 用户决定，不新增批准阶段，也不授权实现。
-检查 ID 与条件门禁取自 `docs/process/lifecycle-registry.yaml` 的 `stage.plan.spec_entry`。查询 Plan 或相关工作单元自动加载 `planning`、`grill_exit` 和全量检查，初始均为 `pending`。自动加载不代表勾选通过。
+可先用 `scripts/plan-spec-entry prepare --root <项目> --feature <id> --plan <Plan引用> --context-reconciliation <调和记录引用>` 将可读输入及当前摘要组织为待审候选 JSON，或用 `scripts/plan-spec-entry diff --root <项目> --review <审阅包引用>` 比较原依据与当前字节。两条命令只写标准输出；所有检查初始为 `pending`，影响判断为未知，候选不构成会签或批准。缺输入时返回结构化阻断原因。
+检查 ID 与条件门禁取自 `.template-spec/process/lifecycle-registry.yaml` 的 `stage.plan.spec_entry`。查询 Plan 或相关工作单元自动加载 `planning`、`grill_exit` 和全量检查，初始均为 `pending`。自动加载不代表勾选通过。
 ## 持久化合同
-入口状态包含 `feature_id`、`plan_review_ref`、`plan_user_decision_ref`。这三个字段同样用于任务包、checkpoint 和完成态 Workflow Execution Result；不从历史阶段、路径或默认值推断。
+入口状态包含 `feature_id`、`plan_review_ref`，并按用户决定协议提供 `plan_user_decision_ref` 或 `plan_continuation_ref`。这些字段同样用于任务包、checkpoint 和完成态 Workflow Execution Result；不从历史阶段、路径或默认值推断。两条证明路径均由现有用户决定校验器核验，不能混填或以延续记录伪造新回复。
 `plan_review_ref` 指向 YAML / JSON：
@@ -18,6 +20,8 @@
 - `impacts`：显式评估 `domain_strategy`（领域边界、词汇、协作或核心规则影响）和 `stage_decision`（需要稳定阶段决策合同）。证据和判断必须呈现给用户；缺值不解释为 false。
 - `internal_checks`：注册表 `check_impacts` 内部专业审查全部逐项记录。命中项须 `status: approved`、`approval_ref`、`subject_ref`、`approval_scope`、`evidence_refs`，会签记录及对应资产均加入 `basis`；未命中项须 `status: not-applicable`、`reason`、`evidence_refs`，并由用户确认影响面判断。阶段决策检查的上游依赖必须批准，不能用 N/A 跳过。
-先固定审阅包及依据，展示当前内容、范围、风险、延期、N/A 理由和下一动作，再取得真实用户回复。`plan_user_decision_ref` 采用 `docs/process/schemas/user-decision.schema.json`：边界为 `gate.plan-approved`，subject 为当前 `plan_review_ref`，scope 包含当前 `feature_id`。不得将旧“继续”、数字人会签或合成测试回复当作本次批准。
+先固定审阅包及依据，展示当前内容、范围、风险、延期、N/A 理由和下一动作，再取得真实用户回复。`plan_user_decision_ref` 采用 `.template-spec/process/schemas/user-decision.schema.json`：边界为 `gate.plan-approved`，subject 为当前 `plan_review_ref`，scope 包含当前 `feature_id`。不得将旧“继续”、数字人会签或合成测试回复当作本次批准。
+审阅包、注册表、Plan、词汇、依据或批准来源变化均要求重新校验；摘要漂移时先展示差异并按用户决定协议重验：排版、措辞或派生内容变化，经独立等价审查证明决定依据与授权范围未变，且原始决定和适用外部审批仍有效时，可用 `plan_continuation_ref` 延续；范围、关键规则、验收、契约承诺、授权或风险接受发生实质变化时重新取得决定。未知影响先补分析，不能视为等价。检查器保证结构、引用、摘要和回复绑定，不证明业务事实或身份来源绝对真实；主控仍须按证据核查影响面，不能为了放行而填 false 或空问题列表。
-审阅包、注册表、Plan、词汇、依据或批准来源变化均要求重新校验；摘要漂移时重新展示并取得当前确认。检查器保证结构、引用、摘要和回复绑定，不证明业务事实或身份来源绝对真实；主控仍须按证据核查影响面，不能为了放行而填 false 或空问题列表。
+批准延续使用 `yss-product-lifecycle/references/user-decisions.md` 的 `approved-scope-continuation-v1`：绑定当前审阅包、原始真实决定、实际差异与独立审查；禁止链式延续、修改旧回复或跳过检查。`scripts/plan-spec-entry prepare` 只起草候选，`diff` 只报告原始字节变化；两者均不判定等价或批准。

package/template/{docs → .template-spec}/plan/templates/competitive-analysis-template.md RENAMED Viewed

@@ -2,7 +2,7 @@
 > AI 辅助生成，人工审核补充。
 > 建议配套产物：`competitive-matrix-template.md` 用于横向功能矩阵，本模板用于深度分析和 Spec 前置输入。
-> 使用 `grill-with-docs` 时，请把稳定术语同步沉淀到 `CONTEXT.md`，只有出现难以回滚、非显而易见且存在真实取舍的决策时才新增 ADR。
+> 使用 `work-unit.plan-requirements` 时，请把稳定术语同步沉淀到 `CONTEXT.md`，只有出现难以回滚、非显而易见且存在真实取舍的决策时才新增 ADR。
 ## 0. 文档信息
@@ -250,7 +250,7 @@ flowchart LR
 ## 11. 建议下一步
 1. [补充调研 / 用户访谈 / 厂商验证]
-2. [进入 grill-with-docs 继续澄清的问题]
+2. [进入 work-unit.plan-requirements 继续澄清的问题]
 3. [生成 Spec]
 4. [判断是否需要 OpenAPI / 垂直切片 issue]

package/template/{docs → .template-spec}/plan/templates/plan-template.md RENAMED Viewed

@@ -7,7 +7,7 @@ owner: <负责人>
 # <功能名称> Plan（战略规划）
-> 生命周期身份：`stage.plan` / `artifact.plan-record`。按影响面填写，不制造未命中项的空产物。进入 Spec 的退出条件以 `docs/process/lifecycle-registry.yaml` 为准。
+> 生命周期身份：`stage.plan` / `artifact.plan-record`。按影响面填写，不制造未命中项的空产物。进入 Spec 的退出条件以 `.template-spec/process/lifecycle-registry.yaml` 为准。
 填写前读取[中文写作规范](../../process/document-writing.md)和 [Plan 对照](../../templates/examples/lifecycle-writing-examples.md#1-plan让业务问题和取舍可见)。先说明问题和本期取舍，假设与事实分开；以下各项按实际影响填写。

package/template/{docs → .template-spec}/process/contract-reading.md RENAMED Viewed

@@ -1,6 +1,6 @@
 # 合同阅读、准备与显式迁移
-本文件描述工具入口；阶段、批准和执行门禁仍由 `docs/process/lifecycle-registry.yaml` 及资产所有者定义。YAML 是权威文件，视图不能编辑、批准合同或授予执行权限。
+本文件描述工具入口；阶段、批准和执行门禁仍由 `.template-spec/process/lifecycle-registry.yaml` 及资产所有者定义。YAML 是权威文件，视图不能编辑、批准合同或授予执行权限。
 ```sh
 scripts/contract view <资产> --kind <类型> [--profile review|task|full] [--unit <ID>] [--json]
@@ -39,8 +39,32 @@ v2 的 `openapi` 是唯一 Draft 绑定，`draft_review` 只存 `ref/digest`，F
 ## 验证阶段与回退
+Slice v3 的任务聚焦布局可显式试用 `scripts/contract view <资产> --kind slice --profile task --unit <ID> --task-layout focused`。默认仍为 `legacy`，推广取决于受控对照结果。聚焦布局展示当前工作单元及其验证项关联的验收（包括 `required_for_all`），保留全局、专项和未知约束，并给出完整验收原文件引用。v2 保留原布局，不根据缺失引用裁剪。
+恢复入口 `scripts/lifecycle-status --checkpoint <ref> --task <task-package-ref>` 增量返回只读 `recovery`：任务引用、合同 task 视图命令、实际结果引用及恢复顺序。引用由调用方显式选择，不扫描目录猜任务；运行中、未知或版本不符不能重复派发。`not-checked` 和 `execution_authorization: not-evaluated` 保持原义。
 预检、准备、派发各自建立私有验证阶段。阶段绑定根目录、用途、切片、工作单元、只读状态；只在本次操作内共享输入和纯校验结果。原始输入不可变，返回给调用者的是独立副本。相同 schema、输入和格式选项复用；外部 `$ref` 未追踪的校验不享受结果复用。Python 引擎、同步 API 和技术设计 Node 边界保留。
 成功返回前复核所有登记原字节、目录枚举及不存在项。技术设计子进程自行验证批准，再返回依赖清单；父进程合并读取集合，读取矛盾、遗漏报告或异常均阻断。此清单不是批准上下文。品牌上下文不能序列化、跨仓或从只读升级；在阶段中生成的上下文结束后失效。调用者可传入 `AbortSignal`，已收到的撤回事件须中止当前操作；下一次边界始终重新读取当前批准和回复。未接入读取追踪的消费者保留原检查，不共享结果。
 P1 可回用原 `slice-contract` 阅读入口；P2 可回退阶段调用与本次改动的读取适配，恢复完整重复检查；P3 可停止创建 v2，但已生成 v2 的读取能力必须保留。回退后重新验证当前来源和批准，不恢复历史通过状态。
+## 默认派发与审阅材料
+提供该查询入口的聚合与战略模板中，派发首先用 `scripts/query-lifecycle-context` 一次组合 mode、stage、work-unit 与必要合同子树（`--mode`、`--stage`、`--work-unit`、`--include`）。结果 `sources.lifecycle_registry.sha256` 绑定原始注册表字节，`context_sha256` 绑定规范化查询、实际返回内容及来源；旧 `semantic_sha256` 只绑定稳定 ID 语义。旧结果缺少新增绑定时重新查询，不视作可复用。身份、执行范围和查询来源在同一 `validation-phase` 内读取，返回前变化则失败。
+专职交付 Profile 的阶段与 mode 继续由其现有 harness-profile 和主控入口解析，不假定未分发的查询命令存在。实现者默认读取指定 `--unit` 的 `task` 视图，审阅者默认读取 `review`；不要先整读 YAML 再重复生成相同视图。身份、版本、写边界、验收、停止条件、风险与未知约束均须保留，需要追溯时展开 `full`。一次执行边界内可复用未变来源；恢复、交接、实现、合并及发布重新核验。Context Plan 的原始 v2 字段为 `common.context_plan`，原始 v3 为 `scope.context_plan`；`common.context_plan` 在 v3 运行时只是归一化别名，不是修改原 YAML 的位置。
+```sh
+scripts/contract prepare-review <前资产> <后资产> --kind <类型> [--unit <ID>] [--decision <原决定.yaml>] --json
+```
+输出来源字节绑定、差异、完整约束、原决定与缺口及恢复动作。`approval_reusable: false`、`execution_allowed: false` 固定不授予批准或执行权；语义等价、风险接受、原回复真实性和批准延续由原审查及决定验证器处理。缺少原决定标记未提供，不能据此沿用批准。
+## 当前前端交互证据
+模板正式研究的路由、实际验证及收尾见 [研究收尾协议](research-completion.md)。
+前端 verification schema v2 保留读取历史交互文字；正式完成校验要求 `implementation_plan: {ref, digest}` 绑定当前批准计划，`interaction_results` 使用 `{case_id, state, result, evidence_ref, evidence_digest}`，覆盖计划全部 state_cases 和选定 case_id。只有 `result: pass` 可继续。console、实现截图、视觉差异与实际命令日志均须绑定当前字节摘要，命令必须覆盖计划中的 pnpm_commands。
+历史文字报告返回 `legacy-interaction-binding-missing`；先重验计划与批准，再真实执行交互、console、截图及适用命令并另存新报告，不给旧报告补造通过记录。摘要校验不证明交互语义，实际浏览器轨迹和独立前端审查仍按既有边界执行。

package/template/{docs → .template-spec}/process/lifecycle-artifact-map.md RENAMED Viewed

@@ -1,9 +1,9 @@
 # YSS 生命周期产物与门禁地图
-本文是模板仓库与模板实例共享的生命周期派生阅读视图。结构化事实源是 `docs/process/lifecycle-registry.yaml`；本文解释主阶段、条件门禁、必须持久化的产物和退出标准。具体项目只有在触发条件命中时才执行对应门禁。
+本文是模板仓库与模板实例共享的生命周期派生阅读视图。结构化事实源是 `.template-spec/process/lifecycle-registry.yaml`；本文解释主阶段、条件门禁、必须持久化的产物和退出标准。具体项目只有在触发条件命中时才执行对应门禁。
 <!-- lifecycle-registry:structure:start -->
-> 此结构区由 `docs/process/lifecycle-registry.yaml` 生成。当前为 `active` 模式：正式门禁、内部检查和派生文档共同消费此事实源。
+> 此结构区由 `.template-spec/process/lifecycle-registry.yaml` 生成。当前为 `active` 模式：正式门禁、内部检查和派生文档共同消费此事实源。
 ## 1. 主阶段
@@ -70,8 +70,8 @@
 | `artifact.low-fidelity-prototype` | 低保真原型 | `stage.product-design` | 命中产品设计影响。 |
 | `artifact.state-matrix` | 状态矩阵 | `stage.product-design` | 存在状态流转、异常或恢复。 |
 | `artifact.prototype-deliverable` | 原型交付物 | `stage.product-design` | 低保真评审后需要 H1 视觉或 H2 流程校准。 |
-| `artifact.prototype-review` | 原型评审记录 | `stage.product-design` | 命中 gate.prototype-reviewed。 |
-| `artifact.prototype-confirmation` | 原型确认记录 | `stage.product-design` | 命中 gate.user-confirmation。 |
+| `artifact.prototype-review-v2` | 原型评审记录 | `stage.product-design` | 命中 check.prototype-reviewed。 |
+| `artifact.prototype-confirmation-v2` | 原型确认记录 | `stage.product-design` | 命中 gate.product-design-approved。 |
 | `artifact.openapi-draft` | OpenAPI Draft | `stage.system-data-engineering` | 有 API 影响。 |
 | `artifact.openapi-freeze-record` | OpenAPI Freeze 记录 | `stage.system-data-engineering` | API 进入实现。 |
 | `artifact.data-architecture` | 数据架构 | `stage.system-data-engineering` | 数据模型、存储或一致性变化。 |
@@ -107,7 +107,7 @@
 | `evidence.antd-cli-validation` | Ant Design CLI 校验证据 | 设计语言、组件、demo、token、semantic 与 lint 的实际 CLI/目标版本和可读输出引用。 |
 | `evidence.browser-prototype-verification` | 浏览器原型验证证据 | 高保真原型的非空渲染、主流程、异常状态、视口和控制台验证记录。 |
 | `evidence.prototype-profile-decision` | 原型档位选择证据 | 基于低保真评审后的风险触发、决定目标、H1/H2 计算结果以及人工升降级依据。 |
-| `evidence.prototype-deliverable-verification` | 原型交付物验证证据 | schema v3 共同证据与所选档位的浏览器、Design QA、无障碍、组件事实或真实组件合同验证结果。 |
+| `evidence.prototype-deliverable-verification` | 原型交付物验证证据 | 新原型证据采用 schema v4，包含共同证据、Visual Baseline Bundle、浏览器、Design QA、无障碍及档位验证结果；历史 v3 仅供只读兼容。 |
 | `evidence.prototype-confirmation` | 原型用户确认记录 | 高保真原型、验证清单和进入下游阶段范围的人工确认结论。 |
 | `evidence.openapi-draft-review` | OpenAPI Draft 审查记录 | P0、错误、分页、幂等和契约测试审查记录。 |
 | `evidence.contract-approval` | Slice 合同批准记录 | 生命周期编排器批准且已持久化的当前版本合同引用。 |