create-yss-spec 3.1.0 → 3.1.3

package/template/docs/process/schemas/digital-human-task-package.schema.json

@@ -7,6 +7,14 @@
   "required": ["schema_version", "task_id", "work_unit_id", "actor_id", "role_id", "runtime_id", "execution_state", "workflow_status", "skill_source", "contract", "inputs", "objective", "allowed_write_paths", "forbidden_actions", "expected_outputs", "expected_evidence_files", "verification_commands", "verification_results", "downstream_consumers", "convergence"],
   "properties": {
     "schema_version": { "const": 1 },
+    "frontend_delivery": {
+      "type": "object", "additionalProperties": false, "required": ["acceptance_ref"],
+      "properties": {
+        "acceptance_ref": { "type": "string", "minLength": 1 },
+        "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+      }
+    },
+    "slice_id": { "type": "string", "minLength": 1 },
     "task_id": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" },
     "work_unit_id": { "type": "string", "minLength": 1, "pattern": "^work-unit\\.[a-z0-9][a-z0-9-]*$" },
     "actor_id": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]*$" },

package/template/docs/process/schemas/frontend-delivery-acceptance.schema.json

@@ -0,0 +1,200 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "status": {
+      "const": "accepted"
+    },
+    "slice_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "backend_delivery": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "import_receipt_ref": {
+          "type": "string",
+          "minLength": 1
+        },
+        "bundle_digest": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        }
+      },
+      "required": [
+        "import_receipt_ref",
+        "bundle_digest"
+      ]
+    },
+    "strategic_handoff": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "import_receipt_ref": {
+          "type": "string",
+          "minLength": 1
+        },
+        "bundle_digest": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "context_reconciliation_ref": {
+          "type": "string",
+          "minLength": 1
+        },
+        "rows": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "source_id",
+              "source_digest",
+              "disposition",
+              "dependency_status",
+              "dependent_slice_refs",
+              "evidence_refs"
+            ],
+            "properties": {
+              "source_id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "source_digest": {
+                "type": "string",
+                "pattern": "^sha256:[0-9a-f]{64}$"
+              },
+              "disposition": {
+                "enum": [
+                  "mapped",
+                  "pending",
+                  "conflict",
+                  "deferred",
+                  "not-applicable"
+                ]
+              },
+              "dependency_status": {
+                "enum": [
+                  "known",
+                  "unknown"
+                ]
+              },
+              "dependent_slice_refs": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "minItems": 0,
+                "uniqueItems": true
+              },
+              "evidence_refs": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "minItems": 0,
+                "uniqueItems": true
+              },
+              "frontend_case_refs": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "minItems": 0,
+                "uniqueItems": true
+              }
+            }
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      },
+      "required": [
+        "import_receipt_ref",
+        "bundle_digest",
+        "context_reconciliation_ref",
+        "rows"
+      ]
+    },
+    "frontend_cases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "case_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "source_ids": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "minItems": 1,
+            "uniqueItems": true
+          },
+          "outcome": {
+            "enum": [
+              "success",
+              "failure"
+            ]
+          },
+          "operation_ids": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "minItems": 1,
+            "uniqueItems": true
+          },
+          "visual_case_ids": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "minItems": 1,
+            "uniqueItems": true
+          },
+          "evidence_ref": {
+            "type": "string",
+            "minLength": 1
+          },
+          "evidence_digest": {
+            "type": "string",
+            "pattern": "^sha256:[a-f0-9]{64}$"
+          }
+        },
+        "required": [
+          "case_id",
+          "source_ids",
+          "outcome",
+          "operation_ids",
+          "visual_case_ids",
+          "evidence_ref",
+          "evidence_digest"
+        ]
+      },
+      "minItems": 1,
+      "uniqueItems": true
+    }
+  },
+  "required": [
+    "schema_version",
+    "status",
+    "slice_id",
+    "backend_delivery",
+    "strategic_handoff",
+    "frontend_cases"
+  ]
+}

