create-yss-spec 3.1.0 → 3.2.0

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/fixture.mjs

@@ -16,7 +16,8 @@ context_schema_version: 1
 |---|---|---|---|---|
 | 供应商 | 提供产品或服务的主体 | Supplier | Global | |
 `;
-export async function fixture(root) {
+// Legacy fixture remains the default for released CLI compatibility tests.
+export async function fixture(root, { technicalDesign = false } = {}) {
  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']);
@@ -51,7 +52,7 @@ const visualBaselineRef = { baseline_id: sealedBaseline.baseline_id, version: se
  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 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:technicalDesign?'yss-technical-design':'yss-tactical-design',status:'pending'},target:{team:'downstream-rd-team',skill:technicalDesign?'yss-technical-design':'yss-tactical-design',output:technicalDesign?'technical-design-contract':'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};
 }

package/template/scripts/instantiate-harness

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// Repository-local distribution for the two dedicated Harness templates.
+import { existsSync, readFileSync, mkdirSync, mkdtempSync, renameSync, rmSync, statSync, lstatSync, readlinkSync, realpathSync, symlinkSync, chmodSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { ROOT, read, safe, ensure, hash, digest, write, json } from './lib/strategic-handoff-io.mjs';
+
+try {
+  const args=process.argv.slice(2),options={};
+  while(args.length) {
+    const key=args.shift();
+    if(key==='--allow-working-tree')options.working=true;
+    else if(['--target','--project-name'].includes(key)) {ensure(args.length&&!args[0].startsWith('--'),`${key} 缺少值`);options[key.slice(2)]=args.shift();}
+    else throw new Error(`未知参数 ${key}；使用 --target <新目录> [--project-name <名称>]`);
+  }
+  ensure(options.target,'必须指定 --target <新目录>');
+  const identity=read(safe(ROOT,'yss-project.yaml'));
+  ensure(identity.schema_version===1&&identity.repository_mode==='template-source','仅模板源可初始化新项目');
+  const profile=read(safe(ROOT,'docs/process/harness-profile.yaml'));
+  ensure(['harness.backend-delivery','harness.frontend-delivery'].includes(profile.profile_id),'仅支持后端/前端专职模板');
+  const target=path.resolve(options.target);
+  ensure(!target.startsWith(ROOT+path.sep)&&!ROOT.startsWith(target+path.sep)&&target!==ROOT,'目标不得包含模板源或位于模板源内');
+  ensure(!existsSync(target),'目标已存在；不覆盖或静默转换既有项目 profile');
+  const git=args=>execFileSync('git',args,{cwd:ROOT,encoding:'utf8',maxBuffer:16*1024*1024}).trim();
+  const commit=git(['rev-parse','HEAD']);
+  ensure(/^[0-9a-f]{40}$/.test(commit),'模板必须有不可变 Git 提交');
+  const dirty=Boolean(git(['status','--porcelain','--untracked-files=all']));
+  ensure(!dirty||options.working,'模板工作树未提交；维护测试可显式使用 --allow-working-tree，正式分发须先提交');
+  const manifest=read(safe(ROOT,profile.instantiation.distribution_manifest));
+  const names=execFileSync('git',['ls-files','-co','--exclude-standard','-z'],{cwd:ROOT,encoding:'utf8',maxBuffer:16*1024*1024}).split('\0').filter(Boolean);
+  const prefix=(ref,base)=>ref===base||ref.startsWith(base+'/');
+  const selected=[...new Set(names)].filter(ref=>{
+    const top=ref.split('/')[0];
+    const allowed=(manifest.allowRootEntries||[]).includes(top)||(manifest.allowRootFiles||[]).includes(ref)||(manifest.allowFiles||[]).includes(ref);
+    return allowed&&![...(manifest.excludeRootEntries||[]),...(manifest.initExcludeRootEntries||[])].includes(top)
+      &&![...(manifest.excludeRootFiles||[]),...(manifest.initExcludeRootFiles||[])].includes(ref)
+      &&![...(manifest.excludePaths||[]),...(manifest.initExcludePaths||[])].some(excluded=>prefix(ref,excluded));
+  }).sort();
+  ensure(selected.includes('yss-project.yaml')&&selected.includes('AGENTS.md')&&selected.includes('CONTEXT.md'),'分发缺少入口合同');
+  const capture=ref=>{
+    const file=path.join(ROOT,ref);if(path.dirname(ref)!=='.')safe(ROOT,path.dirname(ref));
+    if(lstatSync(file).isSymbolicLink()) {
+      const link=readlinkSync(file),resolved=realpathSync(file);
+      ensure(!path.isAbsolute(link)&&resolved.startsWith(path.join(ROOT,'.agents/skills')+path.sep),'仅允许指向本仓 canonical skills 的相对投影链接');
+      return {ref,link,bytes:Buffer.from(`symlink:${link}`),mode:0o777};
+    }
+    return {ref,bytes:readFileSync(safe(ROOT,ref)),mode:statSync(file).mode&0o777};
+  };
+  const captured=selected.map(capture);
+  const sourceFiles=captured.map(({ref,bytes,mode})=>({ref,digest:hash(bytes),mode}));
+  const sourceDigest=digest(sourceFiles);
+  mkdirSync(path.dirname(target),{recursive:true});
+  const staging=mkdtempSync(path.join(path.dirname(target),'.harness-init-'));
+  try {
+    const managed={};
+    for(const file of captured) {
+      let bytes=file.bytes;
+      if(file.ref==='yss-project.yaml') bytes=Buffer.from('schema_version: 1\nrepository_mode: project-instance\n');
+      if(file.ref==='README.md') bytes=Buffer.from(`# ${options['project-name']||path.basename(target)}\n\n本仓是 \`${profile.profile_id}\` 的 \`project-instance\`。先读 [AGENTS.md](AGENTS.md)、根 CONTEXT.md 与 [profile](docs/process/harness-profile.yaml)。接力输入与执行条件见 [交付合同](docs/process/frontend-backend-delivery.md)。\n`);
+      if(file.link) {mkdirSync(path.dirname(path.join(staging,file.ref)),{recursive:true});symlinkSync(file.link,path.join(staging,file.ref));}
+      else {write(staging,file.ref,bytes);chmodSync(path.join(staging,file.ref),file.mode);}
+      managed[file.ref]={digest:hash(bytes),mode:file.mode};
+    }
+    write(staging,profile.instantiation.metadata_file,json({schema_version:1,profile_id:profile.profile_id,template_source:profile.instantiation.template_source,template_commit:commit,source_tree_digest:sourceDigest,source_files:sourceFiles,source_working_tree:dirty,release_snapshot:!dirty,managed_files:managed}));
+    for(const {ref,bytes} of captured)ensure(hash(capture(ref).bytes)===hash(bytes),`初始化期间模板变化: ${ref}`);
+    ensure(!existsSync(target),'目标目录并发冲突');renameSync(staging,target);
+    process.stdout.write(json({result:'initialized',profile_id:profile.profile_id,target,template_commit:commit,source_tree_digest:sourceDigest,release_snapshot:!dirty}));
+  } finally {rmSync(staging,{recursive:true,force:true});}
+} catch(error) {process.stderr.write(`${error.message}\n`);process.exitCode=1;}

