create-yss-spec 3.4.9 → 3.5.0

package/template/.pi/skills/yss-prototype-stage/SKILL.md

@@ -5,6 +5,8 @@ description: Use when a YSS feature has product-design impact on a primary flow,
 
 # YSS Prototype Stage
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 把产品设计影响收敛为跨 Agent 一致的原型交付物、证据和生命周期回流合同。它不替代 `yss-product-lifecycle` 的门禁裁决，也不把原型当作生产前端代码。
 
 文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
@@ -51,7 +53,7 @@ Design QA 合并 visual、layout、interaction、content、accessibility、cross
 ## 按需读取
 
 - 档位、上游融合与迁移：[prototype-profile-routing.md](references/prototype-profile-routing.md)
-- 渲染适配、fact pack 与命令：[product-design-adapter.md](references/product-design-adapter.md)
+- 离线渲染适配与命令：[product-design-adapter.md](references/product-design-adapter.md)
 - 证据模板：`docs/design/templates/prototype-evidence-template.yaml`
 - Visual Baseline 模板与 schema：`docs/design/templates/visual-baseline-template.yaml`、`docs/design/schemas/visual-baseline.schema.json`
 
@@ -59,7 +61,7 @@ Design QA 合并 visual、layout、interaction、content、accessibility、cross
 
 - 把 H1/H2 当作低/高保真；把离线 HTML 降为静态截图，或继续要求 Provider、Node starter、预先生成图片。
 - 低保真未评审就选择技术栈；用主观评分代替确定性触发规则。
-- 空填 lockfile/fact pack；把自身生成图当成独立来源，或宣称已验证生产真实组件。
+- 编造组件版本或构建来源；把自身生成图当成独立来源，或宣称已验证生产真实组件。
 - 重复抄写机器可采集的版本、digest、截图和 console；创建第二份状态机、QA 或 handoff 资产。
 - 把原型源码直接复制进生产，或在原型阶段调用 `yss-ui`。
 

package/template/.pi/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
-import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { existsSync, readFile, readdir } from "../../../../scripts/lib/validation-phase.mjs";
+import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseDocument, stringify } from "../../../../scripts/vendor/yaml.mjs";

package/template/.pi/skills/yss-repository/SKILL.md

@@ -29,6 +29,7 @@ description: 用于按批准的 YSS 架构与持久化合同实现或重构 PO
 <a id="repository.mapping"></a>
 <!-- yss-rule {"id":"repository.mapping","when":"persistence","level":"mandatory","evidence":"code-and-verification"} -->
 - 数据合同必须显式覆盖主键、逻辑删除、审计字段、空值、枚举/值对象映射和敏感字段；动态排序、分组与过滤必须使用批准白名单和参数绑定。
+- 数据合同选择 YSS 分布式主键时，记录已选 `component.distributed-id` 绑定、Segment/Snowflake 策略、实体主键类型与批量插入路径，并消费 `yss-distributed-id` 的当前平台证据；不由 Repository 自行切换算法或创建发号合同。
 <a id="repository.transaction"></a>
 <!-- yss-rule {"id":"repository.transaction","when":"persistence","level":"mandatory","evidence":"code-and-verification"} -->
 - 事务归所选 Profile 的用例边界。Repository/Gateway Adapter 不临时新增业务事务，也不把数据库异常原文或凭据暴露给上层。

package/template/.pi/skills/yss-stage-decision/SKILL.md

@@ -5,6 +5,8 @@ description: 编排 Plan 到 Spec 入口的方案决策与业务边界、协作
 
 # YSS Stage Decision
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 `yss-stage-decision` 是由生命周期主控调度的上游决策技能，负责把需求、产品、商务输入和业务边界与规则设计结果整理成可审查、可版本化、可被下游消费的方案决策包。它不替代生命周期主控，也不生成产品代码、原型、OpenAPI 或垂直切片 Ticket。
 
 文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。

package/template/.pi/skills/yss-tactical-design/SKILL.md

@@ -5,6 +5,8 @@ description: 在 YSS 技术分析阶段将批准的战略领域输入细化为
 
 # yss-tactical-design
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 本 skill 负责 DDD 战术设计，不新增生命周期主阶段，也不替代 `yss-stage-decision` 或 `yss-domain`。
 
 ## 适用边界

