create-yss-spec 3.0.1 → 3.1.3

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

@@ -1,21 +1,18 @@
 # 用户手册索引
 
-这里集中放置 YSS 模板和生命周期的入门手册。第一次使用时，先看总览，再进入与你当前工作阶段对应的子项目手册。
+## 第一次使用
 
-## 推荐阅读顺序
+1. [YSS 用户手册](用户手册.md)：五类项目选型、首次创建、确认与升级。
+2. [设备借用贯穿案例](设备借用贯穿案例.md)：输入、提示词、命令、成功标准及异常恢复。
+3. [战术设计指南](战术设计子项目用户手册.md)：批准战略如何落到设计和测试。
 
-1. [YSS 用户手册](./用户手册.md)：了解仓库身份、生命周期主链和 Agent 使用模式。
-2. [战略设计子项目用户手册](../../submodules/yss-harness-design-agent/docs/user-guide/战略设计子项目用户手册.md)：从模糊想法形成 Strategic Design Handoff。
-3. [战术设计子项目用户手册](./战术设计子项目用户手册.md)：把交接包细化为 Tactical Design，供研发实现和评审。
+## 专项路线
 
-## 按任务查找
+- [战略：澄清、设计、交接](https://github.com/iloveZzz/yss-harness-design-agent/blob/main/docs/user-guide/用户手册索引.md)
+- [通用研发：接收、合同、实现与验证](https://github.com/iloveZzz/yss-harness-dev-agent/blob/main/docs/user-guide/用户手册索引.md)
+- [后端：接口、实现与交付](https://github.com/iloveZzz/yss-harness-backend-agent/blob/main/docs/user-guide/用户手册索引.md)
+- [前端：联合接收、页面与验收](https://github.com/iloveZzz/yss-harness-frontend-agent/blob/main/docs/user-guide/用户手册索引.md)
 
-| 你现在要做什么 | 推荐手册 |
-|---|---|
-| 创建、接管或更新 YSS 项目 | [YSS 用户手册](./用户手册.md) |
-| 澄清需求、确定用户和范围 | [战略设计子项目用户手册](../../submodules/yss-harness-design-agent/docs/user-guide/战略设计子项目用户手册.md) |
-| 设计聚合、状态、不变量和领域事件 | [战术设计子项目用户手册](./战术设计子项目用户手册.md) |
-| 了解完整生命周期和阶段门禁 | [产品生命周期工作流](../../submodules/yss-harness-design-agent/docs/user-guide/产品生命周期工作流.md) |
-| 查找长期协作习惯和反模式 | [生命周期最佳实践](../../submodules/yss-harness-design-agent/docs/user-guide/生命周期最佳实践.md) |
+跨项目导航使用 GitHub 链接；生成实例不需要兄弟仓或 submodules 目录。链接指向各仓 main，实际执行仍核对本地 profile、包版本和固定模板 SHA。
 
-> 本仓库是 `template-source`。手册中的业务名称和示例只用于教学；真实产品资料应在 `project-instance` 中建立，并遵守对应的生命周期门禁。
+CLI 参数详解：[综合 CLI](https://github.com/iloveZzz/create-yss-spec/blob/main/docs/user-guide/create-yss-spec-cli-guide.md)、[战略 CLI](https://github.com/iloveZzz/create-yss-harness-design)、[研发 CLI](https://github.com/iloveZzz/create-yss-harness-dev)。组件工具专项见 [YSS UI MCP](yss-ui-mcp.md)。

package/template/docs/user-guide//350/256/276/345/244/207/345/200/237/347/224/250/350/264/257/347/251/277/346/241/210/344/276/213.md

@@ -0,0 +1,127 @@
+# 内部设备借用：贯穿五类项目的教学案例
+
+本文是虚构教学说明，不是已批准 Spec、真实交付包或可直接执行的产品合同。示例路径、规则和标识由学习者在独立 `project-instance` 中确认后落盘；模板源不登记这些业务词汇。
+
+## 业务故事与范围
+
+员工申请借用设备，负责人审批，管理员记录领用和归还。第一轮仅支持一张申请借用一台设备；采购、计费和维修不在案例范围。统一管理方协调战略、后端和前端版本。
+
+| 场景 | 正常结果 | 必须讨论的反例 |
+|---|---|---|
+| 提交申请 | 形成待审批申请 | 日期非法、设备不可借 |
+| 审批 | 形成批准或驳回结果 | 无权限、重复审批 |
+| 领用 | 记录领用并改变设备占用状态 | 未批准、设备被另一申请占用 |
+| 归还 | 记录归还并释放设备 | 重复归还、设备损坏如何另行处置 |
+
+“审批是否预占设备”“谁能代领”“超期如何处理”是待用户决定，不由 Agent 默认为业务规则。完整故事贯穿教学；每次实现仍只选一个窄业务切片，例如“已批准申请领用设备”。
+
+## 1. 选择工作组织
+
+综合模板可承载从澄清到业务验收的管理资产。战略模板只负责上游方案；研发既可以交给通用研发模板，也可以交给后端/前端专职模板。后两者必须登记统一管理方及独立实现仓，不把源代码复制进模板。
+
+## 2. 战略方形成可交接输入
+
+```text
+请按本仓战略流程澄清“内部设备借用”。
+逐轮确认参与者、目标、范围、申请/审批/领用/归还规则及失败场景。
+先提出会改变业务结果的问题，不替我决定审批是否占用库存。
+确认后再起草 Spec、需要的页面流程、视觉基线和业务级 Ticket。
+列出准备交接的规则、关键场景、版本、批准证据和研发待决事项。
+```
+
+用户逐项核对业务和页面。预期输出为本仓合同要求的已批准战略资产、根词汇、交接描述及证据闭包，不能只交聊天摘要。战略方不在此生成后端工程或冻结工程 API。
+
+由 Agent 给出实际交接描述路径后，在战略实例执行以下命令。尖括号必须替换为真实路径，输出目录须新建；`--handoff` 是相对源实例的文件路径。
+
+```bash
+node scripts/strategic-handoff export --source-root . --handoff <交接描述相对路径> --output <新包目录> --zip
+node scripts/strategic-handoff verify --bundle <包目录或ZIP>
+```
+
+预期验包输出 `result: verified` 及包摘要；缺证据或被修改的包会失败。把完整目录/ZIP交给下游，保留版本与摘要，不手改包内文件。
+
+## 3. 后端或通用研发接收
+
+在接收实例运行：
+
+```bash
+node scripts/strategic-handoff verify --bundle <包目录或ZIP>
+node scripts/strategic-handoff import --bundle <包目录或ZIP> --target-root .
+```
+
+```text
+请读取导入收据和包内规则/场景，核对本仓根 CONTEXT.md 并形成正式对账。
+为“已批准申请领用设备”逐项登记承接、冲突和依赖。
+按当前流程准备战术设计、API Draft/Freeze 和后端 Slice Contract，
+登记真实实现仓、验证命令和回滚点。合同获准前只准备材料，不写代码。
+```
+
+预期保存导入收据、目标词汇对账、规则/场景承接与当前合同；导入成功不会自动批准这些资产。设备占用竞争应落实到设计与可执行测试，不能只在页面禁用按钮。API 变化回到冻结流程。后端专职只承担后端；通用研发按本仓合同承担实际受影响的两端工作。
+
+## 4. 后端交付当前切片
+
+```text
+请按已批准且当前的合同实现领用切片，使用登记实现仓根 ./mvnw 验证。
+整理成功/失败契约测试、冻结接口、合同批准、构建产物、部署身份和测试数据证据。
+按本仓 backend-delivery schema 起草交付描述，核对本次切片范围与战略摘要。
+缺可达环境或版本证据就列为缺口，不写成已完成。
+```
+
+在后端实例执行（交付描述已由实际证据形成）：
+
+```bash
+node scripts/backend-delivery export --source-root . --delivery <交付描述相对路径> --output <新交付包目录> --zip
+node scripts/backend-delivery verify --bundle <交付包目录或ZIP>
+```
+
+预期 `verified`，但 `live_service_checked: false`：这里只验证快照，不能证明环境当前可用。交付包含战略绑定、冻结接口、批准合同、构建部署及成功/失败验证；不把账号密码装入包。实际 API 和版本探测由已登记环境提供，不凭手册假设已有固定端点。
+
+## 5. 前端联合接收与准备
+
+在前端实例执行：
+
+```bash
+node scripts/backend-delivery import --bundle <交付包目录或ZIP> --target-root .
+```
+
+战略快照随交付链导入，后端包与战略包分别验证。导入产生接收草稿；核对目标词汇、规则/场景、接口和视觉用例后才能形成正式接收记录。
+
+```text
+请联合核对战略和后端交付，完成目标词汇对账与前端场景映射。
+检查部署/源码/接口/构建/测试数据版本及真实服务。
+通过后只准备前端工程设计、frontend_implementation_plan 和 Slice Contract，
+列出待批准事项。输入不齐时只诊断并回交缺口，不写前端或后端代码。
+```
+
+由 Agent 返回当前接收记录相对路径和切片 ID 后执行：
+
+```bash
+node scripts/verify-frontend-delivery --root . --slice <切片ID> <接收记录相对路径>
+```
+
+成功是 `inputs-verified` 且 `ready_for_agent: false`。这允许准备计划和合同，正式编码仍须批准且当前的 Slice Contract。前端实现消费冻结 API；发现业务/API缺口回交维护方，不在前端仓悄悄重定义。
+
+## 6. 实现、联调与业务验收
+
+```text
+请复验接收输入与合同仍然当前，再按批准写范围实现前端领用流程。
+使用登记前端工程的 pnpm 命令，记录实际退出码、截图、状态交互、
+console warning、失败恢复及真实后端联调结果；交独立 Reviewer 审查。
+```
+
+后端记录可交付、前端记录可验收，统一管理方汇总同一战略、API、部署、前端版本的业务证据。用户检查一次真实领用及“重复领用/无权限”等约定反例，再按角色政策完成验收和发布裁决。单端完成、离线验包或一张截图都不能替代整体业务验收。
+
+## 7. 变更、失败与恢复
+
+| 情况 | 应做的事 |
+|---|---|
+| 包摘要不一致/批准缺失 | 保留失败输出，要求源方重出完整包；不手改摘要 |
+| 对账冲突/规则含糊 | 回交战略方决定，阻断依赖切片 |
+| 服务不可达或版本不符 | 后端补环境/部署证据，前端重新接收 |
+| 已导入更新的同身份后端包 | 旧接收记录失效，重新验证并编译依赖合同 |
+| 战略或视觉基线变化 | 评估规则/场景/页面依赖，更新合同后恢复 |
+| 模板同步失败 | 检查事务回滚结果和旧 metadata；从 Git 基线或备份恢复 |
+
+重试使用真实当前输入，不能复用旧成功日志当本次放行。已成功导入的战略快照可在后端包导入失败后保留，修复后幂等重试。
+
+权威接力语义见 [前后端交付与联合接收](../process/frontend-backend-delivery.md)，具体阶段/门禁见本仓 lifecycle-registry.yaml；案例不另定义状态、角色或批准政策。

package/template/scripts/backend-delivery

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { exportBackendDelivery, openBackendDelivery, importBackendDelivery } from './lib/backend-delivery.mjs';
+try {
+  const {values,positionals}=parseArgs({allowPositionals:true,options:{'source-root':{type:'string'},delivery:{type:'string'},output:{type:'string'},zip:{type:'boolean'},bundle:{type:'string'},'target-root':{type:'string'}}});
+  if(positionals.length!==1)throw new TypeError('必须指定 export / verify / import');
+  let result;
+  if(positionals[0]==='export'&&values['source-root']&&values.delivery&&values.output)result=await exportBackendDelivery({sourceRoot:values['source-root'],deliveryRef:values.delivery,output:values.output,zip:values.zip});
+  else if(positionals[0]==='verify'&&values.bundle)result=await openBackendDelivery(path.resolve(values.bundle),b=>({result:'verified',delivery_id:b.delivery.delivery_id,version:b.delivery.version,bundle_digest:b.manifest.bundle_digest,live_service_checked:false}));
+  else if(positionals[0]==='import'&&values.bundle&&values['target-root'])result=await importBackendDelivery({bundle:path.resolve(values.bundle),targetRoot:values['target-root']});
+  else throw new TypeError('用法: backend-delivery export --source-root <repo> --delivery <ref> --output <new-dir> [--zip] | verify --bundle <dir|zip> | import --bundle <dir|zip> --target-root <repo>');
+  process.stdout.write(`${JSON.stringify(result,null,2)}\n`);
+} catch(error) { process.stderr.write(`${JSON.stringify({result:'blocked',error:error.message})}\n`);process.exitCode=1; }

package/template/scripts/fixtures/backend-delivery/revision-server.mjs

@@ -0,0 +1,11 @@
+// Synthetic maintenance service. Never used as evidence of product API readiness.
+import { createServer } from 'node:http';
+import { readFileSync } from 'node:fs';
+const server=createServer((request,response)=>{
+  if(request.method!=='GET'||request.url!=='/version') {response.writeHead(404);response.end();return;}
+  const state=JSON.parse(readFileSync(process.argv[2],'utf8'));
+  response.writeHead(state.status||200,{'content-type':'application/json'});
+  response.end(JSON.stringify(state.body));
+});
+server.listen(0,'127.0.0.1',()=>process.send({port:server.address().port}));
+process.on('disconnect',()=>server.close(()=>process.exit(0)));

package/template/scripts/fixtures/strategic-handoff/base-stage.json

@@ -0,0 +1,91 @@
+{
+  "schema_version": 2,
+  "stage_decision_id": "stage-decision.supplier-admission",
+  "package_version": "v2",
+  "status": "approved",
+  "problem_statement": "合规准入决定分散，采购无法稳定判断当前有效资格。",
+  "target_users": [
+    "采购专员、合规专员"
+  ],
+  "mvp": [
+    "提交供应商申请、合规准入决定、采购侧有效性校验"
+  ],
+  "non_goals": [
+    "供应商结算、采购付款、通用工作流平台"
+  ],
+  "success_criteria": [
+    "新采购订单 100% 校验当前有效准入决定"
+  ],
+  "test_seams": [
+    "supplier-application-submit",
+    "admission-validity-check"
+  ],
+  "confirmed_decisions": [
+    "ComplianceReview 拥有准入规则语义，ProcurementExecution 只消费决定"
+  ],
+  "assumptions": [
+    "供应商已有唯一 subject_ref"
+  ],
+  "constraints": [
+    "保留现有采购订单流程"
+  ],
+  "unresolved_items": [
+    {
+      "item": "供应商历史资料迁移范围",
+      "type": "deferred",
+      "owner": "role.product-manager",
+      "next_action": "在 Spec synthesis 前完成数据盘点",
+      "target_version": "2026-Q4"
+    }
+  ],
+  "context_snapshot": {
+    "context_ref": "CONTEXT.md",
+    "context_schema_version": 1,
+    "document_digest": "<document-digest>",
+    "referenced_terms_digest": "<referenced-terms-digest>",
+    "term_refs": [
+      "Global/Supplier",
+      "ComplianceReview/AdmissionDecision"
+    ]
+  },
+  "domain_strategy_ref": {
+    "domain_strategy_id": "domain-strategy.supplier-admission",
+    "domain_version": "v2",
+    "digest": "<domain-strategy-digest>",
+    "status": "approved",
+    "persisted_ref": "domain-strategy.yaml"
+  },
+  "impact_assessment": {
+    "ui": true,
+    "api": true,
+    "data": true,
+    "backend": true,
+    "frontend": true,
+    "cross_repo": false,
+    "high_risk": false
+  },
+  "downstream_mapping": [
+    {
+      "domain_change": "admission-decision-validity",
+      "consumer": "spec-synthesis",
+      "propagation": "direct",
+      "reapproval_condition": "领域策略版本或有效性规则变化"
+    },
+    {
+      "domain_change": "admission-decision-validity",
+      "consumer": "ticket-decomposition",
+      "propagation": "transitive",
+      "reapproval_condition": "Spec 基线变更"
+    }
+  ],
+  "evidence_refs": [
+    "evidence.discovery.supplier",
+    "evidence.domain-strategy-review.supplier"
+  ],
+  "approval": {
+    "approval_ref": ".agents/skills/yss-stage-decision/tests/fixtures/stage-decision-approval.yaml",
+    "approver": "role.product-manager",
+    "persisted_ref": "docs/.scratch/supplier/stage-decision/stage-decision-package-v1.yaml",
+    "current_version": "v2"
+  }
+}

package/template/scripts/fixtures/strategic-handoff/base-strategy.json

@@ -0,0 +1,205 @@
+{
+  "schema_version": 2,
+  "domain_strategy_id": "domain-strategy.supplier-admission",
+  "domain_version": "v2",
+  "status": "approved",
+  "contexts": [
+    {
+      "context_id": "SupplierManagement",
+      "name": "供应商管理",
+      "responsibilities": [
+        "供应商申请、资料生命周期"
+      ],
+      "non_responsibilities": [
+        "合规决定、采购订单"
+      ],
+      "subdomain_type": "Supporting Subdomain",
+      "owner": "requirements-manager",
+      "status": "confirmed"
+    },
+    {
+      "context_id": "ComplianceReview",
+      "name": "合规审查",
+      "responsibilities": [
+        "资质审查、准入决定、有效期"
+      ],
+      "non_responsibilities": [
+        "供应商主档、采购订单"
+      ],
+      "subdomain_type": "Core Domain",
+      "owner": "product-manager",
+      "status": "confirmed"
+    },
+    {
+      "context_id": "ProcurementExecution",
+      "name": "采购执行",
+      "responsibilities": [
+        "采购选择、采购订单履行"
+      ],
+      "non_responsibilities": [
+        "合规规则、供应商申请"
+      ],
+      "subdomain_type": "Supporting Subdomain",
+      "owner": "project-manager",
+      "status": "confirmed"
+    }
+  ],
+  "subdomains": [
+    {
+      "subdomain_id": "subdomain.supplier-management",
+      "name": "Supplier Management",
+      "type": "Supporting Subdomain",
+      "rationale": "管理申请与资料生命周期，不承载差异化合规决策。",
+      "evidence_refs": [
+        "evidence.discovery.supplier"
+      ]
+    },
+    {
+      "subdomain_id": "subdomain.compliance-review",
+      "name": "Compliance Review",
+      "type": "Core Domain",
+      "rationale": "核心价值候选是企业自有的合规判断和风险规则。",
+      "evidence_refs": [
+        "evidence.discovery.compliance"
+      ]
+    }
+  ],
+  "relationships": [
+    {
+      "relationship_id": "relationship.supplier-to-compliance",
+      "from_context": "SupplierManagement",
+      "to_context": "ComplianceReview",
+      "relationship_pattern": "Customer/Supplier",
+      "semantic_upstream": "SupplierManagement",
+      "semantic_downstream": "ComplianceReview",
+      "business_authority": "SupplierManagement owns applicant facts",
+      "model_change_impact": "applicant schema changes require review adaptation",
+      "transport_direction": "SubmitSupplierForComplianceReview command",
+      "translation_responsibility": "ComplianceReview ACL",
+      "direction_explanation": "申请资料由 SupplierManagement 拥有，但技术请求方向不代表合规规则所有权。"
+    },
+    {
+      "relationship_id": "relationship.compliance-to-procurement",
+      "from_context": "ComplianceReview",
+      "to_context": "ProcurementExecution",
+      "relationship_pattern": "Published Language",
+      "semantic_upstream": "ComplianceReview",
+      "semantic_downstream": "ProcurementExecution",
+      "business_authority": "ComplianceReview owns admission validity",
+      "model_change_impact": "decision validity changes invalidate procurement acceptance",
+      "transport_direction": "admission decision events",
+      "translation_responsibility": "ProcurementExecution local projection",
+      "direction_explanation": "合规决定是语义上游；采购侧可通过事件接收并在下单时实时校验。"
+    }
+  ],
+  "scenarios": [
+    {
+      "scenario_id": "scenario.supplier-submits",
+      "actor": "supplier",
+      "preconditions": [
+        "供应商资料可编辑"
+      ],
+      "commands": [
+        "SubmitSupplierApplication"
+      ],
+      "rules": [
+        "申请材料必须完整"
+      ],
+      "events": [
+        "SupplierApplicationSubmitted"
+      ],
+      "failure_results": [
+        "材料不完整时拒绝提交"
+      ],
+      "responsible_context": "SupplierManagement",
+      "consumers": [
+        "ComplianceReview"
+      ],
+      "status": "confirmed"
+    },
+    {
+      "scenario_id": "scenario.admission-expires",
+      "actor": "compliance-officer",
+      "preconditions": [
+        "批准决定存在"
+      ],
+      "commands": [
+        "EvaluateAdmissionValidity"
+      ],
+      "rules": [
+        "过期决定不得支持新采购订单"
+      ],
+      "events": [
+        "SupplierAdmissionExpired"
+      ],
+      "failure_results": [
+        "采购下单时资格校验失败"
+      ],
+      "responsible_context": "ComplianceReview",
+      "consumers": [
+        "SupplierManagement",
+        "ProcurementExecution"
+      ],
+      "status": "confirmed"
+    }
+  ],
+  "concept_candidates": [
+    {
+      "concept_id": "domain-concept.admission-decision",
+      "name": "AdmissionDecision",
+      "context_id": "ComplianceReview",
+      "identity_features": [
+        "decision_id、subject_ref、rule_version"
+      ],
+      "lifecycle": [
+        "proposed、approved、rejected、expired、revoked"
+      ],
+      "possible_tactical_role": "Entity candidate",
+      "confidence": "high",
+      "status": "confirmed"
+    }
+  ],
+  "invariants": [
+    {
+      "invariant_id": "invariant.current-admission-required",
+      "statement": "新采购订单必须引用当前有效的准入决定。",
+      "responsible_context": "ComplianceReview",
+      "scenario_refs": [
+        "scenario.admission-expires"
+      ],
+      "verification_method": "领域场景测试和事件版本校验"
+    }
+  ],
+  "context_snapshot": {
+    "context_ref": "CONTEXT.md",
+    "context_schema_version": 1,
+    "document_digest": "<document-digest>",
+    "referenced_terms_digest": "<referenced-terms-digest>",
+    "term_refs": [
+      "Global/Supplier",
+      "ComplianceReview/AdmissionDecision"
+    ]
+  },
+  "downstream_mapping": [
+    {
+      "domain_change": "admission-decision-validity",
+      "impacts": [
+        "spec",
+        "openapi",
+        "procurement-acceptance-tests"
+      ],
+      "propagation": "stale",
+      "reapproval_condition": "ComplianceReview 决定和有效期重新批准"
+    }
+  ],
+  "evidence_refs": [
+    "evidence.discovery.supplier",
+    "evidence.discovery.compliance"
+  ],
+  "approval": {
+    "approval_ref": ".agents/skills/yss-stage-decision/tests/fixtures/domain-strategy-approval.yaml",
+    "approver": "role.product-manager",
+    "persisted_ref": "docs/.scratch/supplier/domain/domain-strategy-v1.yaml",
+    "current_version": "v2"
+  }
+}

package/template/scripts/fixtures/strategic-handoff/fixture.mjs

@@ -0,0 +1,57 @@
+import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { sealVisualBaseline } from '../../../.agents/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs';
+import { parseContextSource, resolveContextTermRefs } from '../../lib/context-contract.mjs';
+import { read, hash, digest, json, files, sourceApprovalPolicy, treeDigest } from '../../lib/strategic-handoff-io.mjs';
+import { countersignRuleForGate } from '../../lib/digital-human-roles.mjs';
+export const context = `---
+context_schema_version: 1
+---
+# 业务上下文
+## 流程术语
+| 术语 | 含义 | 英文标识 | 避免 / 备注 |
+|---|---|---|---|
+## 业务术语
+| 术语 | 含义 | 英文标识 | 适用业务责任区 | 避免 / 备注 |
+|---|---|---|---|---|
+| 供应商 | 提供产品或服务的主体 | Supplier | Global | |
+`;
+export async function fixture(root) {
+ const put=(ref,value)=>{const p=path.join(root,ref);mkdirSync(path.dirname(p),{recursive:true});writeFileSync(p,typeof value==='string'?value:json(value));};
+ put('yss-project.yaml','schema_version: 1\nrepository_mode: project-instance\n');put('CONTEXT.md',context);
+ const source=parseContextSource(context), resolved=resolveContextTermRefs(source,['Global/Supplier']);
+ const snapshot={context_ref:'CONTEXT.md',context_schema_version:1,document_digest:source.document_digest,referenced_terms_digest:resolved.referenced_terms_digest,term_refs:['Global/Supplier']};
+function pngHeader(width, height) { const value = Buffer.alloc(24); Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(value, 0); value.writeUInt32BE(13, 8); value.write("IHDR", 12, "ascii"); value.writeUInt32BE(width, 16); value.writeUInt32BE(height, 20); return value; }
+const bundleRoot = path.join(root, "source/visual-baseline-v1"); mkdirSync(path.join(bundleRoot, "images"), { recursive: true }); mkdirSync(path.join(bundleRoot, "sources"), { recursive: true }); mkdirSync(path.join(bundleRoot, "capture"), { recursive: true });
+writeFileSync(path.join(bundleRoot, "images/primary-desktop.png"), pngHeader(1440, 900)); writeFileSync(path.join(bundleRoot, "images/primary-narrow.png"), pngHeader(390, 844));
+writeFileSync(path.join(bundleRoot, "sources/prototype.html"), "<main>supplier</main>\n"); writeFileSync(path.join(bundleRoot, "sources/interaction.md"), "# Interaction\n"); writeFileSync(path.join(bundleRoot, "sources/states.md"), "# States\n"); writeFileSync(path.join(bundleRoot, "capture/capture.mjs"), "// capture\n"); writeFileSync(path.join(bundleRoot, "capture/result.json"), "{\"result\":\"passed\"}\n");
+const baselineFile = path.join(bundleRoot, "visual-baseline.yaml");
+const baseline = { schema_version: 1, baseline_id: "visual-baseline.supplier", feature: "supplier", version: "v1", status: "approved", bundle: { format: "portable-directory", root_ref: "source/visual-baseline-v1", digest: `sha256:${"0".repeat(64)}`, size_bytes: 0, max_image_bytes: 5242880, max_bundle_bytes: 104857600 }, source: { prototype_ref: "sources/prototype.html", prototype_digest: `sha256:${"1".repeat(64)}`, interaction_spec_ref: "sources/interaction.md", interaction_spec_digest: `sha256:${"2".repeat(64)}`, state_matrix_ref: "sources/states.md", state_matrix_digest: `sha256:${"3".repeat(64)}` }, capture_environment: { browser: "chromium", browser_version: "140.0.0", operating_system: "linux", fonts_digest: `sha256:${"4".repeat(64)}`, device_scale_factor: 1, color_space: "srgb", locale: "zh-CN", timezone: "Asia/Shanghai", animations_disabled: true, cursor_hidden: true, capture_script_ref: "capture/capture.mjs", capture_script_digest: `sha256:${"5".repeat(64)}`, capture_result_ref: "capture/result.json", capture_result_digest: `sha256:${"6".repeat(64)}` }, cases: [{ case_id: "primary-desktop", route: "/supplier", page: "SupplierPage", state: "normal", viewport: { name: "desktop", width: 1440, height: 900, scroll_mode: "viewport", scroll_position: 0 }, theme: "compact-light", locale: "zh-CN", data_scenario: "primary", image_ref: "images/primary-desktop.png", image_digest: `sha256:${"0".repeat(64)}`, image_size_bytes: 1, mask_ref: "not-applicable", mask_digest: "not-applicable", mask_size_bytes: 0, semantic_refs: ["sources/prototype.html", "sources/interaction.md"], allowed_differences: [], result: "passed" }, { case_id: "primary-narrow", route: "/supplier", page: "SupplierPage", state: "normal", viewport: { name: "narrow", width: 390, height: 844, scroll_mode: "viewport", scroll_position: 0 }, theme: "compact-light", locale: "zh-CN", data_scenario: "primary", image_ref: "images/primary-narrow.png", image_digest: `sha256:${"0".repeat(64)}`, image_size_bytes: 1, mask_ref: "not-applicable", mask_digest: "not-applicable", mask_size_bytes: 0, semantic_refs: ["sources/states.md"], allowed_differences: [], result: "passed" }] };
+writeFileSync(baselineFile, JSON.stringify(baseline)); const sealedBaseline = await sealVisualBaseline(baselineFile, bundleRoot);
+const visualBaselineRef = { baseline_id: sealedBaseline.baseline_id, version: sealedBaseline.version, digest: sealedBaseline.bundle.digest, status: "approved", persisted_ref: "source/visual-baseline-v1", manifest_ref: "visual-baseline.yaml", case_ids: sealedBaseline.cases.map((item) => item.case_id) };
+
+ const roles=sourceApprovalPolicy(read(new URL('./source-roles.json',import.meta.url)));
+ put('docs/agents/digital-human-roles.yaml',roles);
+ put('preview/index.html','<!doctype html><html><body><button onclick="this.textContent=\'已提交\'">提交</button></body></html>');
+ put('prototype-src/main.js','export const state = "ready";');
+ put('prototype-src/pnpm-lock.yaml','lockfileVersion: 9');
+ put('evidence/offline.log','Synthetic fixture for CLI tests; not product verification.');
+ const previewDigest=digest(files(root,'preview').map(ref=>({path:path.posix.relative('preview',ref),sha256:hash(readFileSync(path.join(root,ref)))})));
+ put('evidence/offline.json',{network_mode:'offline',exit_code:0,command:'synthetic fixture',executed_at:'2026-09-05T00:00:00Z',preview_digest:previewDigest,case_ids:['primary-desktop','primary-narrow'],evidence_refs:['evidence/offline.log']});
+ const baseStrategy=read(new URL('./base-strategy.json',import.meta.url));
+ const strategy={...baseStrategy,schema_version:2,domain_strategy_id:'domain-strategy.supplier',domain_version:'v1',status:'approved',contexts:baseStrategy.contexts,traceability_version:1,rule_catalog:[{rule_id:'rule.complete',statement:'申请材料必须完整',responsible_context:'SupplierManagement',status:'confirmed'}],scenarios:[{scenario_id:'scenario.submit',actor:'supplier',preconditions:['draft'],commands:['Submit'],rules:['申请材料必须完整'],rule_refs:['rule.complete'],events:['Submitted'],success_results:['已提交'],failure_results:['缺材料拒绝'],responsible_context:'SupplierManagement',consumers:[],status:'confirmed',critical:true}],invariants:[{invariant_id:'invariant.complete',statement:'申请材料必须完整',rule_ref:'rule.complete',responsible_context:'SupplierManagement',scenario_refs:['scenario.submit'],verification_method:'test'}],context_snapshot:snapshot,evidence_refs:['evidence/offline.log']};
+ strategy.approval={approval_ref:'approvals/domain_strategy_ref.yaml',approver:'role.product-manager',persisted_ref:'source/strategy.yaml',current_version:'v1'};
+ strategy.subdomains.forEach(x=>x.evidence_refs=['evidence/offline.log']);
+ put('source/strategy.yaml',strategy);
+ const stage={...read(new URL('./base-stage.json',import.meta.url)),schema_version:2,stage_decision_id:'stage-decision.supplier',package_version:'v1',status:'approved',domain_strategy_ref:{domain_strategy_id:strategy.domain_strategy_id,domain_version:'v1',status:'approved',persisted_ref:'source/strategy.yaml',digest:digest(strategy)},context_snapshot:snapshot,unresolved_items:[]};
+ stage.approval={approval_ref:'approvals/stage_decision_package_ref.yaml',approver:'role.product-manager',persisted_ref:'source/stage.yaml',current_version:'v1'};stage.evidence_refs=['evidence/offline.log'];
+ put('source/stage.yaml',stage);put('source/spec.md','# 供应商提交\n');put('source/tickets.yaml',{status:'approved'});
+ const ref=(id,p,kind)=>({id,version:'v1',status:'approved',persisted_ref:p,digest:kind==='canonical-json'?digest(read(path.join(root,p))):hash(readFileSync(path.join(root,p)))});
+ const sourceRefs={domain_strategy_ref:ref(strategy.domain_strategy_id,'source/strategy.yaml','canonical-json'),stage_decision_package_ref:ref(stage.stage_decision_id,'source/stage.yaml','canonical-json'),spec_ref:ref('spec.supplier','source/spec.md'),prototype_ref:ref('prototype.supplier','preview/index.html'),visual_baseline_ref:visualBaselineRef,business_ticket_set_ref:ref('business-ticket-set.supplier','source/tickets.yaml','canonical-json')};
+ const terminalGate=countersignRuleForGate(roles.gate_policy,'gate.strategic-design-handoff-approved')?'gate.strategic-design-handoff-approved':'gate.stage-decision-package-approved';
+ const gates={domain_strategy_ref:'gate.domain-strategy-approved',stage_decision_package_ref:'gate.stage-decision-package-approved',spec_ref:'gate.spec-baseline-approved',prototype_ref:'gate.user-confirmation',visual_baseline_ref:'gate.user-confirmation',business_ticket_set_ref:terminalGate,handoff:terminalGate};
+ const approvals=Object.fromEntries([...Object.keys(sourceRefs),'handoff'].map(key=>[key,{record_ref:`approvals/${key}.yaml`,gate_id:gates[key],digest_kind:key==='visual_baseline_ref'?'visual-baseline':['domain_strategy_ref','stage_decision_package_ref','business_ticket_set_ref'].includes(key)?'canonical-json':'sha256-bytes'}]));
+ const handoff={schema_version:3,handoff_id:'strategic-design-handoff.supplier',handoff_version:'v1',status:'approved',source:sourceRefs,source_context_snapshot:snapshot,context_delta:{added:resolved.terms.map(({term_ref,term,meaning,english_identifier,context_id,forbidden_aliases})=>({term_ref,term,meaning,english_identifier,context_id,forbidden_aliases})),updated:[],deprecated:[]},target_context_reconciliation:{target_context_ref:'CONTEXT.md',reconciliation_schema_ref:'docs/process/schemas/context-reconciliation.schema.json',required_before_skill:'yss-tactical-design',status:'pending'},target:{team:'downstream-rd-team',skill:'yss-tactical-design',output:'tactical-design-contract'},problem_and_business_outcomes:['提交供应商材料'],bounded_context_and_subdomain_map:['SupplierManagement'],context_map_and_translation_responsibility:['SupplierManagement'],ubiquitous_language_and_concept_candidates:['Global/Supplier'],scenarios_and_business_invariants:['rule.complete','scenario.submit'],tactical_design_questions:['一致性边界'],deferred_decisions_and_ownership:[],evidence_and_version_digests:['evidence/offline.log'],acceptance:['traceability'],package_export:{schema_version:1,approvals,additional_files:[],reference_map:{},prototype:{profile:'H2',preview_root:'preview',entry_ref:'preview/index.html',verification_ref:'evidence/offline.json',verification_digest:hash(readFileSync(path.join(root,'evidence/offline.json'))),source_digest:treeDigest(root,'prototype-src'),source_root:'prototype-src',lock_ref:'prototype-src/pnpm-lock.yaml'}}};
+ const sign=()=>{put('handoff.yaml',handoff);for(const[key,approval]of Object.entries(approvals)){const asset=key==='handoff'?{id:handoff.handoff_id,version:handoff.handoff_version,digest:hash(readFileSync(path.join(root,'handoff.yaml')))}:sourceRefs[key];put(approval.record_ref,{schema_version:1,gate_id:approval.gate_id,decision:'approved',actor_kind:'digital-human',role_id:countersignRuleForGate(roles.gate_policy,approval.gate_id).countersigners[0],runtime_id:'runtime.generic',principal_ref:'synthetic-maintenance-fixture',artifact_bindings:[{id:asset.id||asset.baseline_id,version:asset.version,digest:asset.digest}]});}};
+ sign();return{handoff,strategy,stage,put,sign,snapshot};
+}