package/template/scripts/lib/backend-delivery.mjs

@@ -0,0 +1,164 @@
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { openBundle, importBundle, sourceApproval } from './strategic-handoff.mjs';
+import { read, safe, ensure, hash, digest, json, files, write, project, schema, archive, sourceApprovalPolicy } from './strategic-handoff-io.mjs';
+
+// Evidence binds the deliverable basis, avoiding a circular hash through its own logs.
+export function backendDeliveryBasis(delivery) {
+  return digest(Object.fromEntries(['delivery_id','version','strategic_bundle_digest','scope','openapi','slice_contract','build','environment'].map(key=>[key,delivery[key]])));
+}
+
+function boundFile(root, binding) {
+  const bytes=readFileSync(safe(root,binding.ref));
+  ensure(hash(bytes)===binding.digest,`交付资产摘要不一致: ${binding.ref}`);
+  return bytes;
+}
+
+async function approvedFile(root, binding, gate) {
+  const bytes=boundFile(root,binding);
+  const record=read(safe(root,binding.approval_ref));
+  const roles=sourceApprovalPolicy(read(safe(root,'docs/agents/digital-human-roles.yaml')));
+  await sourceApproval(record,roles,root);
+  ensure((Array.isArray(gate)?gate:[gate]).includes(record.gate_id),`交付资产批准门禁不匹配: ${binding.ref}`);
+  ensure(record.artifact_bindings?.some(x=>x.id===binding.id&&x.version===binding.version&&x.digest===binding.digest),`批准未绑定当前交付资产: ${binding.ref}`);
+  return bytes;
+}
+
+function verification(root, binding, basis, kind) {
+  boundFile(root,binding);
+  const record=read(safe(root,binding.ref));
+  schema(record,'docs/process/schemas/backend-delivery-verification.schema.json');
+  ensure(record.kind===kind&&record.subject_digest===basis,`验证未绑定当前交付: ${kind}`);
+  ensure(record.results.every(x=>x.exit_code===0),`后端验证失败: ${kind}`);
+  for(const result of record.results) {
+    ensure(Number.isFinite(Date.parse(result.executed_at))&&Date.parse(result.executed_at)<=Date.now()+60000,'验证执行时间无效');
+    result.evidence.forEach(file=>boundFile(root,file));
+  }
+  return record;
+}
+
+export async function inspectBackendDelivery(root, ref) {
+  project(root);
+  const delivery=read(safe(root,ref));
+  schema(delivery,'docs/process/schemas/backend-delivery.schema.json');
+  ensure(boundFile(root,delivery.environment.test_data).length>0,'测试数据准备说明为空');
+  await approvedFile(root,delivery.openapi,['gate.openapi-frozen','gate.openapi-freeze-confirmed']);
+  await approvedFile(root,delivery.slice_contract,'gate.slice-contract-approved');
+  const contractDoc=read(safe(root,delivery.slice_contract.ref));
+  const contract=contractDoc.slice_contract||contractDoc;
+  ensure(contract.status==='approved'&&contract.slice_id===delivery.scope.slice_id&&contract.contract_id===delivery.slice_contract.id&&contract.contract_version===delivery.slice_contract.version,'后端 Slice Contract 身份/状态/切片不匹配');
+  const api=read(safe(root,delivery.openapi.ref));
+  ensure(/^3\.1\./.test(api.openapi),'后端交付必须使用 OpenAPI 3.1');
+  const operations=Object.values(api.paths||{}).flatMap(item=>Object.entries(item).filter(([method])=>['get','put','post','delete','options','head','patch','trace'].includes(method)).map(([,operation])=>operation.operationId));
+  ensure(delivery.scope.operation_ids.every(id=>operations.includes(id)),'交付接口不在冻结 OpenAPI 中');
+  const basis=backendDeliveryBasis(delivery);
+  const tests=verification(root,delivery.verification.contract,basis,'backend-contract');
+  verification(root,delivery.verification.deployment,basis,'backend-deployment');
+  return openBundle(safe(root,delivery.strategic_bundle_ref),bundle=>{
+    ensure(bundle.manifest.bundle_digest===delivery.strategic_bundle_digest,'后端交付与战略版本不一致');
+    const sources=new Set([...bundle.indexes.rules.map(x=>x.rule_id),...bundle.indexes.scenarios.map(x=>x.scenario_id)]);
+    ensure(delivery.scope.source_ids.every(id=>sources.has(id)),'后端交付引用未知规则/场景');
+    const scenarios=bundle.indexes.scenarios.filter(x=>delivery.scope.source_ids.includes(x.scenario_id));
+    ensure(scenarios.length>0,'后端交付范围缺少业务成功/失败场景');
+    for(const scenario of scenarios) {
+      ensure(scenario.rule_refs.every(id=>delivery.scope.source_ids.includes(id)),'交付场景缺少关联规则');
+      for(const outcome of ['success','failure'])ensure(tests.coverage.some(x=>x.source_id===scenario.scenario_id&&x.outcome===outcome),'后端交付缺少成功/失败场景验证');
+    }
+    ensure(delivery.scope.operation_ids.every(id=>tests.operation_ids.includes(id)),'后端契约验证未覆盖交付接口');
+    return {delivery,basis};
+  });
+}
+
+function validManifest(manifest,root) {
+  ensure(manifest.schema_version===1&&manifest.kind==='backend-delivery','后端包类型或 schema 不支持');
+  const {bundle_digest,...body}=manifest;
+  ensure(bundle_digest===digest(body),'后端包清单摘要不一致');
+  ensure(Array.isArray(manifest.files)&&manifest.files.length<=20000,'后端包文件清单无效');
+  const names=manifest.files.map(x=>x.path);
+  ensure(new Set(names.map(x=>x.toLowerCase())).size===names.length,'后端包路径重复');
+  ensure(json([...names,'manifest.json'].sort())===json(files(root).sort()),'后端包文件缺失或存在未登记文件');
+  ensure(manifest.files.reduce((total,file)=>total+file.size_bytes,0)<=512*1024*1024,'后端包大小超限');
+  const originals=manifest.files.filter(x=>x.original_ref).map(x=>x.original_ref);
+  ensure(new Set(originals.map(x=>x.toLowerCase())).size===originals.length,'后端包源路径重复');
+  for(const file of manifest.files) {
+    const bytes=readFileSync(safe(root,file.path));
+    ensure(bytes.length===file.size_bytes&&hash(bytes)===file.sha256,`后端包文件摘要不一致: ${file.path}`);
+  }
+}
+
+export async function openBackendDelivery(input, action) {
+  const temporary=mkdtempSync(path.join(tmpdir(),'yss-backend-delivery-'));
+  try {
+    ensure(existsSync(input)&&!lstatSync(input).isSymbolicLink(),'后端交付包不存在或是 symlink');
+    let root=path.resolve(input);
+    if(lstatSync(root).isFile()) { root=path.join(temporary,'unpacked');mkdirSync(root);archive('unpack',path.resolve(input),root); }
+    const manifest=read(safe(root,'manifest.json'));validManifest(manifest,root);
+    const source=path.join(temporary,'source');mkdirSync(source);
+    for(const file of manifest.files)if(file.original_ref)write(source,file.original_ref,readFileSync(safe(root,file.path)));
+    const inspected=await inspectBackendDelivery(source,manifest.delivery_ref);
+    ensure(manifest.delivery_id===inspected.delivery.delivery_id&&manifest.version===inspected.delivery.version,'后端包身份不一致');
+    return await action({root,source,manifest,...inspected});
+  } finally { rmSync(temporary,{recursive:true,force:true}); }
+}
+
+export async function exportBackendDelivery({sourceRoot,deliveryRef,output,zip=false}) {
+  const root=project(sourceRoot), target=path.resolve(output);
+  ensure(!existsSync(target)&&(!zip||!existsSync(`${target}.zip`)),'后端包输出已存在');
+  const {delivery}=await inspectBackendDelivery(root,deliveryRef);
+  const refs=new Set([deliveryRef,'yss-project.yaml','CONTEXT.md','docs/agents/digital-human-roles.yaml',delivery.openapi.ref,delivery.openapi.approval_ref,delivery.slice_contract.ref,delivery.slice_contract.approval_ref,delivery.environment.test_data.ref,...delivery.supporting_files]);
+  for(const binding of Object.values(delivery.verification)) {
+    refs.add(binding.ref);
+    for(const result of read(safe(root,binding.ref)).results)for(const file of result.evidence)refs.add(file.ref);
+  }
+  // Keep the original strategic bytes and paths; offline validation reconstructs a temporary source view.
+  const strategy=safe(root,delivery.strategic_bundle_ref);
+  if(lstatSync(strategy).isDirectory())files(root,delivery.strategic_bundle_ref).forEach(ref=>refs.add(ref));
+  else refs.add(delivery.strategic_bundle_ref);
+  ensure(refs.size<=20000,'后端包文件数量超限');
+  const captured=[...refs].sort().map(ref=>({ref,bytes:readFileSync(safe(root,ref))}));
+  mkdirSync(path.dirname(target),{recursive:true});
+  const staging=mkdtempSync(path.join(path.dirname(target),'.backend-export-'));
+  try {
+    const entries=[];
+    for(const {ref,bytes} of captured) {
+      const name=ref==='CONTEXT.md'?'payload/source-context.snapshot.md':`payload/files/${ref}`;
+      write(staging,name,bytes);entries.push({path:name,original_ref:ref,size_bytes:bytes.length,sha256:hash(bytes)});
+    }
+    const body={schema_version:1,kind:'backend-delivery',delivery_id:delivery.delivery_id,version:delivery.version,delivery_ref:deliveryRef,files:entries};
+    const manifest={...body,bundle_digest:digest(body)};write(staging,'manifest.json',json(manifest));
+    await openBackendDelivery(staging,()=>null);
+    for(const {ref,bytes} of captured)ensure(hash(readFileSync(safe(root,ref)))===hash(bytes),`导出期间后端源资产变化: ${ref}`);
+    if(zip)archive('pack',staging,`${staging}.zip`);
+    ensure(!existsSync(target)&&(!zip||!existsSync(`${target}.zip`)),'后端包输出并发冲突');
+    renameSync(staging,target);if(zip)renameSync(`${staging}.zip`,`${target}.zip`);
+    return {result:'exported',delivery_id:delivery.delivery_id,version:delivery.version,bundle_digest:manifest.bundle_digest,output:target,...(zip?{zip:`${target}.zip`}:{})};
+  } finally { rmSync(staging,{recursive:true,force:true});rmSync(`${staging}.zip`,{force:true}); }
+}
+
+export async function importBackendDelivery({bundle,targetRoot}) {
+  const target=project(targetRoot);
+  return openBackendDelivery(bundle,async b=>{
+    const ref=`docs/backend-deliveries/${b.delivery.delivery_id}/${b.delivery.version}`;
+    const destination=safe(target,ref,{missing:true});
+    if(existsSync(destination)) {
+      const receipt=read(safe(destination,'import-receipt.json'));
+      ensure(receipt.bundle_digest===b.manifest.bundle_digest,'同 ID/version 后端包内容冲突');
+      await openBackendDelivery(safe(destination,'package'),()=>null);
+      return {result:'already-imported',receipt_ref:`${ref}/import-receipt.json`,acceptance_ref:`${ref}/frontend-acceptance-draft.json`};
+    }
+    const strategic=await importBundle({bundle:safe(b.source,b.delivery.strategic_bundle_ref),targetRoot:target});
+    const strategicReceipt=read(safe(target,strategic.receipt_ref));
+    const trace=read(safe(target,`${path.posix.dirname(strategic.receipt_ref)}/tactical-traceability-draft.json`));
+    mkdirSync(path.dirname(destination),{recursive:true});
+    const staging=mkdtempSync(path.join(path.dirname(destination),'.backend-import-'));
+    try {
+      cpSync(b.root,path.join(staging,'package'),{recursive:true,errorOnExist:true,force:false});
+      const receipt={schema_version:1,delivery_id:b.delivery.delivery_id,version:b.delivery.version,bundle_digest:b.manifest.bundle_digest,package_ref:`${ref}/package`};
+      write(staging,'import-receipt.json',json(receipt));
+      write(staging,'frontend-acceptance-draft.json',json({schema_version:1,status:'draft',slice_id:b.delivery.scope.slice_id,backend_delivery:{import_receipt_ref:`${ref}/import-receipt.json`,bundle_digest:b.manifest.bundle_digest},strategic_handoff:{import_receipt_ref:strategic.receipt_ref,bundle_digest:strategicReceipt.bundle_digest,context_reconciliation_ref:'',rows:trace.rows.map(({tactical_refs,test_seam_refs,...row})=>({...row,frontend_case_refs:[]}))},frontend_cases:[]}));
+      ensure(!existsSync(destination),'后端包导入并发冲突');renameSync(staging,destination);
+      return {result:'imported-pending-acceptance',receipt_ref:`${ref}/import-receipt.json`,acceptance_ref:`${ref}/frontend-acceptance-draft.json`};
+    } finally { rmSync(staging,{recursive:true,force:true}); }
+  });
+}

