create-yss-spec 2.2.8 → 2.2.9

package/template/docs/process/harness-process-tailoring.md

@@ -46,6 +46,13 @@
 5. 模板正式发布仍执行一次完整 `scripts/verify-template`，但不因 L3 额外冻结候选或派发正式独立审查。
 6. 模板维护与产品切片使用同一 finding 闭环：`violation` / 机器检查失败 / 适用行空白由实施者修复后重新验证并按本表强度复审；`drift` / `new_impacts` 升级影响面并重新分级，禁止在旧合同或旧 checkpoint 上继续编码。审查者不得写实现。未命中的条件项才 `not-applicable`；命中后不得豁免。
 
+## 5. 上下文、反证与质量基线裁剪
+
+- Slice Contract 的 `common.context_plan` 是实现上下文的唯一轻量计划：先读 `CONTEXT.md`、已批准 Spec、当前合同和适用 ADR / 工程基线，再按影响面按需加载 references；达到最小充分证据后停止扩展。缺失权威上下文只能 `blocked` 或 `reroute`。
+- 质量标准在 `engineering-baseline` 中定义一次，以 `baseline_id` / `baseline_version` 被 Slice Contract、YSS Skill Execution Result、`code-review` 和发布检查复用；切片不得重定义同一标准。约束结果统一写入 `constraint_results`。
+- 只有命中高风险影响时才要求 Doubt-Driven 在途反证：API / 数据迁移、跨仓契约、发布回滚、实际改变的安全行为、生命周期或生成语义。反证写入现有决策 / 架构 / 契约 / 发布审查记录，不新增生命周期阶段；缺少反证、证据不足或残余风险未处理即阻断。
+- Wayfinder 是超长工作的可选规划模式，不改变阶段、门禁或 Ticket 状态；地图收敛后按 `wayfinder → handoff → to-spec` 返回主链。
+
 模板维护默认停在 `implementation-ready`，不自动冻结候选或派发审查。需要独立审查时显式提升到 `review-ready`；完成独立审查和最终完整门禁后才能成为 `release-ready`。三个核验入口由 `docs/process/template-verification-profiles.yaml` 统一定义：
 
 - `scripts/verify-template-fast`：按 Git 影响面运行快速检查；未映射路径或核心核验资产变化时 fail-safe 升级为完整门禁。