package/template/.pi/skills/yss-technical-design/SKILL.md

@@ -5,6 +5,8 @@ description: 在 YSS 技术分析中统一承接需求与战略输入，按已
 
 # YSS 技术设计
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 由 `yss-product-lifecycle` 调度，负责 `work-unit.technical-analysis` 的技术设计，不另起生命周期、不生成生产代码。生命周期维护批准和状态；`yss-implementation-contract-compiler` 消费批准且当前的设计，起草实现合同。
 
 文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。

package/template/.pi/skills/yss-technical-design/scripts/engineering-design.mjs

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import {readFileSync} from 'node:fs';
+import {readFileSync} from '../../../../scripts/lib/validation-phase.mjs';
 import {ensure,read,safe,hash} from '../../../../scripts/lib/strategic-handoff-io.mjs';
 const beneath=(ref,scope)=>ref===scope||ref.startsWith(`${scope}/`);
 export function validateEngineeringDesign(data,{root}) {

package/template/.pi/skills/yss-technical-design/scripts/validate-technical-design.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
+import { readFileSync, withValidationPhase, validationDependencies } from '../../../../scripts/lib/validation-phase.mjs';
 import { validateEngineeringDesign } from './engineering-design.mjs';
 import { createApprovedExecutionContext, assertApprovedExecutionContext } from '../../../../scripts/lib/approved-execution-context.mjs';
 import { verifyArchitectureEvidence } from '../../../../scripts/lib/backend-architecture.mjs';
@@ -42,8 +42,8 @@ function validateMvc(design) {
   if (!design.integration_catalog.length) ensure(text(design.integration_not_applicable_reason), '无外部集成必须说明原因');
 }
 
-export function verifyArchitecture(data, root, {execution,sliceRef}={}) {
-  if(execution)assertApprovedExecutionContext(execution,{root,technicalDesign:data,sliceId:sliceRef});
+export function verifyArchitecture(data, root, {execution,sliceRef,readOnly=false}={}) {
+  if(execution)assertApprovedExecutionContext(execution,{root,technicalDesign:data,sliceId:sliceRef,readOnly});
   const binding = data.architecture;
   const file = safe(root, binding.decision_ref);
   ensure(hash(readFileSync(file)) === binding.decision_digest, '架构来源摘要漂移');
@@ -63,7 +63,7 @@ export function verifyArchitecture(data, root, {execution,sliceRef}={}) {
     ensure(!['stale','blocked'].includes(record.status) && !['stale','blocked'].includes(entry.status), '工程登记已失效');
     if (entry.architecture_identity?.schema_version === 2) {
       ensure(entry.architecture_evidence?.engineering_baseline && entry.architecture_evidence?.manifest, '既有工程登记缺少原始工程证据引用');
-      verifyArchitectureEvidence(entry.architecture_identity, { ...entry.architecture_evidence, repository_registration: { ref: binding.decision_ref, digest: binding.decision_digest } }, { root, execution });
+      verifyArchitectureEvidence(entry.architecture_identity, { ...entry.architecture_evidence, repository_registration: { ref: binding.decision_ref, digest: binding.decision_digest } }, { root, execution, readOnly });
     }
   }
 }
@@ -111,7 +111,7 @@ export async function validateTechnicalDesign(data, { root = process.cwd(), slic
   ensure(data.digest === technicalDigest(data), '技术设计合同摘要不匹配');
   ensure(!['stale','blocked','drift','new_impacts'].includes(data.status), '设计状态不可消费');
   if (sliceRef) ensure(data.status === 'approved', '切片只能消费 approved 设计');
-  verifyArchitecture(data, root, {execution,sliceRef});
+  verifyArchitecture(data, root, {execution,sliceRef,readOnly});
   ensure(data.inputs.some(item => item.kind === 'context' && item.ref === 'CONTEXT.md') && data.inputs.some(item => item.kind === 'spec'), '共同输入缺少根 CONTEXT.md 或 Spec');
   for (const input of data.inputs) ensure(hash(readFileSync(safe(root, input.ref))) === input.digest, `输入摘要漂移: ${input.ref}`);
   for (const ref of data.evidence_refs) safe(root, ref);
@@ -135,12 +135,15 @@ export async function validateTechnicalDesign(data, { root = process.cwd(), slic
 }
 
 async function main() {
-  const { values, positionals } = parseArgs({ allowPositionals: true, options: { root: { type: 'string', default: process.cwd() }, slice: { type: 'string' }, 'legacy-ddd': { type: 'boolean', default: false }, 'read-only': {type:'boolean',default:false}, 'work-unit': {type:'string'}, 'approved-slice': {type:'string'}, 'approved-slice-digest': {type:'string'}, 'approved-slice-approval': {type:'string'} } });
+  const { values, positionals } = parseArgs({ allowPositionals: true, options: { root: { type: 'string', default: process.cwd() }, slice: { type: 'string' }, 'legacy-ddd': { type: 'boolean', default: false }, 'read-only': {type:'boolean',default:false}, 'validation-dependencies': {type:'boolean',default:false}, 'work-unit': {type:'string'}, 'approved-slice': {type:'string'}, 'approved-slice-digest': {type:'string'}, 'approved-slice-approval': {type:'string'} } });
   ensure(positionals.length === 1, '用法: validate-technical-design.mjs <合同> --root <项目根> [--slice <ID>] [--legacy-ddd]');
   const approvedOptions=['approved-slice','approved-slice-digest','approved-slice-approval'];
   ensure(!approvedOptions.some(key=>values[key])||approvedOptions.every(key=>values[key]),'执行增量必须完整给出持久化 Slice、字节摘要及本地批准引用');
-  const execution=values['approved-slice']?createApprovedExecutionContext({ref:values['approved-slice'],digest:values['approved-slice-digest'],approval_ref:values['approved-slice-approval']},{root:values.root,work_unit_id:values['work-unit']}):undefined;
+  const output=await withValidationPhase({root:values.root,purpose:'technical-design',slice_id:values.slice,work_unit_id:values['work-unit'],readOnly:values['read-only']},async()=>{
+  const execution=values['approved-slice']?createApprovedExecutionContext({ref:values['approved-slice'],digest:values['approved-slice-digest'],approval_ref:values['approved-slice-approval']},{root:values.root,work_unit_id:values['work-unit'],readOnly:values['read-only']}):undefined;
   const result = await validateTechnicalDesign(read(path.resolve(positionals[0])), { root: values.root, sliceRef: values.slice, legacyDdd: values['legacy-ddd'], readOnly:values['read-only'], execution });
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return values['validation-dependencies']?{...result,validation_dependencies:validationDependencies()}:result;
+  });
+  process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
 }
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main().catch(error => { process.stderr.write(`${JSON.stringify({ result: 'blocked', errors: [error.message] })}\n`); process.exitCode = 1; });

package/template/AGENTS.md

@@ -42,6 +42,8 @@
 
 ## 6. Ticket 与状态
 
+- Plan / Spec / Design 按 `docs/process/stage-tracking.md` 从阶段入口登记工作、按需拆分并在恢复 / 流转时验证；工作项进度不替代 Ticket 五态和阶段批准。
+
 - 每个功能先建父 Ticket，汇总阶段资产、审查、阻塞和证据。
 - Spec、设计、原型、OpenAPI Draft 和待冻结资产使用 `ready-for-human`；只有门禁通过、阻塞清除且可直接实现的垂直切片才能使用 `ready-for-agent`。
 - 按 `docs/agents/issue-tracker.md` 持久化主 tracker，不从 Git remote 推断；平台不可用时生成待发布草案。五态见 `docs/agents/triage-labels.md`。

package/template/CONTEXT.md

@@ -39,8 +39,9 @@ context_schema_version: 1
 | 技能投影 | 从权威共享技能生成、供特定 Agent root 加载的同步副本。 | — | 投影不是独立维护的技能源，不应在各 Agent root 中分别修改。 |
 | Spec | 记录用户问题、解决方案、用户故事、关键决策、验收标准和测试 seam 的产品研发规格。 | — | 新资产统一使用 Spec；旧规格称谓只在迁移记录中保留。 |
 | Spec Delta | 记录相对于既有冻结 Spec 基线的 `ADDED / MODIFIED / REMOVED` 行为、验收场景和测试映射。 | — | 不用于全新产品或全新模块，也不替代完整 Spec、OpenAPI 或架构资产。 |
+| 阶段工作项 | Plan、Spec、Design 中有明确负责人、验收和证据的工作记录；当前进度由 checkpoint.stage_tracking 持有，按需独立落盘。 | — | 不等同于业务 Ticket 或可实现垂直切片，不授予 ready-for-agent。 |
 | Ticket | 在追踪平台上承载功能生命周期或可实现工作单元的通用追踪对象。 | — | GitHub Issues / GitLab Issues 是具体平台对象名称；领域资产统一称为 Ticket。 |
-| 功能父 Ticket | 汇总一个功能从 Spec 到契约冻结的阶段状态、资产链接、审查结论和阻塞项的 Ticket。 | — | 不作为 Agent 直接实现的垂直切片。 |
+| 功能父 Ticket | 汇总一个功能从 Plan 或最近可信接入阶段到契约冻结的阶段状态、资产链接、审查结论和阻塞项的 Ticket。 | — | 不作为 Agent 直接实现的垂直切片。 |
 | 垂直切片 Ticket | 契约冻结后生成的可独立验证实现单元，记录范围、阻塞关系、验收标准和验证证据。 | — | 只有通过必要门禁并具备直接实现条件时才能标记 `ready-for-agent`。 |
 | `ready-for-human` | 表示 Spec、设计、契约草案或其他资产仍需会签（指定数字人或生物人）。 | — | 此状态不表示可以直接进入实现；也不等于某个数字人角色。 |
 | `ready-for-agent` | 表示垂直切片已通过必要门禁并具备直接实现条件的流程状态。 | — | 不得用于 Spec 初稿、原型、OpenAPI Draft 或其他未冻结资产。 |

package/template/README.md

@@ -98,21 +98,20 @@ scripts/verify-template-fast
 
 ## 关键文档
 
+业务方可从[用户手册](./docs/user-guide/用户手册.md)了解工作入口；阶段、条件门禁和完成证据以生命周期注册表及流程裁剪规则为准。
+
 | 文档 | 内容 |
 |------|------|
 | [AGENTS.md](./AGENTS.md) | 全局 AI 指令 + 工程基线入口 + Agent 协作 |
 | [docs/user-guide/用户手册.md](./docs/user-guide/用户手册.md) | 从首次只读检查到需求、开发、审查、发布和 CLI 操作的统一用户手册 |
-| [docs/process/PDCA-SCRUM.md](./docs/process/PDCA-SCRUM.md) | PDCA × Scrum × AI |
+| [阶段接入与产物复用使用手册](./docs/user-guide/阶段接入与产物复用使用手册.md) | 复用上游资产，从指定入口继续；含后端交付后前端开发操作 |
 | [docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md](./docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md) | Matt Pocock Engineering Skills 集成与使用 |
 | [docs/process/lifecycle-registry.yaml](./docs/process/lifecycle-registry.yaml) | 生命周期结构事实源：主阶段、门禁、产物、工作单元、证据与稳定 ID |
 | [docs/process/harness-process-tailoring.md](./docs/process/harness-process-tailoring.md) | 小改动 / 中等变更 / 新模块的流程裁剪指南 |
-| [docs/process/harness-executive-blueprint.md](./docs/process/harness-executive-blueprint.md) | 面向业务方和管理者的 Harness 一页式蓝图 |
 | [docs/process/implementation-repo-integration.md](./docs/process/implementation-repo-integration.md) | 外部前端 / 后端实现仓库接入与跨仓库切片绑定 |
 | [docs/agents/README.md](./docs/agents/README.md) | Agent 协作文档目录说明 |
 | [docs/user-guide/yss-ui-mcp.md](./docs/user-guide/yss-ui-mcp.md) | YSS UI MCP 项目配置、全局安装边界与自检 |
-| [docs/plan/IDEATION.md](./docs/plan/IDEATION.md) | 机会构想方法 |
 | [docs/architecture/README.md](./docs/architecture/README.md) | 架构设计 + 审查清单 |
-| [docs/testing/README.md](./docs/testing/README.md) | 测试策略 |
 
 ## 核心模板
 
@@ -121,7 +120,6 @@ scripts/verify-template-fast
 | [docs/templates/spec-template.md](./docs/templates/spec-template.md) | Spec，包含 OpenAPI 影响、测试决策、AI / 人工审查点 |
 | [docs/templates/local-parent-ticket-template.md](./docs/templates/local-parent-ticket-template.md) | Local Markdown 功能父 Ticket 与生命周期索引 |
 | [docs/templates/vertical-slice-ticket-template.md](./docs/templates/vertical-slice-ticket-template.md) | 垂直切片 Ticket |
-| [docs/templates/agent-brief-template.md](./docs/templates/agent-brief-template.md) | `triage` 产出的 Agent Brief |
 | [docs/templates/implementation-repo-registry-template.md](./docs/templates/implementation-repo-registry-template.md) | 外部实现仓库登记 |
 | [docs/templates/cross-repo-slice-template.md](./docs/templates/cross-repo-slice-template.md) | 跨仓库垂直切片记录 |
 | [docs/architecture/templates/architecture-deepening-template.md](./docs/architecture/templates/architecture-deepening-template.md) | 架构 deepening 候选与 seam 设计 |

package/template/docs/agents/issue-tracker.md

@@ -1,5 +1,6 @@
 ---
 tracker:
+  lifecycle_tracking_version: 1
   platform: local-markdown
   root: docs/.scratch
   legacy_roots:
@@ -135,3 +136,9 @@ Ticket 是默认 triage surface。MR / PR 是否纳入 triage 取决于当前平
 - Local Markdown：读取引用的 `docs/.scratch/<feature>/...` 文件；旧路径引用必须先经过迁移检查。
 - GitLab：使用 `glab issue view <iid> --comments`。
 - GitHub：使用 `gh issue view <number> --comments`。
+
+## 阶段工作追踪
+
+新初始化默认启用 `tracker.lifecycle_tracking_version: 1`。已有项目的 attach / sync 保留原配置；缺省保持旧模式，按 [阶段工作追踪](../process/stage-tracking.md) 执行 check → plan → apply。
+
+Plan / Spec / Design 的小工作记录在 checkpoint.stage_tracking；独立工作项使用 `work-items/<id>.md`，不占用业务票 / 实现切片的 `issues/`。执行进度只由 checkpoint 保存，父票和 map 引用；阶段工作项不得设置 `ready-for-agent`。

package/template/docs/agents/skill-migrations.md

@@ -2,6 +2,10 @@
 
 本文记录已退役技能入口的迁移路径。退役技能不保留物理目录、投影或 lock 条目；本文件是历史名称的唯一持久兼容说明。
 
+## `grill-me` 入口退役（2026-09-24）
+
+`grill-me` 仅转发到 `grilling`，现已硬退役。新请求直接使用 `grilling`；旧 ID 返回 `skill-retired`，不保留兼容目录、投影、Registry 或 lock 条目。历史候选与冻结证据只读保留。
+
 ## 后端组件源码索引双轨迁移（2026-09-19）
 
 后端组件 Skill 的单一 `references/source-index.md` 已迁移为平台线选择页。生成证据分别保存在 `source-index.boot2-java8.md` 与 `source-index.boot3-java17.md`，来源根分别由 `YSS_SOURCE_ROOT_BOOT2_JAVA8` 与 `YSS_SOURCE_ROOT_BOOT3_JAVA17` 显式提供。

package/template/docs/agents/yss-skill-registry.yaml

@@ -6,6 +6,13 @@ description: >-
   单一可执行注册表。实现合同编译器与生命周期编排器只消费通过本表校验的
   canonical 技能；skills-lock.json 继续独立持有来源、hash 与投影完整性。
 canonical_content_root: .agents/skills
+instance_distribution:
+  schema_version: 1
+  initial_skills: [yss-product-lifecycle, yss-research, i-have-adhd]
+  runtimes: [codex, cursor, pi]
+  projection_roots: { codex: .codex/skills, cursor: .cursor/skills, pi: .pi/skills }
+  dependency_types_for_ensure: [context-required, context-conditional]
+  initial_example_docs: false
 backend_skill_domains:
   schema_version: 1
   scope: active-yss-backend-capability-owners
@@ -354,12 +361,6 @@ skills:
     instance_default_discoverable: true
     aliases: []
     impacts: [discovery]
-  - id: grill-me
-    layer: compatibility
-    maturity: supported
-    instance_default_discoverable: false
-    aliases: []
-    impacts: [discovery]
   - id: grill-with-docs
     layer: compatibility
     maturity: supported

package/template/docs/design/README.md

@@ -46,7 +46,6 @@ Token 或组件视觉变体变更必须先修改 `DESIGN.md`，再更新派生
 - `product-design:index`：Codex 产品原型产出的主路由；根据输入是否有 URL、截图、Figma、代码目标或视觉方向，进入 `$get-context`、`$ideate`、`$prototype`、`$image-to-code`、`$url-to-code`、`$share` 或 `$design-qa` 等 focused skill。
 - Product Design focused skills：按 H1/H2 的问题边界产出视觉或流程设计资产；ideation 只在新/不确定视觉方向时强制。
 当前原型使用 `yss-prototype-stage` 的离线 HTML 适配器；历史 Provider 证据保持只读。
-当前原型使用 `yss-prototype-stage` 的离线 HTML 适配器；历史 Provider 证据保持只读。
 - `prototype-review`：原型阶段评审门禁；未通过则不要进入 Spec 校准 / API 影响分析 / 契约草案。
 - 兼容入口：`product-design-prototype`、`high-fidelity-html-prototype` 只读迁移；新资产统一使用 `artifact.prototype-deliverable`、`yss-prototype-stage`、Prototype Evidence schema v4 与 Visual Baseline schema v1。
 

package/template/docs/design/design.md

@@ -35,13 +35,13 @@
 
 ## 原型设计依据的优先级
 
-原型使用 Ant Design 或 Antdv Next 时，上游 `design.md` 与组件查询提供的是**上游默认**和组件事实；项目根 `DESIGN.md` 是**规范覆盖**，`docs/design/design.md` 是治理解释，`docs/design/tokens/*` 是派生实现视图。当前功能只能在这些层之下完成语义组件映射。若上游默认与项目 Token 不同，以根规范源为准，并在 `prototype-evidence.yaml` 中记录根规范与 Token digest；不得把上游默认直接写回项目实现。
+当前原型以项目根 `DESIGN.md` 为视觉规范源，`docs/design/design.md` 解释治理规则，`docs/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`。
 
-原型 H1/H2 统一使用 `html-css-js`，以本地 Token CSS 保留 YSS 企业后台视觉语言。生产实现只在目标工程按 lockfile 核验组件 API；原型阶段不调用 `yss-ui`。已冻结的组件库原型和 fact pack 保留历史只读，不再生成新的 Provider 事实包。
+原型 H1/H2 默认使用 `html-css-js`，以本地 Token CSS 保留 YSS 企业后台视觉语言；复杂交互影响评审结论时可按集成说明选用 `react-antd-prebuilt`。生产实现只在目标工程按 lockfile 核验组件 API；原型阶段不调用 `yss-ui`。已有项目中冻结的组件库原型及其事实证据保持只读；模板不再预置 Antdv Next fact pack，也不生成新的 Provider 事实包。
 
 ### HTML 与生产主题的映射
 

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

@@ -106,7 +106,7 @@
 - 每个表格列、筛选条件、表单字段、抽屉、弹窗和按钮都有数据来源或契约反推说明。
 - 设计可以拆成独立可演示的垂直切片。
 - 低保真评审通过后，记录档位触发与待确认决定；H1 覆盖视觉和少量交互，H2 覆盖主流程/关键异常。
-- H2 只有实际使用 React AntD 且 fact pack 不新鲜时才执行增量 CLI 查询；H1 不创建 AntD 证据。任何原型档位都不得调用 `yss-ui` 或声明已验证真实生产组件。
+- H2 仅在复杂交互影响评审结论且选用 `react-antd-prebuilt` 时，记录精确组件版本、选择理由与预构建来源；H1 不创建组件库证据。任何原型档位都不得调用 `yss-ui` 或声明已验证真实生产组件。
 
 ## 9. 决策与未决问题