package/template/scripts/lib/frontend-delivery-boundary.mjs

@@ -0,0 +1,49 @@
+import { loadDeliveryProfile } from './harness-execution-scope.mjs';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { ROOT, read, safe, ensure, digest } from './strategic-handoff-io.mjs';
+
+// Shared synchronous adapter for existing compiler, lifecycle and task-package seams.
+// Always re-executes the verifier; a caller-supplied "verified" flag is never evidence.
+export function enforceFrontendDelivery(state={}, {root=ROOT,phase='inputs'}={}) {
+  const profile=loadDeliveryProfile(root);
+  let contract;
+  const contractRef=state.slice_contract_ref||state.contract?.slice_contract_ref;
+  const selected=profile?.profile_id==='harness.frontend-delivery'||profile?.frontend_delivery?.required===true;
+  const identity=selected?read(safe(root,'yss-project.yaml')):null;
+  if(selected)ensure(identity.schema_version===1&&['template-source','project-instance'].includes(identity.repository_mode),'前端项目仓库身份无效');
+  const dedicated=selected&&identity.repository_mode==='project-instance';
+  if(dedicated)ensure(state.contract?.kind!=='template-maintenance','前端产品项目不得用模板维护任务绕过输入条件');
+  let binding=state.frontend_delivery||state.frontend?.delivery||state.resolution?.frontend_delivery;
+  if(contractRef) {
+    // Legacy callers may supply an absolute external contract. Discover whether
+    // the new boundary applies before enforcing its repository-relative policy.
+    const file=path.resolve(root,contractRef);
+    if(existsSync(file)) {
+      const document=read(file);contract=document.slice_contract||document;
+      const direct=contract.frontend?.delivery, resolved=contract.resolution?.frontend_delivery;
+      ensure(!direct||!resolved||digest(direct)===digest(resolved),'Slice Contract 前端交付绑定冲突');
+      binding=direct||resolved||binding;
+    }
+  }
+  if(!dedicated&&!binding)return {result:'not-applicable'};
+  if(contractRef)safe(root,contractRef);
+  ensure(binding?.acceptance_ref,'frontend-delivery-required: 缺少战略与后端联合接收记录');
+  const slice=contract?.slice_id||state.slice_id;
+  ensure(!contract?.slice_id||!state.slice_id||contract.slice_id===state.slice_id,'前端任务与 Slice Contract 切片不一致');
+  ensure(slice,'frontend-delivery-required: 缺少明确切片');
+  if(phase==='implementation') {
+    ensure(contract?.status==='approved','frontend-delivery-required: 必须读取已持久化的 approved Slice Contract');
+    ensure(contract.frontend?.delivery||contract.resolution?.frontend_delivery,'frontend-delivery-required: Slice Contract 未绑定前端交付');
+    ensure(binding.digest,'frontend-delivery-required: Slice Contract 未冻结接收记录摘要');
+  }
+  const args=[path.join(ROOT,'scripts/verify-frontend-delivery'),'--root',root,'--slice',slice];
+  if(binding.digest)args.push('--expected-digest',binding.digest);
+  args.push(binding.acceptance_ref);
+  const verified=spawnSync(process.execPath,args,{cwd:root,encoding:'utf8',timeout:60000,maxBuffer:2*1024*1024});
+  ensure(verified.status===0,`frontend-delivery-blocked: ${verified.error?.message||verified.stderr||verified.stdout}`);
+  const result=JSON.parse(verified.stdout);
+  ensure(result.result==='inputs-verified'&&result.ready_for_agent===false,'前端接收校验返回非法状态');
+  return result;
+}