package/template/docs/process/schemas/frontend-implementation-evidence.schema.json

@@ -6,6 +6,9 @@
   "additionalProperties": false,
   "required": ["schema_version", "kind", "template", "status", "prototype_ref", "spec_ref", "visual_baseline", "route_and_page_inventory", "pnpm_commands"],
   "properties": {
+    "frontend_delivery": {"type":"object","additionalProperties":false,"required":["acceptance_ref","digest"],"properties":{"acceptance_ref":{"type":"string","minLength":1},"digest":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"}}},
+    "slice_id": {"type":"string","minLength":1},
+    "slice_contract_ref": {"type":"string","minLength":1},
     "schema_version": {"const": 2},
     "kind": {"enum": ["plan", "verification"]},
     "template": {"type": "boolean"},

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

@@ -191,6 +191,8 @@ syntax_files:
   - scripts/verify-maintenance-review-workflow-scenarios
   - scripts/verify-template-cache-scenarios
 routing:
+  - patterns: ["scripts/*backend-delivery*", "scripts/*frontend-delivery*", "scripts/lib/*backend-delivery*", "scripts/lib/*frontend-delivery*", "scripts/fixtures/backend-delivery/**", "docs/process/frontend-backend-delivery.md", "docs/process/schemas/backend-delivery*", "docs/process/schemas/frontend-delivery*"]
+    groups: [frontend-delivery]
   - patterns: ["scripts/*user-decision*", "scripts/lib/user-decision*", "scripts/fixtures/user-decision/**", "docs/process/schemas/user-decision*", "docs/process/templates/user-decision*", "scripts/lib/approval-record.mjs", "scripts/verify-approval-record"]
     groups: [lifecycle, collaboration]
   - patterns: ["scripts/*strategic-handoff*", "scripts/lib/strategic-handoff*", "scripts/fixtures/strategic-handoff/**", "docs/process/strategic-handoff-package.md", "docs/process/schemas/strategic-handoff-*"]
@@ -228,6 +230,10 @@ routing:
   - patterns: ["scripts/**"]
     groups: [hygiene]
 groups:
+  frontend-delivery:
+    commands:
+      - { run: "scripts/verify-frontend-delivery-scenarios" }
+      - { run: "node .template-source/scripts/verify-delivery-harness-distribution.mjs", when: template-source }
   strategic-handoff-package:
     commands:
       - { run: "node --check scripts/lib/strategic-handoff.mjs" }

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

@@ -1,220 +1,34 @@
 # 战术设计子项目用户手册
 
-第一次接触 Tactical Design，不需要先会写代码，也不需要背诵 DDD 术语。
+本入口保留给既有读者。Tactical Design 把已批准业务规则映射为聚合、状态、不变量、一致性边界和测试 seam；它不是新的模板家族，不代替 API Freeze 或 Slice Contract 批准。
 
-这本手册把已经确认的 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 裁决的问题，例如聚合边界、状态、一致性和持久化；
-- 未决问题、责任人和后续验证计划。
-- `source_context_snapshot` 与包含术语定义的 `context_delta`，以及“目标仓在 Tactical Design 前完成 `context_reconciliation`”的约束。
-
-先把 `context_delta` 对账到当前项目根目录唯一 `CONTEXT.md`，生成目标侧 reconciliation，并运行 `scripts/verify-strategic-context-import --root . --reconciliation <record> <handoff>`。如果交接包缺失、仍为 v1、过期、摘要漂移或与当前 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`。它适合通知订阅者、触发异步处理或留下审计线索；事件名称应使用业务语言，不要直接暴露数据库表名。
-
-## 研发接手篇：从场景形成战术设计
-
-### 第一步：从用户场景开始，不从类名开始
-
-以“提交客户合同审批”为例，先写出：谁发起、前置条件、动作、结果、失败方式和后续影响。
+先核对本仓身份、profile、根 CONTEXT.md、当前战略交接及批准证据。导入快照后完成目标词汇对账，再逐项登记源规则/关键场景的承接；缺失、冲突或过期先回交，不能猜测业务规则。
 
 ```text
-角色：销售人员
-前置条件：合同资料完整，且当前没有正在处理的审批流程
-动作：提交合同审批
-成功：合同进入“待审批”，产生 ContractSubmitted 事件
-失败：保留原状态，返回可理解的失败原因
+请按本仓生命周期检查“设备领用”当前战略输入及目标词汇对账。
+有领域行为影响时，使用 yss-tactical-design 起草战术设计，
+解释设备占用的竞争、状态转换和一致性边界，并映射公开测试 seam。
+逐项列出已承接、冲突、延期及依赖切片，等待适用审查后再编译实现合同。
 ```
 
-### 第二步：列出规则并划一致性边界
-
-把规则分成“必须立即成立”和“可以稍后完成”：
-
-| 规则 | 一致性要求 | 设计提示 |
-|---|---|---|
-| 提交前资料必须完整 | 立即成立 | 放在合同聚合的不变量中 |
-| 同一合同不能重复提交 | 立即成立 | 由聚合 + 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`，不能产生两套互相矛盾的事实源。
+| 设计问题 | 设备借用中的例子 |
+|---|---|
+| 谁保护不变量 | 哪个对象/边界保证设备不能同时被领用 |
+| 状态是否合法 | 未批准申请是否允许领用；重复归还如何处理 |
+| 一致性在哪里保证 | 申请与设备占用是否同事务；失败如何恢复 |
+| 外部依赖如何隔离 | API/Repository/Gateway 怎样映射而不篡改业务含义 |
+| 如何证伪设计 | 并发领用、无权限、重复请求的公开 seam 与预期结果 |
 
-## 评审前自检
+案例只是提问方向，答案由项目实际业务与工程条件决定。没有领域行为影响时按当前政策记录带原因的 not-applicable，不为简单页面硬造聚合。
 
-- [ ] 输入来自批准且版本当前的 `Strategic Design Handoff`。
-- [ ] Strategic Design Handoff 为 schema v2，目标根 `CONTEXT.md` 已完成 context delta 对账，`strategic_context_import_ref` 与 `context_reconciliation_ref` 均通过校验。
-- [ ] 统一语言与 `CONTEXT.md` 一致，没有临时创造同义词。
-- [ ] 聚合根、Entity、Value Object 的身份和边界有理由。
-- [ ] 每个聚合的不变量和允许的状态转换都写清楚。
-- [ ] 一致性规则区分了立即成立与最终一致。
-- [ ] Application、Domain、Repository、Gateway 和 API 的职责没有混淆。
-- [ ] 领域事件表达业务事实，不暴露内部表结构。
-- [ ] 关键规则都有测试 seam 和失败场景。
-- [ ] 已判断轻量 `Tactical DDD Check` 是否足够；需要升级时写明原因。
-- [ ] 未决问题有负责人、后续 Ticket、验证计划和目标版本。
+## 从设计到实现
 
-## 与其他文档怎么分工
+综合项目由本仓生命周期继续路由，通用研发/后端由 Harness 流程承接。前端专职只消费上游规则、冻结接口并准备前端工程设计，不在本仓派发后端战术实现。
 
-- [用户手册索引](./用户手册索引.md)：所有入门手册的入口。
-- [战略设计子项目用户手册](../../submodules/yss-harness-design-agent/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-implementation-contract-compiler` 与后端 / 前端专项技能：批准后的实现合同、代码和验证规则。
+编译器起草当前合同，批准与可实现状态由本仓编排和门禁控制。实现前确认工程登记、冻结接口、测试 seam、允许路径与回滚点。战术评审通过不等于 ready-for-agent。
 
-本手册是模板源中的通用分发资产。真实项目应使用自己的术语、规则、合同版本和批准记录；不要把“客户合同审批”示例当成真实业务结论。
+过程示例见 [设备借用贯穿案例](设备借用贯穿案例.md)；项目选型见 [用户手册](用户手册.md)。