create-yss-spec 3.5.2 → 3.5.4

package/template/.template-spec/design/templates/examples/model-publishing-interaction.example.md

@@ -14,7 +14,7 @@
 | 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 预构建；产出后须用户确认 |
+| H1/H2 原型交付物 | `docs/.scratch/<feature>/design/prototypes/index.html` 与本地资源 | 低保真评审后按档位补齐；高保真主要使用 shadcn/ui 预构建，轻量局部修改可用原生 HTML；产出后须用户确认 |
 | 原型验证清单 | `docs/.scratch/<feature>/verification/prototype-evidence.yaml` | 记录 schema v4 档位、浏览器、统一 Design QA、Visual Baseline case、条件组件证据和阻塞项 |
 | 现有 API 草案 | `docs/.scratch/<feature>/api/<feature>.yaml` | 可选；通常应先完成产品设计和 Spec 校准 |
 
@@ -108,7 +108,7 @@
 - 每个表格列、筛选条件、表单字段、抽屉、弹窗和按钮都有数据来源或契约反推说明。
 - 设计可以拆成独立可演示的垂直切片。
 - 低保真评审通过后，记录档位触发与待确认决定；H1 覆盖视觉和少量交互，H2 覆盖主流程/关键异常。
-- H2 仅在复杂交互影响评审结论且选用 `react-antd-prebuilt` 时，记录精确组件版本、选择理由与预构建来源；H1 不创建组件库证据。任何原型档位都不得调用 `yss-ui` 或声明已验证真实生产组件。
+- H2 采用 `vue-shadcn-prebuilt` 时，记录固定组件源码 revision、依赖锁和预构建来源；H1 不创建组件库证据。任何原型档位都不得调用 `yss-ui` 或声明已验证真实生产组件。
 
 ## 9. 决策与未决问题
 

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

@@ -14,6 +14,8 @@
 | 已有原型或 API 草案 | <引用或不适用原因> | 仅用作当前阶段输入 |
 
 - 本次用户、任务与 UI 影响：<待填写>
+- 保持项 / 可调整项：<引用已有页面模式；仅列本轮允许变化>
+- 适用 Token / 状态引用：<引用项目设计规范和已有状态，不复制另一套定义>
 - 不在本次范围内的交互：<待填写>
 
 ## 2. 页面地图
@@ -36,6 +38,28 @@
 |---|---|---|---|---|---|
 | <待填写> | <待填写> | <待填写> | <待填写> | <待填写> | <待填写> |
 
+### 内容规划与动作结果
+
+先列内容，再分配页面区域；同一字段的来源、权限和校验引用上表，不重复维护。
+
+| 内容 / 上表字段引用 | 优先级及用户任务依据 | 长度 / 空值变化 | 所在区域 | actionKey / 可见结果 / 状态引用 |
+|---|---|---|---|---|
+| <实际内容引用> | <主要 / 辅助及依据> | <代表值、长中文或空值> | <区域> | <动作与结果；纯展示说明不适用> |
+
+### 条件方案比较
+
+已有规范与页面模式足够时，记录不适用原因，不填空候选。信息架构/交互比较先于低保真评审；高保真比较只解决尚未确定的视觉方向。
+
+- 要回答的问题、共同输入、保持项及保真度：<当前引用>。
+- 事前比较标准：<Spec 硬约束，以及可权衡项；不得新增业务规则或事后改标准>。
+
+| 候选及入口 | 差异轴 / 待验证假设 | 硬约束结果与观察 | 适用条件与代价 |
+|---|---|---|---|
+| <候选引用> | <步骤 / 粒度 / 分工 / 入口，或视觉层级> | <可定位证据> | <取舍> |
+
+- 选择记录：<用户决定引用；未取得则待确认>。
+- 选择代价、落选理由与重新考虑条件：<依据>。
+
 ## 5. 状态与原型
 
 - 状态矩阵：<引用 `.template-spec/design/templates/state-matrix-template.md` 的当前实例；不适用则说明原因>。

package/template/.template-spec/design/templates/prototype-evidence-template.yaml

@@ -35,7 +35,7 @@ design_baseline:
   canonical_design_digest: <sha256>
   project_design_ref: .template-spec/design/design.md
   project_token_refs:
-    # 默认 Data Quality 浅色；显式暗色 / 紧凑模式改为实际消费的对应快照，并同步摘要和视觉基线 cases[].theme。
+    # 原型默认浅色 compact 使用 DESIGN 命名变体，不切换为生产 tokens.compact.json；登记实际 CSS、密度与摘要。历史暗色快照未验证。
     - .template-spec/design/tokens/theme.json
     - .template-spec/design/tokens/tokens.default.json
     - .template-spec/design/tokens/variables.css
@@ -69,6 +69,8 @@ browser_delivery:
   console_result: pending
   console_ref: <path-to-console-output-or-none>
 design_qa:
+  # 同一 report_ref 内记录 320 CSS px 重排、实际 200% 缩放、目标区域/焦点遮挡、读屏版本与未执行项。
+  # 验证运行 report.json 经该报告引用；首次截图待审，自动扫描/模拟观察不替代用户研究。
   mode: design-contract # visual-reference 对应 visual-comparison
   report_ref: docs/.scratch/<feature>/verification/design-qa.md
   result: pending
@@ -80,7 +82,7 @@ design_qa:
     accessibility: pending
     cross_platform: pending
 profile_evidence:
-  # H1 只保留 visual_review；不得包含 package/lockfile/AntD 字段。
+  # H1 只保留 visual_review；不得包含 package/lockfile/组件来源 字段。
   # visual_review:
   #   runtime_build_required: false
   #   key_interactions_result: pending
@@ -91,7 +93,7 @@ profile_evidence:
   #   reduced_motion: {applicable: false, result: not-applicable, evidence_ref: not-applicable}
   flow_review:
     implementation:
-      framework: html-css-js
+      framework: vue-shadcn-prebuilt
       runtime_build_required: false
     scenario_replay_ref: <case-id-and-data-scenario-action-evidence>
     scenario_reset_result: pending
@@ -108,8 +110,19 @@ profile_evidence:
       result: pending
       evidence_ref: <snapshot-result-ref>
     prototype_library_facts:
-      applicable: false
-      component_basis: html-css-js
+      applicable: true
+      component_basis: vue-shadcn-prebuilt
+      source: source-snapshot
+      library_package: shadcn-vue
+      registry_revision: <40-char-upstream-revision>
+      manifest_ref: <registry-manifest-ref>
+      manifest_digest: <registry-manifest-digest>
+      build_provenance_ref: <build-provenance-ref>
+      components_covered: [<actual-components>]
+      canonical_design_digest: <same-as-design-baseline>
+      project_token_baseline_digest: <same-as-design-baseline>
+      new_api_uncertainty: false
+      # 原生轻量路线改为 applicable: false / component_basis: html-css-js，删除其余来源字段。
 implementation_handoff:
   prototype_code_reusable: false
   production_component_assumptions:

package/template/.template-spec/design/templates/prototype-review-checklist.md