package/template/scripts/lib/frontend-delivery.mjs

@@ -0,0 +1,73 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { openBackendDelivery } from './backend-delivery.mjs';
+import { openBundle } from './strategic-handoff.mjs';
+import { verifyConsumption } from './strategic-handoff-consumption.mjs';
+import { read, safe, ensure, hash, schema, project } from './strategic-handoff-io.mjs';
+
+function pointer(value, ref) {
+  ensure(ref.startsWith('/')&&!ref.includes('//'),'服务版本 JSON Pointer 无效');
+  return ref.slice(1).split('/').reduce((node,key)=>node?.[key.replace(/~1/g,'/').replace(/~0/g,'~')],value);
+}
+
+export async function probeBackend(delivery) {
+  const base=new URL(delivery.environment.base_url);
+  const url=new URL(delivery.environment.revision_path,base);
+  ensure(['http:','https:'].includes(base.protocol)&&!base.username&&!base.password&&!base.hash&&!base.search,'服务环境 URL 无效或包含凭据');
+  ensure(url.origin===base.origin&&!url.username&&!url.password&&!url.hash&&!url.search,'版本探测必须在登记环境内');
+  const headers={Accept:'application/json'};
+  if(delivery.environment.authorization_env) {
+    const authorization=process.env[delivery.environment.authorization_env];
+    ensure(authorization,'版本探测缺少登记的授权环境配置');headers.Authorization=authorization;
+  }
+  const response=await fetch(url,{method:'GET',redirect:'error',signal:AbortSignal.timeout(5000),headers});
+  ensure(response.ok,`真实接口不可用: HTTP ${response.status}`);
+  const reader=response.body.getReader();let size=0;const chunks=[];
+  try {
+    while(true) { const {done,value}=await reader.read();if(done)break;size+=value.length;ensure(size<=1024*1024,'版本探测响应超限');chunks.push(value); }
+  } finally { await reader.cancel(); }
+  const body=JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  const expected={deployment_id:delivery.environment.deployment_id,source_commit:delivery.build.source_commit,openapi_digest:delivery.openapi.digest,artifact_digest:delivery.build.artifact_digest,test_data_digest:delivery.environment.test_data.digest};
+  for(const [key,value] of Object.entries(expected))ensure(pointer(body,delivery.environment.revision_pointers[key])===value,`真实服务版本不匹配: ${key}`);
+  return {command:`GET ${url.href}`,executed_at:new Date().toISOString(),exit_code:0,observed:expected};
+}
+
+export async function verifyFrontendDelivery({root=process.cwd(),acceptanceRef,sliceRef,expectedDigest}) {
+  project(root);
+  const file=safe(root,acceptanceRef), acceptance=read(file);
+  schema(acceptance,'docs/process/schemas/frontend-delivery-acceptance.schema.json');
+  const acceptanceDigest=hash(readFileSync(file));
+  if(expectedDigest)ensure(expectedDigest===acceptanceDigest,'前端接收记录摘要已变化，需重编译合同');
+  ensure(sliceRef&&acceptance.slice_id===sliceRef,'前端接收记录与执行切片不匹配');
+  const binding=acceptance.backend_delivery, receipt=read(safe(root,binding.import_receipt_ref));
+  const base=`docs/backend-deliveries/${receipt.delivery_id}/${receipt.version}`;
+  ensure(binding.import_receipt_ref===`${base}/import-receipt.json`&&receipt.package_ref===`${base}/package`,'后端收据路径与身份不匹配');
+  ensure(receipt.bundle_digest===binding.bundle_digest,'后端收据与接收记录摘要不匹配');
+  const versions=readdirSync(safe(root,`docs/backend-deliveries/${receipt.delivery_id}`)).filter(name=>/^v[1-9][0-9]*$/.test(name)&&existsSync(safe(root,`docs/backend-deliveries/${receipt.delivery_id}/${name}/import-receipt.json`,{missing:true}))).sort((a,b)=>Number(b.slice(1))-Number(a.slice(1)));
+  ensure(versions[0]===receipt.version,'已接收更新的后端交付，旧前端接收记录 stale');
+  return openBackendDelivery(safe(root,receipt.package_ref),async backend=>{
+    const delivery=backend.delivery;
+    ensure(backend.manifest.bundle_digest===receipt.bundle_digest&&backend.manifest.delivery_id===receipt.delivery_id&&backend.manifest.version===receipt.version,'后端包与收据不一致');
+    ensure(delivery.scope.slice_id===sliceRef&&delivery.strategic_bundle_digest===acceptance.strategic_handoff.bundle_digest,'后端、战略与前端切片版本不一致');
+    const strategic=await verifyConsumption(acceptance,{root,sliceRef,consumer:'frontend'});
+    ensure(strategic.result==='verified',`战略承接阻断: ${JSON.stringify(strategic.issues)}`);
+    const ids=acceptance.frontend_cases.map(item=>item.case_id);
+    ensure(new Set(ids).size===ids.length,'前端验收用例 ID 重复');
+    await openBundle(safe(backend.source,delivery.strategic_bundle_ref),bundle=>{
+      const visualCases=bundle.handoff.source.visual_baseline_ref.case_ids;
+      for(const item of acceptance.frontend_cases) {
+        ensure(item.operation_ids.every(id=>delivery.scope.operation_ids.includes(id)),'前端用例依赖未交付接口');
+        ensure(item.source_ids.every(id=>delivery.scope.source_ids.includes(id)),'前端用例依赖未交付规则/场景');
+        ensure(item.visual_case_ids.every(id=>visualCases.includes(id)),'前端用例视觉基线悬空');
+        const evidence=readFileSync(safe(root,item.evidence_ref));
+        ensure(evidence.length>0&&hash(evidence)===item.evidence_digest,'前端承接用例说明为空或摘要漂移');
+      }
+    });
+    for(const id of delivery.scope.source_ids) {
+      const row=acceptance.strategic_handoff.rows.find(item=>item.source_id===id);
+      ensure(row?.disposition==='mapped'&&row.dependent_slice_refs.includes(sliceRef),'当前交付规则/场景未承接到当前前端切片');
+    }
+    const actual=await probeBackend(delivery);
+    return {result:'inputs-verified',ready_for_agent:false,slice_id:sliceRef,acceptance_ref:acceptanceRef,acceptance_digest:acceptanceDigest,backend_bundle_digest:receipt.bundle_digest,strategic_bundle_digest:strategic.consumed_bundle_digest,actual_verification:actual,next_action:'prepare-or-revalidate-frontend-plan-and-slice-contract'};
+  });
+}