package/template/docs/process/lifecycle-registry-baseline.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "registry_id": "yss.lifecycle",
-  "semantic_sha256": "49ca553e83efb9cffae220d9e6fca434b1d27096126a640f8f8e172e048808df",
+  "semantic_sha256": "15375e8d7da599e2117e19399cb5e14b9c53aa4e4ce7c94c4e9c135a499e55e6",
   "published_ids": [
     "artifact.architecture-review",
     "artifact.data-architecture",

package/template/docs/process/lifecycle-registry.yaml

@@ -360,7 +360,7 @@ work_units:
   - id: work-unit.stage-decision
     name: 阶段决策包综合
     scope: project-instance
-    input: Discovery、DDD 战略设计、产品和商务输入。
+    input: Discovery、DDD 战略设计以及产品经理负责的商业约束输入。
     output: 带版本、digest、证据和下游映射的阶段决策包。
     completion: 必填字段、引用、影响面和下游消费验证通过；批准门禁完成。
   - id: work-unit.spec-synthesis

package/template/docs/process/template-verification-profiles.yaml

@@ -32,6 +32,7 @@ core_escalation_patterns:
   - scripts/cache-template-commit
   - scripts/capture-maintenance-candidate
   - scripts/inspect-maintenance-candidate
+  - .template-source/tooling/node/scripts/design-md.mjs
 required_files:
   - yss-project.yaml
   - AGENTS.md
@@ -129,6 +130,8 @@ syntax_files:
   - scripts/verify-maintenance-review-workflow-scenarios
   - scripts/verify-template-cache-scenarios
 routing:
+  - patterns: [DESIGN.md, "docs/design/**", ".template-source/tooling/node/scripts/design-md.mjs"]
+    groups: [design-system]
   - patterns: [AGENTS.md, CONTEXT.md, yss-project.yaml, package.json, .gitignore, README.md, "docs/**"]
     groups: [hygiene]
   - patterns: [AGENTS.md, yss-project.yaml, "docs/process/template-engineering-overview.md"]
@@ -156,6 +159,10 @@ routing:
   - patterns: ["scripts/**"]
     groups: [hygiene]
 groups:
+  design-system:
+    commands:
+      - { run: "node .template-source/tooling/node/scripts/design-md.mjs lint DESIGN.md", when: template-source }
+      - { run: "node .template-source/tooling/node/scripts/design-md.mjs drift", when: template-source }
   hygiene:
     commands: []
   tooling:

package/template/docs/templates/build-architecture-checklist-template.md

@@ -46,6 +46,8 @@ owner: ai
 | 工程项目路径：每个 Harness 内项目必须有具体项目段，禁止直接写入容器根或单数 `app/...` | `docs/process/implementation-repo-integration.md` / implementation path validator |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 路径违规时停止 build，并回到实现路由 |
 | 文档语言：持久化生命周期文档、实施记录、审查报告、发布说明和 Git checkpoint 正文必须使用中文，英文 skill / 模板不得原样落地 | `AGENTS.md` / `yss-product-lifecycle` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 仅保留必要英文技术标识、命令和 metadata |
 | 高风险变更：按已批准的普通影响面结论记录验证证据、责任人和回滚约束 | `AGENTS.md` / Spec / 架构记录 |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺验证证据或责任人时不得发布或合并 |
+| 质量基线：`baseline_id` / `baseline_version` 只从 `engineering-baseline` 引用，Slice、Execution Result、审查和发布不得重复定义 | `engineering-baseline` / `orchestration-contract.yaml` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺少基线引用或出现重复标准时阻断并回到工程基线 |
+| Doubt-Driven：命中 API、数据、跨仓、发布回滚、实际安全行为或生命周期 / 生成语义时具备主张、反证、证据、残余风险和审查引用 | Router Contract / `orchestration-contract.yaml` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺反证、证据不足或残余风险未处理时阻断 |
 |  |  |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  |  |
 
 状态说明：

package/template/docs/templates/implementation-routing-template.md

@@ -95,11 +95,34 @@ owner: ai
 | verification_commands |  |
 | human_review_points |  |
 | full_reroute_triggers | 新 API/schema、状态机、数据模型、写目录、仓库、skill、风险、seam、交付顺序或其他未冻结行为等变化 |
+| quality_baseline_ref | 工程基线的 `baseline_id` / `baseline_version`；切片不得重新定义质量标准 |
+| context_plan | 必需上下文、按需上下文、停止规则和缺失动作 |
+| doubt_driven_review | 高风险影响的主张、反证、证据、残余风险和审查引用；未命中时 `not-applicable` |
 
 | 不适用 skill | 原因 |
 |---|---|
 |  |  |
 
+### Context Plan（上下文工程）
+
+| 字段 | 内容 |
+|---|---|
+| required_context_refs | `CONTEXT.md`、已批准 Spec、当前 Slice Contract、适用 ADR / 工程基线 |
+| on_demand_context_refs | 命中影响面后再加载的专项 references、实现仓库文件和历史证据 |
+| context_stop_rule | `minimal-sufficient-evidence` |
+| missing_context_action | `blocked` / `reroute`；不得猜测补齐 |
+
+### Doubt-Driven 高风险反证
+
+| 字段 | 内容 |
+|---|---|
+| status | `not-applicable` / `required` / `completed` / `blocked` |
+| trigger_impacts | API、数据迁移、跨仓契约、发布回滚、实际安全行为、生命周期 / 生成语义 |
+| claim / counterclaim |  |  |
+| evidence_refs |  |
+| residual_risks |  |
+| reviewer_ref |  |
+
 ## 3. YSS skill 最小集合
 
 | 领域 | skill | 使用原因 | 是否必需 |

package/template/docs/user-guide//346/210/230/346/234/257/350/256/276/350/256/241/345/255/220/351/241/271/347/233/256/347/224/250/346/210/267/346/211/213/345/206/214.md

@@ -0,0 +1,218 @@
+# 战术设计子项目用户手册
+
+第一次接触 Tactical Design，不需要先会写代码，也不需要背诵 DDD 术语。
+
+这本手册把已经确认的 Strategic Design Handoff，继续细化成研发团队可以实现、测试和评审的领域模型。全文使用虚构的“客户合同审批”作为例子；示例只用于学习，不要把示例名称直接写入真实项目。
+
+## 这本手册适合谁
+
+- 产品经理、业务专家：想知道业务规则在技术设计中如何被保护。
+- 架构师、开发者：需要把业务边界细化为聚合、状态和一致性规则。
+- 测试人员：需要找到可以独立验证的领域行为。
+- AI Agent 操作者：需要知道何时让 Agent 起草、何时要求人工确认、何时必须停下。
+
+不懂代码也可以读完“业务读者篇”；“研发接手篇”会出现少量工程术语，但每个术语都会先用白话解释。
+
+## 看完能做什么
+
+1. 说清 Strategic Design 和 Tactical Design 的分工。
+2. 判断轻量 `Tactical DDD Check` 是否足够，还是需要独立的 Tactical Design 产物。
+3. 把一个业务场景拆成聚合、Entity、Value Object、领域服务和领域事件。
+4. 说明不变量、一致性边界、Repository / Gateway 和 API 的隔离方式。
+5. 形成可评审、可测试、可交给实现团队的战术设计结果。
+
+## 先记住：它解决什么问题
+
+Strategic Design 解决“业务应该怎样分工和划边界”；Tactical Design 解决“在一个边界里面，具体由哪些对象协作，以及规则如何不被破坏”。
+
+| 工作 | 大白话 | 典型结果 |
+|---|---|---|
+| Strategic Design | 决定业务地图和上下文边界 | 子域、限界上下文、统一语言、Context Map |
+| Tactical Design | 决定一个上下文内部怎样组织规则 | 聚合、状态机、不变量、领域服务、领域事件 |
+| 工程实现 | 把设计变成可运行的软件 | OpenAPI、代码、数据映射、测试和发布 |
+
+本手册的终点是“战术设计已评审并可交给实现”；OpenAPI Freeze、代码和发布仍由下游研发流程负责。
+
+## 开始前：确认输入和仓库身份
+
+### 输入必须来自已确认的交接包
+
+开始前应能找到批准且版本当前的 `Strategic Design Handoff`，其中至少包括：
+
+- 已确认的业务术语和上下文边界；
+- 关键场景、业务不变量和领域事件候选；
+- Spec、原型或业务级 Ticket 的版本引用；
+- 交给 Tactical Design 裁决的问题，例如聚合边界、状态、一致性和持久化；
+- 未决问题、责任人和后续验证计划。
+
+如果交接包缺失、过期或与当前 Spec 不一致，先回到上游处理，不要凭经验补写模型。
+
+### 确认项目实例
+
+打开项目根目录的 `yss-project.yaml`：
+
+| 配置 | 含义 | 处理方式 |
+|---|---|---|
+| `repository_mode: project-instance` | 真实业务项目 | 可以记录真实战术设计 |
+| `repository_mode: template-source` | 模板源 | 只能维护通用模板，不能写具体产品模型 |
+| 文件缺失或值不合法 | 身份不清楚 | 先停止并做迁移检查 |
+
+在项目实例中，先让 Agent 只读分诊：
+
+```text
+使用 yss-product-lifecycle，以 route 模式检查“客户合同审批”的 Tactical Design 输入。
+请先读取 yss-project.yaml、CONTEXT.md、Strategic Design Handoff 和当前已有架构资料。
+本轮只读，不要修改文件。请用普通话告诉我：
+1. 上游交接包是否批准且仍然有效；
+2. 当前是轻量 Tactical DDD Check 还是需要独立 Tactical Design；
+3. 已确认、待确认和冲突的业务规则分别是什么；
+4. 下一步只做哪一件事。
+正式 ID 放在普通话解释后面。
+```
+
+## 业务读者篇：用白话理解核心概念
+
+### 1. 聚合（Aggregate）
+
+聚合是一组必须一起守规则的对象。聚合根是这组对象对外唯一的入口；外部不能绕过聚合根直接修改内部对象。
+
+例子：一次“客户合同审批”可以由 `Contract` 聚合根管理审批状态和审批记录。审批记录如果只能随合同一起新增、退回和查询，就可以放在这个聚合内；不相关的通知不要硬塞进来。
+
+判断一个对象是否属于同一聚合，可以问：
+
+- 这些数据是否必须在同一次事务中保持一致？
+- 修改其中一个对象时，是否必须立即检查另一个对象？
+- 聚合变得很大后，是否会造成锁、并发或性能问题？
+
+不要按数据库表的外键关系画聚合；表关系图和业务一致性边界不是一回事。
+
+### 2. Entity（实体）
+
+实体有自己的身份，即使其他属性变化，它仍然是“同一个东西”。例如合同有 `contractId`，合同名称或金额修改后仍是同一份合同。
+
+### 3. Value Object（值对象）
+
+值对象由它的值决定身份，没有单独的业务身份。例如合同金额、客户地址、审批意见或时间范围。两个值完全相同的金额可以互相替换；值对象通常应尽量不可变。
+
+### 4. 不变量（Invariant）
+
+不变量是无论哪条入口执行，都不能被破坏的规则。例如：
+
+- 合同资料完整且校验通过后才能提交审批；
+- 已通过审批的合同不能直接改回草稿；
+- 同一份合同不能同时存在两个正在处理的审批流程；
+- 每次审批都必须留下操作人、时间、动作和意见。
+
+每条不变量都要能对应至少一个测试场景。不要把“页面上有一个发布按钮”当成不变量。
+
+### 5. 状态机
+
+状态机把允许的状态变化写清楚。合同示例：`草稿 → 待审批 → 审批中 → 已通过`；审批人退回时回到“草稿”，但“已通过”不能直接回到“草稿”。
+
+| 当前状态 | 动作 | 下一状态 | 必须满足 |
+|---|---|---|---|
+| 草稿 | 提交审批 | 待审批 | 合同资料完整 |
+| 待审批 | 审批人接单 | 审批中 | 已分配审批人 |
+| 审批中 | 审批通过 | 已通过 | 规则检查通过 |
+| 审批中 | 退回 | 草稿 | 必须填写退回原因 |
+| 已通过 | 修改 | 不允许 | 创建新的合同草稿 |
+
+### 6. 领域服务（Domain Service）
+
+当一条业务规则不自然属于某个实体，或需要协调多个聚合时，可以使用领域服务。领域服务只表达业务决策，不负责 HTTP、数据库连接或页面跳转。
+
+### 7. 领域事件（Domain Event）
+
+领域事件记录“业务上已经发生了什么”，例如 `ContractApproved`。它适合通知订阅者、触发异步处理或留下审计线索；事件名称应使用业务语言，不要直接暴露数据库表名。
+
+## 研发接手篇：从场景形成战术设计
+
+### 第一步：从用户场景开始，不从类名开始
+
+以“提交客户合同审批”为例，先写出：谁发起、前置条件、动作、结果、失败方式和后续影响。
+
+```text
+角色：销售人员
+前置条件：合同资料完整，且当前没有正在处理的审批流程
+动作：提交合同审批
+成功：合同进入“待审批”，产生 ContractSubmitted 事件
+失败：保留原状态，返回可理解的失败原因
+```
+
+### 第二步：列出规则并划一致性边界
+
+把规则分成“必须立即成立”和“可以稍后完成”：
+
+| 规则 | 一致性要求 | 设计提示 |
+|---|---|---|
+| 提交前资料必须完整 | 立即成立 | 放在合同聚合的不变量中 |
+| 同一合同不能重复提交 | 立即成立 | 由聚合 + Repository 检查并发冲突 |
+| 审批结果通知销售 | 可稍后完成 | 审批完成后发送领域事件 |
+| 统计报表更新 | 可稍后完成 | 使用异步订阅，不阻塞审批事务 |
+
+跨聚合流程由 Application 编排；核心规则仍放在 Domain。不要把所有规则塞进 Controller 或 Application Service。
+
+### 第三步：画出对象职责，而不是字段清单
+
+至少记录以下内容：
+
+| 对象 | 类型 | 负责什么 | 不负责什么 |
+|---|---|---|---|
+| `Contract` | Aggregate Root / Entity | 状态变化、提交前检查 | 发送 HTTP、直接操作表 |
+| `ApprovalRecord` | Entity 或 Value Object（需裁决） | 表达审批动作、意见和时间 | 决定整个流程 |
+| `ApproveContract` | Domain Service（必要时） | 协调跨对象的审批规则 | 事务提交和接口适配 |
+| `ContractRepository` | Repository seam | 保存和加载聚合 | 对外暴露数据库结构 |
+| `ContractApproved` | Domain Event | 描述审批已通过 | 代替主事务中的规则检查 |
+
+“Value Object 还是 Entity”不是凭习惯决定的：如果版本需要独立追踪身份、生命周期或并发操作，可能是 Entity；如果它只是不可变的版本值，可能是 Value Object。把裁决理由写下来。
+
+### 第四步：隔离 Repository、Gateway 和 API
+
+- `Repository` 面向领域模型的保存 / 加载，不让领域层依赖 ORM 或表结构。
+- `Gateway` 面向外部系统能力，例如通知、文件存储或规则服务；领域层只依赖抽象接口。
+- API schema 面向调用方，不直接暴露聚合内部对象、Repository 或持久化表。
+- Application 负责用例编排、事务边界和跨聚合协调；Domain 负责核心业务规则。
+
+### 第五步：写测试 seam
+
+每条关键规则都要有可执行的验证入口：
+
+- 聚合行为测试：给定状态和动作，验证状态变化或拒绝原因；
+- Repository / Gateway 契约测试：验证抽象接口的输入输出；
+- Application 用例测试：验证事务边界和跨聚合协调；
+- API 契约测试：验证公开 wire shape，不验证内部类名。
+
+## 什么时候需要独立 Tactical Design
+
+大多数简单变更，在系统概要设计中的 `Tactical DDD Check` 写清楚即可。只有当以下内容复杂到无法在一节中审查时，才升级为独立 Tactical Design 产物：
+
+- 多个聚合之间有复杂的一致性或并发规则；
+- 状态机有分支、补偿、重试或不可逆状态；
+- 持久化映射会隐藏或破坏领域边界；
+- Gateway、领域事件或最终一致性需要明确时序；
+- 评审者无法仅凭概要设计复现关键业务行为。
+
+升级不是为了增加文档数量，而是为了让复杂决策可读、可测试、可追责。无论采用轻量检查还是独立文档，都必须引用同一份 `tactical-design` contract 和 `evidence.tactical-design-review`，不能产生两套互相矛盾的事实源。
+
+## 评审前自检
+
+- [ ] 输入来自批准且版本当前的 `Strategic Design Handoff`。
+- [ ] 统一语言与 `CONTEXT.md` 一致，没有临时创造同义词。
+- [ ] 聚合根、Entity、Value Object 的身份和边界有理由。
+- [ ] 每个聚合的不变量和允许的状态转换都写清楚。
+- [ ] 一致性规则区分了立即成立与最终一致。
+- [ ] Application、Domain、Repository、Gateway 和 API 的职责没有混淆。
+- [ ] 领域事件表达业务事实，不暴露内部表结构。
+- [ ] 关键规则都有测试 seam 和失败场景。
+- [ ] 已判断轻量 `Tactical DDD Check` 是否足够；需要升级时写明原因。
+- [ ] 未决问题有负责人、后续 Ticket、验证计划和目标版本。
+
+## 与其他文档怎么分工
+
+- [用户手册索引](./用户手册索引.md)：所有入门手册的入口。
+- [战略设计子项目用户手册](../../submodules/yss-strategic-design-harness/docs/user-guide/战略设计子项目用户手册.md)：上游 Discovery、DDD 战略设计、Spec、原型和 Strategic Design Handoff。
+- [系统概要设计模板](../architecture/templates/system-overview-design-template.md)：轻量 Tactical DDD Check 的记录位置。
+- [架构评审清单](../architecture/templates/architecture-review-checklist.md)：设计评审时的结构化检查项。
+- `yss-router` 与后端 / 前端专项技能：批准后的实现合同、代码和验证规则。
+
+本手册是模板源中的通用分发资产。真实项目应使用自己的术语、规则、合同版本和批准记录；不要把“客户合同审批”示例当成真实业务结论。

package/template/docs/user-guide//347/224/250/346/210/267/346/211/213/345/206/214.md

@@ -173,6 +173,60 @@ CLI 初始化、接管或同步成功后，再准备：
 每完成一步，请告诉我改了什么、证据在哪里、下一步是什么。
 ```
 
+## 可选：使用个人 Codex Plugin
+
+本节介绍的是个人、本机的可选工具，不属于 YSS 模板交付物。它不会自动安装到其他成员的环境，也不会改变项目的事实源、生命周期阶段或门禁。
+
+### 适合谁
+
+当前示例插件 `yss-backend-harness` 只服务后端工程角色。产品、项目、前端和测试角色应使用各自职责对应的工具或 Plugin，不要把后端插件当成全团队通用插件。
+
+### 安装和触发
+
+在已经安装 Codex、并且本机存在 `personal` marketplace 的环境中执行：
+
+```bash
+codex plugin add yss-backend-harness@personal
+```
+
+安装后刷新或重启 Codex，再在已登记的实现仓库中调用。例如：
+
+```text
+请读取当前 YSS 任务包和 Slice Contract，按 role.backend-engineer 生成或执行后端任务。
+```
+
+插件只能在以下条件满足后执行具体实现：
+
+- 仓库是 `project-instance`，不是 `template-source`；
+- 实现仓库、项目根目录、分支和验证命令已经登记；
+- OpenAPI 已 Freeze，或已记录无 API 影响；
+- Slice Contract 已批准并处于 `ready-for-agent`；
+- 任务包明确了允许写入的路径、行为和测试 seam。
+
+### 插件不会替代什么
+
+Plugin 是运行时适配器，不是新的事实源。它不会替代 `yss-product-lifecycle`、`yss-router` 或 `tdd`，不会设置 `ready-for-agent`，不会 Freeze OpenAPI，也不能承担独立审查。
+
+执行结果应包含 `Workflow Execution Result`（例如 `completed`、`blocked`、`needs-human` 或 `failed`）及对应证据。发现路径越界、合同过期、影响面变化或证据缺失时，应停止并回到路由流程。
+
+### 不可用时怎么办
+
+如果插件未安装、版本不兼容或执行失败，回退到通用的 `yss-router + tdd` 流程，并记录阻塞原因和实际验证命令。不要为了绕过插件故障而跳过生命周期门禁。
+
+### 其他应用的接入建议
+
+应用接入按项目需要逐步增加，不作为模板默认依赖：
+
+1. GitHub 或 GitLab：代码、分支、MR/PR 和 CI。
+2. Jira 或 Linear：父 Ticket、Slice Ticket、状态和责任人。
+3. GitHub Actions、GitLab CI 或 Jenkins：自动执行模板、前端和后端验证。
+4. Confluence、Notion 或飞书文档：团队说明和知识库，但不得替代仓库事实源。
+5. Figma：仅在产品设计和 UI 实现阶段接入。
+6. Slack、Teams 或企业微信：仅发送阻塞、审查和发布通知，不承载正式决策。
+7. Sentry、Grafana 或 Datadog：仅在具体产品实例上线后接入运行监控。
+
+推荐顺序是：本地 Git + Codex/Plugin → Git 平台 → Issue tracker → CI/CD → 知识库 → 设计、通知和监控。
+
 ## 一张表看懂完整路线
 
 | 你要解决的问题 | 正式阶段 | 完成后应该看到什么 |
@@ -630,12 +684,11 @@ ADR 是架构决策记录。
 | 角色 | 提前参与什么 | 交付前重点检查 |
 |---|---|---|
 | 需求经理 | 用户、范围、术语、成功标准 | Spec 是否还能被业务复述 |
-| 产品经理 | 优先级、页面流、状态和原型 | 实现是否偏离已确认体验 |
+| 产品经理 | 优先级、页面流、状态、原型及商业约束、交付承诺和发布窗口 | 实现是否偏离已确认体验；对外承诺是否经过生物人批准 |
 | 前端工程师 | 原型可行性、API 是否好用 | 页面状态、截图、console、`pnpm` |
 | 后端工程师 | API、数据、领域规则、工程准备 | 行为测试、契约、`./mvnw` |
 | 测试工程师 | 测试入口、异常和恢复路径 | 独立审查、当次验证 |
 | 项目经理 | Ticket、依赖、仓库和风险 | 候选、发布顺序和回滚点 |
-| 商务 | 商业约束和交付窗口 | 对外承诺是否与实际范围一致 |
 
 角色可以由不同 Agent 运行时承载。实现者不能审查自己的候选。
 

package/template/docs/user-guide//347/224/250/346/210/267/346/211/213/345/206/214/347/264/242/345/274/225.md

@@ -0,0 +1,21 @@
+# 用户手册索引
+
+这里集中放置 YSS 模板和生命周期的入门手册。第一次使用时，先看总览，再进入与你当前工作阶段对应的子项目手册。
+
+## 推荐阅读顺序
+
+1. [YSS 用户手册](./用户手册.md)：了解仓库身份、生命周期主链和 Agent 使用模式。
+2. [战略设计子项目用户手册](../../submodules/yss-strategic-design-harness/docs/user-guide/战略设计子项目用户手册.md)：从模糊想法形成 Strategic Design Handoff。
+3. [战术设计子项目用户手册](./战术设计子项目用户手册.md)：把交接包细化为 Tactical Design，供研发实现和评审。
+
+## 按任务查找
+
+| 你现在要做什么 | 推荐手册 |
+|---|---|
+| 创建、接管或更新 YSS 项目 | [YSS 用户手册](./用户手册.md) |
+| 澄清需求、确定用户和范围 | [战略设计子项目用户手册](../../submodules/yss-strategic-design-harness/docs/user-guide/战略设计子项目用户手册.md) |
+| 设计聚合、状态、不变量和领域事件 | [战术设计子项目用户手册](./战术设计子项目用户手册.md) |
+| 了解完整生命周期和阶段门禁 | [产品生命周期工作流](../../submodules/yss-strategic-design-harness/docs/user-guide/产品生命周期工作流.md) |
+| 查找长期协作习惯和反模式 | [生命周期最佳实践](../../submodules/yss-strategic-design-harness/docs/user-guide/生命周期最佳实践.md) |
+
+> 本仓库是 `template-source`。手册中的业务名称和示例只用于教学；真实产品资料应在 `project-instance` 中建立，并遵守对应的生命周期门禁。

package/template/scripts/lib/digital-human-roles.mjs

@@ -12,7 +12,6 @@ const RUNTIME_ID = /^runtime\.[a-z0-9][a-z0-9-]*$/;
 const REQUIRED_ROLES = [
   "role.requirements-manager",
   "role.product-manager",
-  "role.business",
   "role.project-manager",
   "role.frontend-engineer",
   "role.backend-engineer",

package/template/scripts/lib/skill-registry.mjs

@@ -9,6 +9,7 @@ const ROUTER_CONTRACT = path.join(ROOT, ".agents/skills/yss-router/references/ro
 const LIFECYCLE_CONTRACT = path.join(ROOT, ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml");
 const LAYERS = new Set(["core", "specialist", "compatibility", "maintainer-only"]);
 const MATURITIES = new Set(["draft", "verified", "supported", "deprecated"]);
+const INVOCATION_MODES = new Set(["user", "model", "both"]);
 const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const PLATFORM_ALIAS_PATTERN = /^[a-z0-9][a-z0-9-]*(?::[a-z0-9][a-z0-9-]*)?$/;
 
@@ -51,6 +52,74 @@ function requireObject(value, field) {
   if (!value || typeof value !== "object" || Array.isArray(value)) fail(`${field} 必须是对象`);
 }
 
+function requireStringArray(value, field, { nonEmpty = false } = {}) {
+  if (!Array.isArray(value) || (nonEmpty && value.length === 0) || value.some((item) => typeof item !== "string" || !item.trim())) {
+    fail(`${field} 必须是${nonEmpty ? "非空" : ""}字符串数组`);
+  }
+}
+
+function validateInvocationContract(registry, skill) {
+  const contract = registry.invocation_contract;
+  requireObject(contract, "invocation_contract");
+  if (contract.schema_version !== 1) fail("invocation_contract.schema_version 必须为 1");
+  if (contract.scope !== "routing-and-dependencies-only") fail("invocation_contract.scope 必须限定为 routing-and-dependencies-only");
+  requireStringArray(contract.required_fields, "invocation_contract.required_fields", { nonEmpty: true });
+  const expected = ["invocation_mode", "trigger_conditions", "exclusion_conditions", "primary_output", "required_dependencies", "optional_dependencies"];
+  if (JSON.stringify(contract.required_fields) !== JSON.stringify(expected)) fail("invocation_contract.required_fields 顺序或字段不完整");
+  requireStringArray(contract.allowed_invocation_modes, "invocation_contract.allowed_invocation_modes", { nonEmpty: true });
+  if (![...INVOCATION_MODES].every((mode) => contract.allowed_invocation_modes.includes(mode))) {
+    fail("invocation_contract.allowed_invocation_modes 必须包含 user、model、both");
+  }
+  if (contract.trigger_source !== "impacts" || contract.trigger_encoding !== "impact:<impact>") {
+    fail("invocation_contract 必须从 impacts 生成 impact:<impact> 触发条件");
+  }
+  requireObject(contract.default, "invocation_contract.default");
+  requireObject(contract.layer_defaults, "invocation_contract.layer_defaults");
+  requireObject(contract.overrides, "invocation_contract.overrides");
+  for (const layer of LAYERS) {
+    const layerDefault = contract.layer_defaults[layer];
+    requireObject(layerDefault, `invocation_contract.layer_defaults.${layer}`);
+    if (!INVOCATION_MODES.has(layerDefault.invocation_mode)) fail(`${layer} 的 invocation_mode 无效`);
+    requireString(layerDefault.primary_output, `invocation_contract.layer_defaults.${layer}.primary_output`);
+  }
+  const defaultMode = contract.default.invocation_mode;
+  if (!INVOCATION_MODES.has(defaultMode)) fail("invocation_contract.default.invocation_mode 无效");
+  requireStringArray(contract.default.trigger_conditions, "invocation_contract.default.trigger_conditions", { nonEmpty: true });
+  requireStringArray(contract.default.exclusion_conditions, "invocation_contract.default.exclusion_conditions", { nonEmpty: true });
+  requireString(contract.default.primary_output, "invocation_contract.default.primary_output");
+  requireStringArray(contract.default.required_dependencies, "invocation_contract.default.required_dependencies");
+  requireStringArray(contract.default.optional_dependencies, "invocation_contract.default.optional_dependencies");
+  for (const [skillId, override] of Object.entries(contract.overrides)) {
+    requireObject(override, `invocation_contract.overrides.${skillId}`);
+    if (!ID_PATTERN.test(skillId)) fail(`invocation_contract.overrides id 非法: ${skillId}`);
+    if (override.invocation_mode && !INVOCATION_MODES.has(override.invocation_mode)) fail(`${skillId}.invocation_mode 无效`);
+    if (override.trigger_conditions) requireStringArray(override.trigger_conditions, `${skillId}.trigger_conditions`, { nonEmpty: true });
+    if (override.exclusion_conditions) requireStringArray(override.exclusion_conditions, `${skillId}.exclusion_conditions`, { nonEmpty: true });
+    if (override.primary_output) requireString(override.primary_output, `${skillId}.primary_output`);
+    if (override.required_dependencies) requireStringArray(override.required_dependencies, `${skillId}.required_dependencies`);
+    if (override.optional_dependencies) requireStringArray(override.optional_dependencies, `${skillId}.optional_dependencies`);
+  }
+  const overrideIds = Object.keys(contract.overrides);
+  const knownIds = new Set(registry.skills.map((item) => item?.id).filter(Boolean));
+  for (const skillId of overrideIds) if (!knownIds.has(skillId)) fail(`invocation_contract.overrides 引用了未登记技能: ${skillId}`);
+  const effective = {
+    ...contract.default,
+    ...contract.layer_defaults[skill.layer],
+    ...(contract.overrides[skill.id] ?? {})
+  };
+  effective.trigger_conditions = [...new Set([...(effective.trigger_conditions ?? []), ...skill.impacts.map((impact) => `impact:${impact}`)])];
+  if (!INVOCATION_MODES.has(effective.invocation_mode)) fail(`${skill.id}.invocation_mode 无效`);
+  requireStringArray(effective.trigger_conditions, `${skill.id}.trigger_conditions`, { nonEmpty: true });
+  requireStringArray(effective.exclusion_conditions, `${skill.id}.exclusion_conditions`, { nonEmpty: true });
+  requireString(effective.primary_output, `${skill.id}.primary_output`);
+  requireStringArray(effective.required_dependencies, `${skill.id}.required_dependencies`);
+  requireStringArray(effective.optional_dependencies, `${skill.id}.optional_dependencies`);
+  const impactTriggers = skill.impacts.map((impact) => `impact:${impact}`);
+  if (!impactTriggers.every((trigger) => effective.trigger_conditions.includes(trigger))) {
+    fail(`${skill.id} 的调用契约必须覆盖其 impacts 触发条件`);
+  }
+}
+
 function requireStringSet(value, expected, field) {
   if (!Array.isArray(value)) fail(`${field} 必须是数组`);
   const missing = expected.filter((item) => !value.includes(item));
@@ -209,6 +278,7 @@ export function validateSkillRegistry(registry, { lock, routerContract, lifecycl
     if (!Array.isArray(skill.impacts) || skill.impacts.length === 0 || skill.impacts.some((item) => typeof item !== "string" || !item.trim())) {
       fail(`${skill.id} impacts 不能为空`);
     }
+    validateInvocationContract(registry, skill);
   }
   for (const skill of skills) {
     if (skill.replaced_by && !ids.has(skill.replaced_by)) fail(`${skill.id}.replaced_by 引用了未登记技能: ${skill.replaced_by}`);

package/template/scripts/verify-digital-human-roles-scenarios

@@ -54,7 +54,7 @@ const seven = [
   "role.lifecycle-orchestrator",
   "role.requirements-manager",
   "role.product-manager",
-  "role.business",
+  "role.project-manager",
   "role.frontend-engineer",
   "role.backend-engineer",
   "role.test-engineer"

package/template/skills-lock.json

@@ -1420,7 +1420,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-product-lifecycle/SKILL.md",
-        "effectiveHash": "71b42d70464a1d05bc87270e21b0d0167ef5b7ebd2a9f84dd27eac6407660ec3",
+        "effectiveHash": "a7283ff14706ed156d0ed4eea619407b9758e3f2dca521f112ab4bcdfad46f57",
         "targets": [
           ".agents/skills",
           ".claude/skills",
@@ -1484,7 +1484,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-router/SKILL.md",
-        "effectiveHash": "51842166ff9c3a64f4a0f357f5a669323d4f944ed5805edc44c0c20e54f510d0",
+        "effectiveHash": "7b1cd0ed4fc3b99a313e125d68f2e7e9bbbf53b4369085575ba06f4d2872a3ca",
         "targets": [
           ".agents/skills",
           ".claude/skills",

package/template.manifest.json

@@ -18,6 +18,7 @@
     "AGENTS.md",
     "CLAUDE.md",
     "CONTEXT.md",
+    "DESIGN.md",
     "README.md",
     "skills-lock.json",
     "yss-project.yaml",

package/template.snapshot.json

@@ -3,15 +3,15 @@
   "templateName": "yss-spec-project-template",
   "templateSource": "github:iloveZzz/yss-spec-project-template",
   "templateRepository": "https://github.com/iloveZzz/yss-spec-project-template.git",
-  "requestedRef": "f9f97eb080519b3388be12fed07b2ce0e026b04b",
-  "templateCommit": "f9f97eb080519b3388be12fed07b2ce0e026b04b",
-  "manifestHash": "10d161eb3f0e426aeefad5d0b9e6c5522d8a4dbacb9edf6ed64285dcb40b1a65",
+  "requestedRef": "a7f2c1be9cb96569c1f6d41890edd72719a5f2af",
+  "templateCommit": "a7f2c1be9cb96569c1f6d41890edd72719a5f2af",
+  "manifestHash": "387b499e08cf3dfa03e08acbc5b5783ee287c61aca12d995c61e2140f5552f40",
   "encodedPaths": {
     ".codex/skills/data-analytics/.gitignore": ".codex/skills/data-analytics/__yss_dotfile__.gitignore",
     ".codex/skills/product-design/.npmignore": ".codex/skills/product-design/__yss_dotfile__.npmignore",
     ".codex/skills/product-design/templates/prototype/.npmrc": ".codex/skills/product-design/templates/prototype/__yss_dotfile__.npmrc",
     ".gitignore": "__yss_dotfile__.gitignore"
   },
-  "snapshotHash": "c3bc9bef3468faa067fc44b9bd38711cb642536c724f2168fe8a72e40301f3d5",
-  "generatedAt": "2026-09-01T17:17:08.650Z"
+  "snapshotHash": "9c3b6db377c9fc29f0ae947bcad5eb7ae181e1027fd2cc7b17cd000759a9ac59",
+  "generatedAt": "2026-09-02T16:32:00.623Z"
 }