@@ -68,3 +68,11 @@
 下一步：
 - yss-prototype-stage 计算档位并进入对应适配器 / 回到产品设计补齐状态与风险 / 进入原型交付物构建
 ```
+
+## 条件比较与内容复核
+
+- 必需内容能定位到区域，优先级有用户任务依据；检查长中文、空值和主动作结果。来源/权限/actionKey 仍引用交互说明及状态矩阵。
+- 信息架构或交互不确定时，候选比较在本次评审之前完成：同输入、同保真、实质差异轴、事前标准、选择代价与落选理由均可定位。未命中时核验不适用理由。
+- 分别记录行为缺陷、视觉观察和非阻断偏好；后续视觉候选改变行为时重审受影响部分，不自动沿用结论。
+
+组件组合检查按 `prototype-review/references/component-qa.md` 并入现有六轴 QA：字段错误关联、分页与选择、浮层焦点返回、InputGroup 内层样式及实际目标尺寸，不新增独立门禁。

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

@@ -1,13 +1,13 @@
 {
   "schema_version": 1,
   "source": "DESIGN.md",
-  "source_sha256": "e84a6c175840efe9663a2d0aba37f5635c053f47452bb146d1025d65665b1bec",
+  "source_sha256": "5c1a896e34b401a5948be490562dca5329c9a54f213fc91f3b974cac62042776",
   "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.css": "27d99eb028db32d185372db8c780f7899fb58d35bfaa89334c9df0598a842b6d",
     ".template-spec/design/tokens/variables.dark.css": "38132db701cd1e9793b6320baba20645a2cf577edc75b25aadb211f65bf05767"
   }
 }

package/template/.template-spec/design/tokens/variables.css

@@ -1,4 +1,166 @@
 :root {
+  --yss-components-workspace-detail-background-color: #ffffff;
+  --yss-components-workspace-detail-width: 384px;
+  --yss-components-workspace-tabs-background-color: #ffffff;
+  --yss-components-workspace-tabs-height: 32px;
+  --yss-components-workspace-sidebar-collapsed-width: 64px;
+  --yss-components-workspace-sidebar-background-color: #ffffff;
+  --yss-components-workspace-sidebar-width: 240px;
+  --yss-components-workspace-header-background-color: #ffffff;
+  --yss-components-workspace-header-height: 48px;
+  --yss-components-card-compact-padding: 16px;
+  --yss-components-card-compact-rounded: 8px;
+  --yss-components-card-compact-text-color: rgba(0, 0, 0, 0.88);
+  --yss-components-card-compact-background-color: #ffffff;
+  --yss-components-button-large-height: 40px;
+  --yss-components-button-small-height: 24px;
+  --yss-components-button-compact-height: 28px;
+  --yss-components-card-default-padding: 20px;
+  --yss-components-card-default-rounded: 8px;
+  --yss-components-card-default-text-color: rgba(0, 0, 0, 0.88);
+  --yss-components-card-default-background-color: #ffffff;
+  --yss-components-secondary-copy-text-color: rgba(0, 0, 0, 0.65);
+  --yss-components-badge-error-solid-padding: 4px 8px;
+  --yss-components-badge-error-solid-rounded: 4px;
+  --yss-components-badge-error-solid-text-color: #000000;
+  --yss-components-badge-error-solid-background-color: #f5222d;
+  --yss-components-badge-warning-solid-padding: 4px 8px;
+  --yss-components-badge-warning-solid-rounded: 4px;
+  --yss-components-badge-warning-solid-text-color: #000000;
+  --yss-components-badge-warning-solid-background-color: #faad14;
+  --yss-components-badge-success-solid-padding: 4px 8px;
+  --yss-components-badge-success-solid-rounded: 4px;
+  --yss-components-badge-success-solid-text-color: #000000;
+  --yss-components-badge-success-solid-background-color: #52c41a;
+  --yss-components-badge-processing-solid-padding: 4px 8px;
+  --yss-components-badge-processing-solid-rounded: 4px;
+  --yss-components-badge-processing-solid-text-color: #000000;
+  --yss-components-badge-processing-solid-background-color: #3371ff;
+  --yss-components-alert-info-padding: 8px 12px;
+  --yss-components-alert-info-rounded: 4px;
+  --yss-components-alert-info-text-color: rgba(0, 0, 0, 0.88);
+  --yss-components-alert-info-background-color: #e6f4ff;
+  --yss-components-alert-error-padding: 8px 12px;
+  --yss-components-alert-error-rounded: 4px;
+  --yss-components-alert-error-text-color: rgba(0, 0, 0, 0.88);
+  --yss-components-alert-error-background-color: #fff2f0;
+  --yss-components-alert-warning-padding: 8px 12px;
+  --yss-components-alert-warning-rounded: 4px;
+  --yss-components-alert-warning-text-color: rgba(0, 0, 0, 0.88);
+  --yss-components-alert-warning-background-color: #fffbe6;
+  --yss-components-alert-success-padding: 8px 12px;
+  --yss-components-alert-success-rounded: 4px;
+  --yss-components-alert-success-text-color: rgba(0, 0, 0, 0.88);
+  --yss-components-alert-success-background-color: #f6ffed;
+  --yss-components-page-shell-padding: 16px;
+  --yss-components-page-shell-text-color: rgba(0, 0, 0, 0.88);
+  --yss-components-page-shell-background-color: #f0f2f5;
+  --yss-components-button-primary-active-height: 32px;
+  --yss-components-button-primary-active-padding: 4px 12px;
+  --yss-components-button-primary-active-rounded: 6px;
+  --yss-components-button-primary-active-text-color: #ffffff;
+  --yss-components-button-primary-active-background-color: #0958d9;
+  --yss-components-modal-default-padding: 16px;
+  --yss-components-modal-default-rounded: 8px;
+  --yss-components-modal-default-text-color: rgba(0, 0, 0, 0.88);
+  --yss-components-modal-default-background-color: #ffffff;
+  --yss-components-table-row-selected-padding: 8px 12px;
+  --yss-components-table-row-selected-text-color: rgba(0, 0, 0, 0.88);
+  --yss-components-table-row-selected-background-color: #e6f4ff;
+  --yss-components-table-header-padding: 8px 12px;
+  --yss-components-table-header-text-color: rgba(0, 0, 0, 0.88);
+  --yss-components-table-header-background-color: #fafafa;
+  --yss-components-input-error-height: 32px;
+  --yss-components-input-error-padding: 4px 8px;
+  --yss-components-input-error-rounded: 6px;
+  --yss-components-input-error-text-color: rgba(0, 0, 0, 0.88);
+  --yss-components-input-error-background-color: #ffffff;
+  --yss-components-input-default-height: 32px;
+  --yss-components-input-default-padding: 4px 8px;
+  --yss-components-input-default-rounded: 6px;
+  --yss-components-input-default-text-color: rgba(0, 0, 0, 0.88);
+  --yss-components-input-default-background-color: #ffffff;
+  --yss-components-button-default-height: 32px;
+  --yss-components-button-default-padding: 4px 12px;
+  --yss-components-button-default-rounded: 6px;
+  --yss-components-button-default-text-color: rgba(0, 0, 0, 0.88);
+  --yss-components-button-default-background-color: #ffffff;
+  --yss-components-button-primary-disabled-height: 32px;
+  --yss-components-button-primary-disabled-padding: 4px 12px;
+  --yss-components-button-primary-disabled-rounded: 6px;
+  --yss-components-button-primary-disabled-text-color: rgba(0, 0, 0, 0.45);
+  --yss-components-button-primary-disabled-background-color: #f0f0f0;
+  --yss-components-button-primary-hover-height: 32px;
+  --yss-components-button-primary-hover-padding: 4px 12px;
+  --yss-components-button-primary-hover-rounded: 6px;
+  --yss-components-button-primary-hover-text-color: #ffffff;
+  --yss-components-button-primary-hover-background-color: #2f68eb;
+  --yss-components-button-primary-height: 32px;
+  --yss-components-button-primary-padding: 4px 12px;
+  --yss-components-button-primary-rounded: 6px;
+  --yss-components-button-primary-text-color: #ffffff;
+  --yss-components-button-primary-background-color: #245bdb;
+  --yss-components-separator-height: 1px;
+  --yss-components-separator-background-color: #d9d9d9;
+  --yss-spacing-xxl: 48px;
+  --yss-spacing-xl: 32px;
+  --yss-spacing-lg: 24px;
+  --yss-spacing-card: 20px;
+  --yss-spacing-md: 16px;
+  --yss-spacing-sm: 12px;
+  --yss-spacing-xs: 8px;
+  --yss-spacing-xxs: 4px;
+  --yss-rounded-pill: 9999px;
+  --yss-rounded-lg: 8px;
+  --yss-rounded-md: 6px;
+  --yss-rounded-sm: 4px;
+  --yss-rounded-none: 0px;
+  --yss-typography-button-line-height: 1.571;
+  --yss-typography-button-font-weight: 600;
+  --yss-typography-button-font-size: 14px;
+  --yss-typography-button-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif;
+  --yss-typography-caption-line-height: 1.571;
+  --yss-typography-caption-font-weight: 400;
+  --yss-typography-caption-font-size: 12px;
+  --yss-typography-caption-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif;
+  --yss-typography-heading-md-line-height: 1.333;
+  --yss-typography-heading-md-font-weight: 600;
+  --yss-typography-heading-md-font-size: 18px;
+  --yss-typography-heading-md-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif;
+  --yss-typography-heading-lg-line-height: 1.333;
+  --yss-typography-heading-lg-font-weight: 600;
+  --yss-typography-heading-lg-font-size: 24px;
+  --yss-typography-heading-lg-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif;
+  --yss-typography-body-strong-line-height: 1.571;
+  --yss-typography-body-strong-font-weight: 600;
+  --yss-typography-body-strong-font-size: 14px;
+  --yss-typography-body-strong-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif;
+  --yss-typography-body-line-height: 1.571;
+  --yss-typography-body-font-weight: 400;
+  --yss-typography-body-font-size: 14px;
+  --yss-typography-body-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif;
+  --yss-colors-info-bg: #e6f4ff;
+  --yss-colors-error-bg: #fff2f0;
+  --yss-colors-error: #f5222d;
+  --yss-colors-warning-bg: #fffbe6;
+  --yss-colors-warning: #faad14;
+  --yss-colors-success-bg: #f6ffed;
+  --yss-colors-success: #52c41a;
+  --yss-colors-border-secondary: #f0f0f0;
+  --yss-colors-border: #d9d9d9;
+  --yss-colors-surface-subtle: #fafafa;
+  --yss-colors-surface-elevated: #ffffff;
+  --yss-colors-surface: #ffffff;
+  --yss-colors-canvas-layout: #f0f2f5;
+  --yss-colors-text-tertiary: rgba(0, 0, 0, 0.45);
+  --yss-colors-text-secondary: rgba(0, 0, 0, 0.65);
+  --yss-colors-text: rgba(0, 0, 0, 0.88);
+  --yss-colors-on-primary: #ffffff;
+  --yss-colors-primary-bg: #e6f4ff;
+  --yss-colors-primary-active: #0958d9;
+  --yss-colors-primary-control-hover: #2f68eb;
+  --yss-colors-primary-control: #245bdb;
+  --yss-colors-primary: #3371ff;
   --yss-card-padding: 20px;
   --yss-control-height: 32px;
   --yss-color-primary-control: #245bdb;

package/template/.template-spec/plan/templates/competitive-analysis-template.md

@@ -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/.template-spec/plan/templates/plan-template.md

@@ -1,4 +1,5 @@
 ---
+content_profile: plan-spec-v1
 pipeline: <feature-id>
 stage: plan
 status: draft
@@ -20,6 +21,20 @@ owner: <负责人>
 - 期望结果、成功标准及验证方式：
 - 约束、假设及事实证据：
 
+### 成功标准
+
+命中方案决策包时，把指标定义、基线或未知原因、目标及确认状态、观测窗口、数据来源、验证方式和补齐动作写入现有 `success_criteria[].statement`；本 Plan 仅在下表引用其稳定 ID。诊断读取 statement 原文，完整性由人工审阅，不扩展 YAML schema。未命中该合同时采用下方轻量表，两种形式按实际情况选用。
+
+| ID | 权威引用 |
+|---|---|
+| success-criterion.<稳定标识> | <项目根相对路径> :: id:success-criterion.<稳定标识> |
+
+轻量表（仅未命中方案决策包时填写）：
+
+| ID | 指标定义 | 基线或未知原因 | 目标 | 确认状态 | 观测窗口 | 数据来源 | 验证方式 | 未决项 |
+|---|---|---|---|---|---|---|---|---|
+| SC-001 | <填写> | <填写> | <填写或未知> | 候选 / 已确认 | <填写> | <资产路径> :: heading:<准确章节名> | <填写> | Q-001 / 无 |
+
 ## 2. 输入与复用依据
 
 | 资产 / 证据引用 | 版本 | 本次仍有效的依据 | 需要重新探索的部分 |
@@ -40,6 +55,13 @@ owner: <负责人>
 | 能力 / 范围 | MVP / 非目标 | 优先级及依据 | 成功信号 |
 |---|---|---|---|
 
+### 关键取舍
+
+影响 MVP、业务边界或难以逆转的决定，记录真实候选、选择理由、主要代价和重新考虑条件；不凑固定数量。已有决策包时复用 `decision.*` 引用，仅在未命中时直接记录下表。
+
+| 决定 / 权威引用 | 真实候选 | 本期选择及理由 | 主要代价 | 重新考虑条件 |
+|---|---|---|---|---|
+
 ## 5. 下游影响与交接
 
 | 下游阶段 / 接收方 | 输入引用 | 责任人 | 待细化内容 | 命中门禁 |
@@ -49,7 +71,7 @@ owner: <负责人>
 
 ## 6. 未决项
 
-| 问题 | 是否影响业务边界 / 关键规则 / MVP | 判断依据 | 责任人 | 解决时点 | 接收方 / 解决证据 |
+| ID | 问题 | 是否影响业务边界 / 关键规则 / MVP | 判断依据 | 责任人 | 解决时点 | 接收方 / 解决证据 |
 |---|---|---|---|---|---|
 
 ## 7. 退出核查与用户决定
@@ -60,3 +82,5 @@ owner: <负责人>
 - 当前资产版本、确认范围和原始用户决定引用：
 - 结论：ready-for-human / blocked / 已满足进入 Spec 的条件（附证据）。
 - 下一工作单元：
+
+表达约定与只读诊断见 [Plan / Spec 内容诊断](../../process/plan-spec-quality.md)。`content_profile` 可选，仅声明创作格式；检查结果不改变既有门禁或批准。

package/template/.template-spec/process/business-tickets.md

@@ -0,0 +1,48 @@
+# Spec 业务拆分与实现 Slice 衔接
+
+结构化阶段、产物和工作单元以 `lifecycle-registry.yaml` 为准。本协议不新增主阶段、Skill 或常规人工批准节点。
+
+## 流程与职责
+
+Spec 综合同时起草业务 Ticket；完成条件是可读取的集合和 FR/AC 覆盖。Design 按页面流、状态、失败与恢复路径校准原 Ticket，保持稳定 ID。无产品设计影响时记录不适用依据并进入业务正式化，不生成空原型。尚未批准、尚未冻结、缺工程是待满足前置，不能写为不适用。
+
+业务正式化消费当前 Spec、适用的产品设计批准和独立专业审查。语义不变按现有授权延续协议核验；范围、规则、验收或风险实质变化交回原决定边界。全生命周期随后进入技术分析；本地已确认资产直接消费，无需导出再导入自己。独立 Design profile 到战略交接结束。
+
+研发可以在技术分析期间形成实现 Slice 草案。正式实现 Slice 仍需当前工程契约、实现仓库准备、Slice 合同批准和完整就绪检查。业务票只能为 `draft` 或 `ready-for-human`，不能授予实现权限。业务票与阶段工作项即使移动到 `issues/` 仍不能作为实现票。
+
+## 文件合同
+
+功能包中每票一份 `business-tickets/BT-<id>.md`，集合为 `business-ticket-set.yaml`；实现票保留 `issues/`。使用共享 business-ticket、business-ticket-set、business-ticket-review 模板及 `schemas/business-tickets-v1.schema.json`。集合只保存引用、版本、原字节 SHA-256 和覆盖处置；Spec、map、父 Ticket、checkpoint 均引用同一集合。先固定 Spec 内容再计算其摘要；Spec 只写集合路径，不能嵌入集合摘要造成循环。
+
+业务票按用户行为与可验收结果划分，不机械地每条 FR 一票，也不按 Controller、Service、Repository 分票。每票关联原始 FR/NFR、AC 和 Spec 版本/摘要。适用规则、场景、设计放入 source_refs，包含 ref/version/digest 以及精确 locator 和 locator_kind（id 或 heading）；不适用需在正文说明并由专业审查判定。版本是作者登记的稳定版本，digest 校验实际字节，二者不能互相替代。
+
+草案可有具名未决项，但不得静默漏掉需求。暂不能分票的需求在 coverage_deferred 记录 reason、risk、owner、target_version、followup_ticket_ref、verification_plan；正式化还需绑定已有有效决定，不补造历史批准。专业审查检查业务粒度、行为完整性、语义保真和延期授权；校验器仅证明结构、引用与摘要，不用文本相似度判断业务正确性。
+
+```sh
+node scripts/verify-business-tickets docs/.scratch/<feature>/business-ticket-set.yaml --root . --mode draft --json
+node scripts/verify-business-tickets docs/.scratch/<feature>/business-ticket-set.yaml --root . --mode formal --json
+```
+
+命令只读，0 表示所选结构检查通过，1 表示阻断，2 表示命令错误；任何结果都不批准资产、不设置 ready-for-agent。正式检查需要绑定当前集合摘要的独立专业审查；真实批准仍由生命周期原验证器核验。
+
+## 实现承接与变化
+
+实现票 frontmatter 声明 `kind: vertical-slice-ticket`、`business_ticket_set_ref`、`business_ticket_refs`（稳定 ID 数组）、`acceptance_refs`（原始 AC 数组）。编译器将集合加入 Slice v3 既有 basis.business_ticket_set；acceptance 必须仍指向原始 Spec 的 AC，且属于所引用业务票。一个业务票可对应多个 Slice，汇总时按 AC 覆盖集合计算，不能把一个子 Slice 完成当成业务票全部完成。
+
+接收方保留既有战略交接、词汇对账以及规则/场景到技术设计的映射。来源变化沿已登记依赖影响 Ticket/Slice；依赖缺失或未知时阻断相关整个范围。集合、Spec 或其他全局依据变化尚不能确定局部影响时保守阻断，不能无依据缩小。
+
+## 批准与交接兼容
+
+Handoff v5 外层结构不变。新 Design 源角色策略声明 required_capabilities: [business-ticket-approval-v1]，最终业务集合绑定 `gate.strategic-design-handoff-approved` 的当前资产批准；不能借用更早的 Plan 批准。旧工具拒绝未知能力。无能力声明的历史包沿原策略只读核验，不能补写历史 Plan 回复。包导出必须包含集合、票据、专业审查、原始来源和延期证据闭包。
+
+## 启用、迁移与回退
+
+新项目 tracker frontmatter 默认 `business_ticket_version: 1`。旧项目缺失配置时状态显示 legacy-unassessed，不自动判断已拆分，也不自动启用。显式迁移时保留原资产与批准，补齐当前业务草案、校准/审查及引用，再启用版本配置；同步工具不得覆盖用户 tracker。旧 Spec 格式不能机械解析时报告 unassessed，先显式适配内容格式，不能推断覆盖为空或已完成。
+
+回退可停用新规则入口但保留业务资产和读取能力。类型隔离、显式来源绑定与新能力拒绝始终有效；不得把业务票降格解释为旧实现票。
+
+## 状态投影
+
+`lifecycle-status` 分别展示业务拆分、实现拆分、实现就绪与批准未验证状态。阶段工作项 completed 仅表示该工作项完成。map/父 Ticket 引用集合，不复制正文；声明已同步时绑定当前集合 digest，过期则报告 sync-stale，不能改写历史批准。缺业务拆分、缺工程前置、tracker 状态过期和 checkpoint 失败分别报告。
+
+实现映射汇总可在上述命令追加多个 `--slice-ticket <issues/ref.md>`，输出每个业务票的 AC→Slice 引用和未映射 AC；covered 仅指映射覆盖，不代表任何实现已完成。接收方可直接使用既有导入协议下的 `docs/handoffs/<id>/<version>/package/payload/files/` 业务集合引用，校验器在不可变源根内解析绑定，并继续保留目标仓的批准/接收门禁。

package/template/.template-spec/process/checkpoint-boundary.yaml

@@ -0,0 +1,73 @@
+{
+  "schema_version": 1,
+  "derived_from": ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml",
+  "phase_boundary": {
+    "choices": [
+      "continue",
+      "clear",
+      "handoff",
+      "subagent",
+      "compact"
+    ],
+    "precedence": [
+      "continue",
+      "clear",
+      "handoff",
+      "subagent",
+      "compact"
+    ],
+    "invariants": [
+      "does-not-force-clear",
+      "preserves-lifecycle-state"
+    ],
+    "evidence": {
+      "required": [
+        "decision",
+        "reason"
+      ],
+      "conditional": {
+        "handoff": [
+          "source_ref",
+          "destination_ref"
+        ],
+        "subagent": [
+          "task_package_ref",
+          "convergence_ref"
+        ],
+        "compact": [
+          "next_phase"
+        ]
+      }
+    },
+    "preserves": [
+      "lifecycle.status",
+      "gate.status",
+      "ticket.role"
+    ]
+  },
+  "checkpoint_policy": {
+    "strategy": "consolidated",
+    "flush_on": [
+      "stage_exit",
+      "human_pause",
+      "handoff",
+      "implementation_entry",
+      "merge",
+      "release"
+    ],
+    "flush_immediately_on": [
+      "blocked",
+      "responsibility_changed",
+      "asset_approval"
+    ],
+    "preserve_stage_causality": true,
+    "required_stage_trace_fields": [
+      "stage",
+      "upstream_refs",
+      "artifact_refs",
+      "gate_decisions",
+      "downstream_impacts"
+    ],
+    "project_instance_stage_exit_requires_context_reconciliation": true
+  }
+}

package/template/.template-spec/process/contract-reading.md

@@ -39,8 +39,67 @@ 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、截图及适用命令并另存新报告，不给旧报告补造通过记录。摘要校验不证明交互语义，实际浏览器轨迹和独立前端审查仍按既有边界执行。
+
+## 首批中文阅读页与显式托管
+
+`domain-strategy`、`stage-decision-package`、`checkpoint`、`tracking-migration` 提供专用中文 Markdown。业务原文、稳定 ID、枚举、失败条件、零值、未知字段均保留；旧类型继续使用原有兼容布局。`--json` 保留原接口字段，首批四类可用 `--model --json` 显式获取 `reading_model`；默认不附逐字段索引以减少 Agent 读取成本；`source_pointer` 只用于可直接对应原字段的条目，其他条目使用 `content_pointer`，不冒充原文位置。
+
+源文件是唯一可编辑事实。阅读页是来源快照，不证明当前批准或执行权；`blockers: []` 只表示未登记阻塞。检查点阶段和工作项进度分别展示。原始 Markdown 文档仍由作者维护，JSON/YAML 的机器绑定不因阅读层改写。
+
+```sh
+# 只读预览；只读检查不创建文件
+scripts/contract view <原资产> --kind domain-strategy
+scripts/contract view <历史迁移plan.json> --kind tracking-migration
+scripts/contract check-views --checkpoint docs/.scratch/<feature>/checkpoint.yaml
+
+# 先审阅启用计划，再显式应用；不覆盖已有计划
+scripts/contract plan-enable --checkpoint docs/.scratch/<feature>/checkpoint.yaml --output reading-enable.json
+scripts/contract apply-enable reading-enable.json
+
+# 手动重建，或完成直接源编辑后调用
+scripts/contract render --checkpoint docs/.scratch/<feature>/checkpoint.yaml
+
+# 正式差异记录可明确保存；相同内容幂等，历史报告不追随源覆盖
+scripts/contract prepare-review <旧资产> <新资产> --kind domain-strategy --checkpoint docs/.scratch/<feature>/checkpoint.yaml --json
+```
+
+策略由 `reading-policy.yaml` 持有；缺失或 `manual` 保留旧行为。实际人工阅读试验通过前，模板默认 `manual`。`apply-enable` 只将计划绑定的 checkpoint 登记为托管；其他功能不会被自动接管。领域与阶段决策页消费 checkpoint.artifacts 中对应 `artifact.domain-strategy`、`artifact.stage-decision-package` 的明确 ref；不扫描目录推断资产。其他未来资产保留原入口。
+
+输出放在功能目录 `reading/`：`status.review.md`、对应合同审阅页、`.manifest.json`；正式差异放在 `reading/changes/`。`map.md` 只维护 `YSS-READING:BEGIN/END` 标记范围，保留外部人工正文。manifest 只存依赖、代码与输出摘要和生成诊断，不保存可复用批准。
+
+`check-views` 核对源字节、明确引用、术语、schema、生成器依赖、输出和导航块；只读且不重建。`current` 表示呈现一致性，不代表业务门禁通过；`diagnostics` 中原资产的阻断仍由资产所有者处理。正式准备 API 对托管过期包返回缺口；CLI `prepare-review` 在准备前重建，实际流转代码再次只读检查。`lifecycle-status` 只报告阅读可用性。
+
+生成使用排他锁、恢复日志、逐文件原子替换，manifest 最后提交。人工改动、同名非托管文件、符号链接、坏 manifest 或导航块会保留并报冲突。先保存人工改动，再恢复对应旧生成物及 manifest 后重建；不提供覆盖式 force。检测到历史输出已不再登记时要求人工确认处置，不静默删除。
+
+阶段追踪事务成功后调用共同 `finalizeReading`；`source_operation: applied` 与 `reading_update.status: failed` 可以同时出现。此时源已应用，只修复阅读冲突并运行 render，不能为了补阅读页重做源事务。进程中断后的生成日志只恢复仍匹配本轮字节的派生文件；他人改动会留下恢复冲突。
+
+迁移预览核对计划、内嵌 after 和 Base64 备份摘要；缺少匹配备份时显示“无法比较旧内容”，不以当前文件替代。单文件解码预览上限 2 MiB，超出时返回诊断，不截断或执行内容。receipt 只说明原事务状态。差异按已有稳定 ID 对齐，数组重排独立显示；`binding-change` 和 `unclassified` 仍须审阅，不自动沿用批准。

package/template/.template-spec/process/document-writing.md

@@ -79,3 +79,5 @@
 4. 检查正文、摘要、表格和状态是否一致；验证适用的引用、结构和合同。自检结论不代替独立审查或批准。
 
 规则、例外、证据或状态变化属于实质差异，不能被“字数减少”抵消。不要只用禁用词扫描或模型给自己的分数判断效果。
+
+生成阅读材料使用 [合同阅读入口](contract-reading.md)。业务解释写入权威资产或人工 Markdown；不要手改 `reading/*.review.md`、manifest 或 map 的工具标记块。源编辑完成后更新已启用的阅读包，批准仍引用原资产及其摘要。

package/template/.template-spec/process/feature-assets.md

@@ -0,0 +1,38 @@
+# 功能资产受控整理
+
+目标是移除可重建缓存、归档未引用的旧草稿。不会批准合同、推进阶段、改写 checkpoint 或重算业务状态。父 Ticket 保留五态、业务说明与资产 / 会签入口，阶段、阻塞和下一工作单元引用实际 checkpoint 并按需查询；阅读包保持显式启用、默认 `manual`。
+
+## 命令
+
+```sh
+scripts/feature-assets inspect --root <项目绝对路径> --checkpoint docs/.scratch/<feature>/checkpoint.yaml --json
+scripts/feature-assets plan --root <项目绝对路径> --checkpoint docs/.scratch/<feature>/checkpoint.yaml \
+  --candidate docs/.scratch/<feature>/verification/prototype-evidence-draft.yaml \
+  --archive-dir <项目外全新归档绝对路径> > <项目外计划.json>
+scripts/feature-assets apply --root <项目绝对路径> --plan <项目外计划.json>
+scripts/feature-assets restore --root <项目绝对路径> --receipt <归档绝对路径>/receipt.json
+```
+
+路径必须显式给出，候选使用根相对路径。inspect / plan 只输出 JSON，不写项目。计划展示删除、归档、保留、理由、引用和内容 / 权限摘要，绑定项目身份、工具实现与引用扫描输入。apply 重新生成判定并检查输入；漂移后重新计划，不强行继续。退出码 0 为操作完成，1 为缓存占用或不可判定而部分保留，2 为输入 / 冲突 / 执行错误。
+
+## 分类与引用
+
+- 仅登记 `verification/browser/.chrome-profile` 与 `.chrome-baseline-profile` 两种可重建测试缓存允许删除；`ps` 或 `lsof` 不可用、诊断异常、占用信息出现时保留，不终止进程。
+- `verification/prototype-evidence-draft.yaml` 已有正式对应资产、`plan/stage-items.yaml` 已有 checkpoint 工作项、`verification/browser/summary.json` 已有详细结果时可作为归档候选。
+- `gates/captures/*-question.yaml` 仅全为数字人提问、具有 message ID 且无决定字段时可作为归档候选；原始人工回复保持保护。
+- 合同、批准、任务包、正式验证、迁移回执、冻结交接及未知类别默认保留。重复字节只是统计信息，不是删除依据。
+- 按文件名、根相对路径、提问 message ID 扫描引用，直接写入摘要的语句只记生产者。可识别但无法确定的动态消费、符号链接和过大文本会阻止候选处理；无引用本身不构成许可。扫描范围与边界见下节。
+
+## 执行与恢复
+
+归档按“复制 → 校验 SHA-256、大小和权限 → 移除原件”执行。外部目录内统一 `receipt.json` 保存逐项执行态，不为项目资产增加 sidecar。中断后用同一计划继续：复制结果先复核；删除缓存仅接受原树的未改变剩余子集。已处理计划返回原结果，不重复操作。不要将归档目录放进被扫描项目。
+
+restore 先校验所有备份和目标，再逐项恢复；目标已有不同内容或权限则拒绝覆盖。缓存不参与恢复。来源父目录保留，恢复文件内容与权限。执行期间避免其他进程编辑同一功能包；再次检测到输入漂移即停止，已完成项由回执恢复，不覆盖后续人工修改。
+
+旧父 Ticket 只对明确指定文件制作迁移差异，保存完整原文；状态冲突同时列出父票与 checkpoint 原值，保持冲突待处理，不改变 checkpoint、批准记录、Ticket 五态或执行权限。批准 / 冻结摘要绑定父 Ticket 时，先报告引用并保留原件，不能当作普通阅读页改写。
+
+## 扫描边界
+
+本工具用于受控的本地功能包，不证明任意外部系统或动态程序不存在引用。扫描项目内文本资产及本地脚本，排除版本控制、依赖、图索引、运行时投影及已登记浏览器缓存。模板 / canonical Skill / 工具文件仅在与安装元数据摘要一致时按通用框架跳过引用解释；本地新增或修改内容继续扫描。整理工具自身与本文不作为功能消费方，仍绑定其摘要。外部 tracker、运行中的 Agent 上下文、任意反射或网络引用需要操作者确认；已知动态来源不能解析时保留候选。不要在未知引用环境自动批量 apply。
+
+首次实例迁移在完整副本验证，正式执行前保存项目外完整备份。对相同门禁做前后验证，正式资产摘要保持一致；既有失败原样报告，整理完成不代表阶段通过。