create-yss-spec 3.3.6 → 3.3.8

package/template/docs/process/schemas/strategic-handoff-stage-decision-package-v3.schema.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.local/schemas/strategic-handoff-stage-decision-package-v3.json",
+  "title": "YSS Stage Decision Package",
+  "type": "object",
+  "required": ["schema_version", "stage_decision_id", "package_version", "status", "problem_statement", "target_users", "mvp", "non_goals", "success_criteria", "test_seams", "confirmed_decisions", "assumptions", "constraints", "unresolved_items", "context_snapshot", "domain_strategy_ref", "impact_assessment", "downstream_mapping", "evidence_refs", "approval"],
+  "properties": {
+    "schema_version": {"const": 3},
+    "stage_decision_id": {"type": "string", "pattern": "^stage-decision\\.[a-z0-9][a-z0-9-]*$"},
+    "package_version": {"type": "string", "pattern": "^v[0-9]+$"},
+    "status": {"enum": ["draft", "ready-for-human", "approved", "stale", "blocked"]},
+    "problem_statement": {"type": "string", "minLength": 1},
+    "target_users": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+    "mvp": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+    "non_goals": {"type": "array", "items": {"type": "string", "minLength": 1}},
+    "success_criteria": {"type": "array", "minItems": 1},
+    "test_seams": {"type": "array", "minItems": 1},
+    "confirmed_decisions": {"type": "array", "minItems": 1},
+    "assumptions": {"type": "array"},
+    "constraints": {"type": "array"},
+    "unresolved_items": {"type": "array", "items": {"$ref": "#/$defs/unresolved"}},
+    "context_snapshot": {"$ref": "#/$defs/contextSnapshot"},
+    "domain_strategy_ref": {"$ref": "#/$defs/domainRef"},
+    "impact_assessment": {"$ref": "#/$defs/impact"},
+    "downstream_mapping": {"type": "array", "minItems": 1},
+    "evidence_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+    "approval": {"$ref": "#/$defs/approval"}
+  },
+  "$defs": {
+    "contextSnapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["context_ref", "context_schema_version", "document_digest", "referenced_terms_digest", "term_refs"],
+      "properties": {
+        "context_ref": {"const": "CONTEXT.md"},
+        "context_schema_version": {"const": 1},
+        "document_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+        "referenced_terms_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+        "term_refs": {"type": "array", "items": {"type": "string", "pattern": "^(Global|[A-Z][A-Za-z0-9]+)/[A-Z][A-Za-z0-9]+$"}, "uniqueItems": true}
+      }
+    },
+    "unresolved": {
+      "type": "object",
+      "required": ["item", "type", "owner", "next_action", "target_version"],
+      "properties": {
+        "item": {"type": "string", "minLength": 1},
+        "type": {"enum": ["blocker", "deferred"]},
+        "owner": {"type": "string", "minLength": 1},
+        "next_action": {"type": "string", "minLength": 1},
+        "target_version": {"type": "string", "minLength": 1}
+      }
+    },
+    "domainRef": {
+      "type": "object",
+      "required": ["domain_strategy_id", "domain_version", "digest", "status", "persisted_ref"],
+      "properties": {
+        "domain_strategy_id": {"type": "string", "pattern": "^domain-strategy\\.[a-z0-9][a-z0-9-]*$"},
+        "domain_version": {"type": "string", "pattern": "^v[0-9]+$"},
+        "digest": {"type": "string", "minLength": 1},
+        "status": {"enum": ["approved", "stale", "blocked"]},
+        "persisted_ref": {"type": "string", "minLength": 1}
+      }
+    },
+    "impact": {
+      "type": "object",
+      "required": ["ui", "api", "data", "backend", "frontend", "cross_repo", "high_risk"],
+      "properties": {
+        "ui": {"type": "boolean"},
+        "api": {"type": "boolean"},
+        "data": {"type": "boolean"},
+        "backend": {"type": "boolean"},
+        "frontend": {"type": "boolean"},
+        "cross_repo": {"type": "boolean"},
+        "high_risk": {"type": "boolean"}
+      }
+    },
+    "mapping": {
+      "type": "object",
+      "required": ["domain_change", "consumer", "propagation", "reapproval_condition"],
+      "properties": {
+        "domain_change": {"type": "string", "minLength": 1},
+        "consumer": {"type": "string", "minLength": 1},
+        "propagation": {"enum": ["direct", "transitive", "not-applicable", "stale"]},
+        "reapproval_condition": {"type": "string", "minLength": 1}
+      }
+    },
+    "recordV3": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "statement", "evidence_refs"],
+      "properties": {
+        "id": {"type": "string", "pattern": "^(success-criterion|test-seam|decision|assumption|constraint)\\.[a-z0-9][a-z0-9-]*$"},
+        "statement": {"type": "string", "minLength": 1},
+        "source_refs": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^(rule|scenario|invariant)\\.[a-z0-9][a-z0-9-]*$"}},
+        "evidence_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "minLength": 1}},
+        "status": {"enum": ["confirmed", "candidate", "stale"]}
+      }
+    },
+    "mappingV3": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mapping_id", "source_refs", "consumer_capability", "propagation", "reapproval_condition", "evidence_refs"],
+      "properties": {
+        "mapping_id": {"type": "string", "pattern": "^mapping\\.[a-z0-9][a-z0-9-]*$"},
+        "source_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "pattern": "^(rule|scenario|invariant)\\.[a-z0-9][a-z0-9-]*$"}},
+        "consumer_capability": {"enum": ["backend-technical-design", "frontend-engineering-design", "delivery-coordination"]},
+        "propagation": {"enum": ["direct", "transitive", "not-applicable", "stale"]},
+        "reapproval_condition": {"type": "string", "minLength": 1},
+        "evidence_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "minLength": 1}}
+      }
+    },
+    "approval": {
+      "type": "object",
+      "required": ["approval_ref", "approver", "persisted_ref", "current_version"],
+      "properties": {
+        "approval_ref": {"type": "string", "minLength": 1},
+        "approver": {"type": "string", "minLength": 1},
+        "persisted_ref": {"type": "string", "minLength": 1},
+        "current_version": {"type": "string", "pattern": "^v[0-9]+$"}
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"schema_version": {"const": 3}}, "required": ["schema_version"]},
+      "then": {
+        "properties": {
+          "success_criteria": {"items": {"$ref": "#/$defs/recordV3"}},
+          "test_seams": {"items": {"$ref": "#/$defs/recordV3"}},
+          "confirmed_decisions": {"items": {"$ref": "#/$defs/recordV3"}},
+          "assumptions": {"items": {"$ref": "#/$defs/recordV3"}},
+          "constraints": {"items": {"$ref": "#/$defs/recordV3"}},
+          "downstream_mapping": {"items": {"$ref": "#/$defs/mappingV3"}}
+        }
+      },
+      "else": {
+        "properties": {
+          "success_criteria": {"items": {"type": "string", "minLength": 1}},
+          "test_seams": {"items": {"type": "string", "minLength": 1}},
+          "confirmed_decisions": {"items": {"type": "string", "minLength": 1}},
+          "assumptions": {"items": {"type": "string", "minLength": 1}},
+          "constraints": {"items": {"type": "string", "minLength": 1}},
+          "downstream_mapping": {"items": {"$ref": "#/$defs/mapping"}}
+        }
+      }
+    }
+  ]
+}

package/template/docs/process/strategic-handoff-package.md

@@ -1,16 +1,16 @@
 # 战略交接快照包
 
-本合同用于批准后的战略交付和研发接收，不增加生命周期阶段或门禁。`scripts/strategic-handoff` 是统一入口；Node 22+、Python 3 和现有 `jsonschema` 环境即可运行，不下载依赖、不执行交接包中的代码。包 schema 与导出配置见同目录 `schemas/strategic-handoff-package.schema.json`、`schemas/strategic-handoff-export.schema.json`。源规则仍由战略合同持有，索引与快照不成为第二套事实源。
+本合同用于批准后的战略交付和研发接收，不增加生命周期阶段或门禁。`scripts/strategic-handoff` 是统一入口；Node 22+、Python 3 和现有 `jsonschema` 环境即可运行，不下载依赖、不执行交接包中的代码。包 schema 与导出配置见同目录 `schemas/strategic-handoff-package.schema.json`、`schemas/strategic-handoff-export.schema.json`（历史 v1）与 `schemas/strategic-handoff-export-v2.schema.json`（Handoff v5）。源规则仍由战略合同持有，索引与快照不成为第二套事实源。
 
 ## 源资产准备
 
-1. 源仓必须为 `project-instance`。业务边界与规则合同保留 schema v2，正式便携导出要求 `traceability_version: 1`。`rule_catalog` 的每行包含稳定 `rule_id`、`statement`、`responsible_context`、`status: confirmed`。不得用行号、文字 hash 或导出顺序生成业务身份。
+1. 源仓必须为 `project-instance`。新交付使用 Domain Strategy v3 与 Stage Decision Package v3；规则、场景、决定、假设、约束、成功标准、测试 seam 与 downstream mapping 使用稳定 ID 和证据。v2 仅用于历史 Handoff v3 的只读验证；修改或重发须显式迁移、重新批准。不得用行号、文字 hash 或导出顺序生成业务身份。
 2. 每个场景明确 `critical`、`rule_refs`、`success_results` 和既有 `failure_results`；兼容字段 `rules` 必须与引用规则正文一致。不变量使用 `rule_ref`，并通过 `scenario_refs` 指向确实覆盖该规则的场景。缺身份或关联先回战略方确认、更新并重新批准，导出器不猜测。
-3. Handoff v3 的 `package_export` 使用导出 schema。`approvals` 按 `source` 字段及 `handoff` 绑定批准记录，声明 `record_ref`、`gate_id`、`digest_kind`。沿用源角色表的现有门禁；当前综合模板的战略、阶段决策及交接资产统一绑定 `gate.plan-approved`，Spec 对应 Spec 基线批准，原型和视觉基线对应 `gate.product-design-approved`；历史包及其他源 profile 仍按包内明确登记的源批准规则验证，不自动迁移当前门禁状态。
+3. 新的既有 UI 交接使用 Handoff v5；原型交付可继续使用 Handoff v4 或显式使用 v5 的 prototype 分支。历史 Handoff v3/v4 按各自冻结 schema 和来源语义严格验证，不原地升级。校验器先读取 `schema_version` 再选择固定 schema，未知版本输出支持列表并 fail closed。`package_export` 的 `approvals` 按 `source` 字段及 `handoff` 绑定批准记录，声明 `record_ref`、`gate_id`、`digest_kind`。沿用源角色表的现有门禁；当前综合模板的战略、阶段决策及交接资产统一绑定 `gate.plan-approved`，Spec 对应 Spec 基线批准，原型和视觉基线对应 `gate.product-design-approved`；历史包及其他源 profile 仍按包内明确登记的源批准规则验证，不自动迁移当前门禁状态。
 4. 批准记录除既有会签字段，还要在 `artifact_bindings` 中逐项绑定 `{id, version, digest}`。战略/阶段建议 `canonical-json`；普通文件使用 `sha256-bytes`；视觉基线使用 `visual-baseline`。正文中的 `approved` 和可读取批准路径不能替代当前字节的批准绑定。源角色表要求用户决定记录时，接收端必须支持并核验该策略；旧工具缺少该能力时阻断并要求升级，不能按旧规则放行。
 5. `additional_files` 明确补充依赖；`reference_map` 将 `evidence.*` 稳定证据引用解析为仓内路径。源资产、批准记录、证据引用、Markdown 本地链接和显式目录共同形成依赖闭包。HTTP 引用保留为引用，不在导出时下载网页。
-6. `prototype` 指定 `profile`、`preview_root`、`entry_ref`、`verification_ref`、`verification_digest`（验证记录的字节摘要）；H2 另须 `source_root`、`lock_ref` 和 `source_digest`（源码目录树摘要，算法同下述预览树）。源码交付目录不含 node_modules / .git；锁文件与源码一同保存。预览目录须资源闭合，可通过本地静态服务离线浏览。源码、锁文件或验证记录变化须更新交接摘要并重新批准。
-7. 离线浏览验证记录必须有 `network_mode: offline`、实际 `command`、`executed_at`、`exit_code: 0`、`case_ids`、`evidence_refs` 和 `preview_digest`。后者为按路径排序的预览文件 `{path: 相对preview_root路径, sha256: 字节摘要}` 数组的 canonical JSON SHA-256。记录须覆盖视觉基线 case；采集时禁用外网，动态资源与交互由实际浏览器验证。验包不执行来源代码；静态闭包检查不能替代浏览器证据。
+6. 原型分支的 `prototype` 指定 `profile`、`preview_root`、`entry_ref`、`verification_ref`、`verification_digest`（验证记录的字节摘要）；H2 另须 `source_root`、`lock_ref` 和 `source_digest`（源码目录树摘要，算法同下述预览树）。源码交付目录不含 node_modules / .git；锁文件与源码一同保存。预览目录须资源闭合，可通过本地静态服务离线浏览。源码、锁文件或验证记录变化须更新交接摘要并重新批准。
+7. 原型分支的离线浏览验证记录必须有 `network_mode: offline`、实际 `command`、`executed_at`、`exit_code: 0`、`case_ids`、`evidence_refs` 和 `preview_digest`。后者为按路径排序的预览文件 `{path: 相对preview_root路径, sha256: 字节摘要}` 数组的 canonical JSON SHA-256。记录须覆盖视觉基线 case；采集时禁用外网，动态资源与交互由实际浏览器验证。验包不执行来源代码；静态闭包检查不能替代浏览器证据。
 
 ## 命令
 
@@ -23,13 +23,29 @@ scripts/strategic-handoff verify --bundle <目录或ZIP>
 scripts/strategic-handoff import --bundle <目录或ZIP> --target-root <研发项目根>
 ```
 
-目录是逻辑包；ZIP 只负责运输。源资产原始字节进入 payload，清单以 `original_ref → path` 映射原路径到包内路径；原 Handoff 保存在 `handoff.yaml`，源根词汇表保存为 `payload/source-context.snapshot.md`。包中不创建嵌套 `CONTEXT.md`。独立验包时工具在临时目录重建只读验证视图，完成后清理；不把临时源词汇表注册为目标权威。
+目录是逻辑包；ZIP 只负责运输。源资产原始字节进入 payload，清单以 `original_ref → path` 映射原路径到包内路径；v3/v4 的原 Handoff 保存在 `handoff.yaml`，源根词汇表保存为 `payload/source-context.snapshot.md`。v5 的原文件映射为 `payload/files/<original_ref>`，只有根词汇表使用固定物理别名 `payload/files/source-context.snapshot.md`；该别名不成为第二个根词汇表。包中不创建嵌套 `CONTEXT.md`。常规独立验包时工具在临时目录重建验证视图，完成后清理；不把临时源词汇表注册为目标权威。
 
 `manifest.json` 的 `files` 声明所有文件的字节摘要和大小。`bundle_digest` 是删除自身字段后 canonical JSON 的 SHA-256；不把整 ZIP 摘要当逻辑版本摘要。目录与 ZIP 的逻辑摘要相同。源合同的既有语义 digest 另行复核。目录/ZIP 已存在时拒绝覆盖，同身份版本不同内容的导入拒绝；已验过且相同的重复导入返回 `already-imported`。限制为 20,000 文件、512 MiB 展开内容；拒绝 ZIP 路径穿越、重复路径、大小写碰撞和符号链接。
 
+## 既有 UI 基线与严格只读核验
+
+Handoff v5 必须声明 `ui_baseline_kind: prototype | existing-ui-baseline`，`package_export` v2 使用相同类型。prototype 分支保留上述原型、视觉包、离线浏览和批准规则。existing-ui-baseline 分支只承接无 UI 改动的工程，`source.existing_ui_baseline_ref` 替代原型/视觉引用；不可混填两类来源。完整文件合同见 [既有 UI 基线](existing-ui-baseline.md)。
+
+既有基线以 `existing-ui-baseline.json` 原字节摘要作为当前资产，由 `gate.product-design-approved` 的真实用户决定覆盖；批准主体必须是同一 manifest。固定源码、锁文件、构建输出、动作、截图、API 请求/响应和原始执行记录逐项绑定。历史原型批准不能自动转成基线批准；任何 UI/体验变化返回产品设计。
+
+初始化和构建前运行 `scripts/preflight-delivery --input <输入清单> --stage prepare|build|export|accept --json`；完整阶段语义见 [交付预检](delivery-preflight.md)。`openBundle(...,{readOnly:true})` 对已展开 v5 包以固定别名映射核验，不写临时源目录、不执行来源代码；ZIP 返回 `readonly-extraction-required`，旧布局返回 `readonly-source-layout-required`，均不得视为验证通过。实际导出和接收仍在执行边界重新校验。
+
+## Handoff v4/v5 消费者路由
+
+`consumer_routes` 固定表达三种能力，不绑定仓名：`backend-technical-design`、`frontend-engineering-design`、`delivery-coordination`。每条路由记录稳定 `route_id`、`required | optional | not-applicable`、影响引用、入口工作单元、预期输出、依赖和 Context Reconciliation 要求；`optional` / `not-applicable` 必须有原因与证据，不能产生 `ready-for-agent`。
+
+- Backend/API/Data 任一影响为真时，backend 路由必须 `required`，入口是 `work-unit.technical-design`；架构只在下游按已批准决定分流 DDD/MVC。
+- Frontend/UI 任一影响为真时，frontend 路由必须 `required`，入口是 `work-unit.frontend-engineering-design`；仅在 backend 路由生效时依赖后端交付。
+- 任一交付路由生效时 coordination 必须 `required`；全部无实现影响时三条路由均为有证据的 `not-applicable`。
+
 ## 下游接收与逐条追溯
 
-导入落盘到 `docs/handoffs/<handoff-id>/<version>/`，包含不可变 `package/`、`import-receipt.json`、`context-reconciliation-draft.json`、`tactical-traceability-draft.json`、`upstream-change-impact.json`。仅写快照与草案，不自动更新根词汇表或批准状态。目标侧确认增量后更新唯一根 `CONTEXT.md`，生成既有 schema 的正式 reconciliation 并校验。
+导入落盘到 `docs/handoffs/<handoff-id>/<version>/`。Handoff v3 继续生成 Import Receipt v1 和原固定文件名；Handoff v4/v5 生成 Import Receipt v2，按目标 profile 的消费者能力登记 route、产物引用和状态，并分别生成后端追踪、Frontend Strategic Preflight / 前端追踪、协调状态索引草案。共同生成 route-aware Context Reconciliation 和 upstream impact 草案。仅写快照与草案，不自动更新根词汇表或批准状态。目标侧确认增量后更新唯一根 `CONTEXT.md` 并完成正式 reconciliation。
 
 Technical Design Contract v2（DDD / MVC 共用）的 `strategic_handoff` 绑定 `import_receipt_ref`、`bundle_digest`、`context_reconciliation_ref` 和 `rows`。逐条覆盖全部规则与 `critical: true` 的成功/失败场景；行字段如下：
 
@@ -45,12 +61,37 @@ scripts/verify-strategic-handoff-consumption --root <研发项目根> --slice <
 node .agents/skills/yss-technical-design/scripts/validate-technical-design.mjs <技术设计合同> --root <研发项目根>
 ```
 
-新交接的 target 使用 `yss-technical-design` / `technical-design-contract`，对账必须在通用入口前完成；旧 `yss-tactical-design` / `tactical-design-contract` 成对只读兼容，不修改已冻结包。`tactical_refs` 在 v2 可指向 `design` 中的 MVC 模块、用例、规则或 DDD 对象，测试 seam 同样在对应分支解析。无战略交接包的 MVC 项目直接消费批准需求，不要求补造战略 DDD。
+Handoff v4/v5 后端消费必须绑定 `backend-technical-design` 的 `route_id`，先对账，再由 `yss-technical-design` 依据已批准架构调用 `yss-tactical-design` 或 `yss-mvc-design`。Handoff v3 的 `yss-technical-design` / `yss-tactical-design` 单目标组合只读兼容，不修改已冻结包。`tactical_refs` 在 v2 Technical Design 可指向 MVC 或 DDD 分支对象；无战略交接包的 MVC 项目直接消费批准需求，不补造战略 DDD。
+
+前端先验证与交接版本匹配的 Strategic Preflight：Handoff v4 使用 v1，Handoff v5 使用 v2 的 `ui_baseline_kind/ui_baseline_ref`，只允许起草前端工程设计与实现计划，固定返回 `ready_for_agent: false`。最终 Frontend Delivery Acceptance v2（Handoff v4）或 v3（Handoff v5）在 Backend/API/Data 有影响时必须绑定真实 Backend Delivery 收据与版本探测；UI-only 时使用与战略路由一致的 `backend-not-applicable`，此时 `operation_ids` 必须为空。无论哪条路径，当前且已批准的 Slice Contract 仍是实现入口。
+
+## 消费者反馈闭环
+
+Consumer Feedback v1 与 Feedback Adjudication v1 独立保存在已交付 package 外，分别绑定 bundle ID/version/digest、route、source ID/digest 和 feedback 原始字节 digest。`keep` 允许消费者重新核验后继续；`amend` 保持旧路径 blocked，战略资产升版、重新批准并导出新版本 Handoff；`defer` 对 blocking 问题继续阻断，非阻断问题只有责任人、风险、验证计划和目标版本齐全时继续。任何范围或风险变化重新应用用户决定失效规则；禁止修改历史 package 或用旧摘要冒充当前裁决。
+
+```bash
+scripts/strategic-feedback verify-feedback --root <消费者项目根> <feedback.json>
+scripts/strategic-feedback verify-adjudication --root <消费者项目根> <adjudication.json>
+```
 
 整体验证有未落实项时返回 blocked；按切片验证可放行有证据证明不依赖这些项的切片。输出 `block_all`、`blocked_slice_refs`、`issues`、实际消费包摘要与战术摘要。通过只证明结构化映射完整和引用可核验，业务语义仍需独立评审；不能代替 Slice Contract 批准。
 
-每版完整快照可独立消费，差异区分 added / updated / removed。更新须提升交接版本，内容变化的源资产也须提升其版本。接收新版本后，消费校验比较最新已导入源对象摘要；规则变化按行依赖阻断，未映射的新规则扩大阻断，战略责任边界、方案决策、Spec/视觉/原型源码等变化未重新绑定时整体阻断。`upstream-change-impact.json` 是生命周期处理 stale 的证据输入，不直接改 Tracker 或覆盖战术合同。
+每版完整快照可独立消费，差异区分 added / updated / removed。更新须提升交接版本，内容变化的源资产也须提升其版本。接收新版本后，消费校验比较最新已导入源对象摘要；规则变化按行依赖阻断，未映射的新规则扩大阻断，战略责任边界、方案决策、Spec/视觉/原型源码/既有 UI 基线等变化未重新绑定时整体阻断。`upstream-change-impact.json` 是生命周期处理 stale 的证据输入，不直接改 Tracker 或覆盖战术合同。
 
 ## 维护与同步
 
-共享脚本和包 schema 以主模板为维护源，通过 `scripts/sync-strategic-handoff-tools` 同步到设计/研发模板；源战略 schema 的离线验证副本由该脚本从 canonical `yss-stage-decision/references` 派生。三仓技能仍只编辑 `.agents/skills`，再生成各 runtime 投影与锁。CLI 快照使用各自同步工具，工作树快照用于集成验证，不代表已发布 commit。
+共享脚本和包 schema 以主模板为维护源，通过 `scripts/sync-strategic-handoff-tools` 同步到设计/研发模板；源战略 schema 的离线验证副本由该脚本从 canonical `yss-stage-decision/references` 派生。各仓技能仍只编辑 `.agents/skills`，再生成各 runtime 投影与锁。CLI 快照使用各自同步工具，工作树快照用于集成验证，不代表已发布 commit。共享同步仅从主技能注册表投影 `existing_project_profiles` 验证元数据，保留接收模板自己的 Recipe、capability 与创作技能；源注册表及目标有效字节写入工具锁。后端接收模板使用独立视觉 wire runtime，不安装原型创作技能。超出本 profile 职责的技术设计/编译资产在预检中明确标记不支持，战略交接路线不依赖这些后端资产。
+
+## 当前用户决定与交接复用
+
+源角色策略以 `required_capabilities: [strategic-decision-reuse-v1]` 声明本节语义；不支持该能力的接收器必须拒绝。历史包仍按包内源策略校验，不升级旧批准。
+
+当前会签绑定 `subject_ref`、`approval_scope`、`user_decision_ref`。只有最终战略交接允许用 `decision_reuse_ref` 引用复用证明；原回复的 boundary、资产和范围保持不变。checkpoint 的 `human_review.decision_reuse` 保存 `{target_gate, ref}`，会签必须引用同一证明。数字人审查仍独立完成。
+
+复用证明采用 schema v1，`kind: strategic-decision-reuse-v1`，包含 `target_gate`、`scope_ref`、`scope`、`requirements`。每个 requirement 保留原 `boundary`、`subject_ref`、`scope`、`user_decision_ref`。校验当前原始回复、负责人、撤销、资产摘要和范围，不接受自填布尔值作为覆盖证据。
+
+独立交付范围清单采用 schema v1，`kind: strategic-delivery-scope`，包含 `delivery_ref`、`assets`、`risks`、`conditions`。每项资产包含 `ref`、`version`、原始字节 `digest`、`boundary` 和 `scope`；原决定的 subject 或 basis 必须覆盖该资产，专业边界须一致。风险必须已出现在原决定的 risks 中，授权条件必须已出现在 next_actions 中；无法证明的部分补充确认。
+
+`delivery_ref` 是交接正文去除 `package_export`、`status` 后的独立 JSON/YAML 快照；也必须列入 assets 并由既有真实决定明确覆盖；不强制新增交接回复。所有实际 source 资产及视觉或既有 UI 基线 manifest 均须逐项覆盖。业务 Ticket 已被 Spec 的当前行为与验收范围明确覆盖时，可引用该 Spec 决定；数字人交接会签仍使用交接门禁，不改写原回复的专业边界。先固定该快照与业务资产，再确认和会签，最后组装包，避免摘要循环。仅重新组装传输包且业务依据和范围不变时复用有效确认。
+
+导出将范围清单、复用证明、原决定及其来源依赖一起收集。离线 verify 重新检查实际交付与批准覆盖；缺文件、摘要变化、范围遗漏、未知能力均阻断，不回写旧包。

package/template/docs/process/templates/lifecycle-checkpoint-template.yaml

@@ -22,6 +22,7 @@ stage_trace:
   downstream_impacts: []
 ticket_sync:
   status: pending
+  # 仅登记消费者收据、反馈/裁决和交付验收等权威资产引用，不复制其状态。
   refs: []
 verification:
   commands: []

package/template/docs/process/templates/stage-checkpoint-template.md

@@ -33,6 +33,7 @@ stage_trace:
   downstream_impacts: []
 ticket_sync:
   status: <pending|synced|not-applicable>
+  # refs 关联消费者收据、反馈/裁决和交付验收等权威资产，不复制其机器状态。
   refs: []
 next_work_unit: <stable work-unit id>
 verification:

package/template/docs/user-guide//346/212/200/346/234/257/350/256/276/350/256/241/347/224/250/346/210/267/346/214/207/345/215/227.md

@@ -0,0 +1,43 @@
+# 技术设计用户指南
+
+本指南说明批准战略或 Spec 如何进入后端技术设计。统一入口是 `yss-technical-design`；工程采用 `domain-driven` 时调用 `yss-tactical-design`，采用 `layered-mvc` 时调用 `yss-mvc-design`。架构类型来自当前工程登记或经用户确认的脚手架决定，不能按目录或个人偏好猜测。
+
+## 开始前检查
+
+先核对仓库身份、根 `CONTEXT.md`、批准战略或 Spec、目标实现仓登记、工程基线和适用批准。既有 Java/Maven 工程还要提供当前的 repository registration、engineering baseline 与 observation manifest；三份原始证据、实际 Git/Maven 工程和摘要必须一致。
+
+```text
+请读取当前批准战略或 Spec、根 CONTEXT.md 和工程登记。
+核对架构身份与既有工程证据，再用 yss-technical-design 起草当前技术设计。
+domain-driven 使用 yss-tactical-design；layered-mvc 使用 yss-mvc-design。
+说明状态、事务、并发、幂等、持久化和公开测试 seam，并逐项映射源规则与关键场景。
+列出冲突、延期、依赖和需要的批准；不要提前实现代码。
+```
+
+缺失、冲突或过期输入应回交事实所有者。技术设计不得改变业务规则，也不能用“实现方便”覆盖已批准行为。
+
+## 两类架构分别回答什么
+
+| 设计问题 | `domain-driven` | `layered-mvc` |
+|---|---|---|
+| 业务不变量由谁保护 | 聚合、Entity、Value Object 或 Domain Service | 用例服务、事务边界和明确校验组件 |
+| 状态如何变化 | 聚合行为和状态机 | Controller/Application/Service 调用下的状态规则 |
+| 一致性如何保证 | 聚合边界、Repository、事件和补偿 | 事务服务、幂等、并发控制和持久化约束 |
+| 外部依赖如何隔离 | Gateway/Repository/Adapter | Controller、Service、Mapper/Repository 和外部适配器 |
+| 怎样证伪 | 领域公开 seam 的正常、拒绝和并发场景 | 用例/API seam 的正常、拒绝和恢复场景 |
+
+MVC 不要求先构造聚合、值对象或 DDD Gateway；DDD 也不能把数据库表直接当作领域边界。两者都必须解释用例、规则、事务、并发、失败恢复和可执行验证。
+
+## 从设计进入实现
+
+API 有影响时先形成 OpenAPI 3.1 Draft，完成适用审查后 Freeze。随后把技术设计、冻结接口、工程登记、验证命令和回滚点编译进窄 Slice Contract。
+
+`yss-implementation-contract-compiler` 只起草合同，不批准合同、不设置 `ready-for-agent`。实现前必须重新确认：
+
+1. 技术设计和工程证据仍与当前源码一致。
+2. Slice Contract 已由本仓适用门禁批准。
+3. 允许写路径是批准范围与实现仓登记范围的交集。
+4. 成功、拒绝、并发、幂等和恢复场景具有公开测试 seam。
+5. 后端优先使用登记工程根 `./mvnw` 验证。
+
+技术设计评审通过不等于实现、合并或发布就绪。过程示例见[设备借用贯穿案例](设备借用贯穿案例.md)，项目选型见[用户手册](用户手册.md)。

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

@@ -1,114 +1,130 @@
 # YSS 用户手册
 
-面向首次使用与已有项目升级的操作者。本仓是模板源；从模板生成项目实例后再保存真实业务材料。先选对职责，再让 Agent 根据本仓规则执行。
+本手册帮助项目负责人选择模板、创建或接管项目，并判断 Agent 何时可以继续工作。本仓是 `template-source`；真实业务材料只能写入由 CLI 生成或接管的 `project-instance`。
 
-## 先选项目
+## 选择项目家族
 
-| 你的任务 | 选择 | 创建与更新入口 |
+| 你的责任 | 模板与 CLI | 本地终点 |
 |---|---|---|
-| 从想法到发布，统一管理整个业务切片 | 综合模板 `yss-spec-project-template` | `create-yss-spec`：初始化、attach、sync |
-| 澄清业务、Spec、原型并交接研发 | 战略模板 `yss-harness-design-agent` | `create-yss-harness-design`：初始化；无 attach/sync |
-| 接收已批准上游，统一组织研发 | 通用研发模板 `yss-harness-dev-agent` | `create-yss-harness-dev`：初始化、attach、sync |
-| 独立团队承担后端并输出交付包 | 后端模板 `yss-harness-backend-agent` | `create-yss-harness-backend`：init、attach、sync（首版候选） |
-| 接收战略及后端交付，承担前端 | 前端模板 `yss-harness-frontend-agent` | `create-yss-harness-frontend`：init、attach、sync（首版候选） |
+| 统一管理从业务问题到实现、验证和发布 | `yss-spec-project-template` / `create-yss-spec` | 完整业务切片验收 |
+| 澄清业务、形成 Spec、页面方案和战略交接 | `yss-harness-design-agent` / `create-yss-harness-design` | Strategic Design Handoff |
+| 设计并实现后端、冻结接口并输出后端交付 | `yss-harness-backend-agent` / `create-yss-harness-backend` | Backend Delivery |
+| 联合接收战略和后端交付、实现并验收前端 | `yss-harness-frontend-agent` / `create-yss-harness-frontend` | Frontend Acceptance |
 
-通用研发和前后端专职是可选择的组织方式，不要求现有通用项目迁移。采用专职路线时，登记一个统一管理方汇总业务切片，不能把两端自报完成直接相加当作业务验收。
+专职路线通常按“战略 → 后端 → 前端 → 统一业务验收”接力。每个子项目只确认自己的职责完成；统一管理方绑定同一战略、接口、部署和前端版本后，才能判断整个业务切片是否完成。
 
-完整协作可以采用“战略 → 后端交付 → 前端联合接收 → 统一业务验收”。综合或通用研发也可承担协调职责，具体责任人和仓库由项目登记，不凭目录推断。
+既有 `yss-harness-dev-agent` / `create-yss-harness-dev` 实例继续按其固定版本和本地 README 维护。本家族已退出当前项目选型，不自动迁移到综合、后端或前端家族，也不能通过修改 metadata 转换身份。
 
-## 安装和首次创建
+## CLI 能力与写入方式
 
-先确认 Node.js 与 npm 可用，命令要求以所选 CLI README 为准。首次使用推荐下列已发布渠道，三条命令只选择与你职责匹配的一条：
+先运行所用包的 `--version` 和 `--help`；源码候选版本、npm 已发布版本和实例记录的模板快照是三个不同事实。
 
-```bash
-npm create yss-spec@latest
-npm create yss-harness-design@latest
-npm create yss-harness-dev@latest
-```
+| 能力 | `create-yss-spec` | 战略、后端、前端专职 CLI |
+|---|---|---|
+| init | 默认命令；写入新目录 | `init`；只接受不存在或空目录 |
+| attach | 必须显式选择 `--dry-run` 或 `--apply` | 默认预览；`--apply` 写入 |
+| sync | 默认写入；`--dry-run`、`--plan`、`--json` 只读 | 默认预览；`--apply` 写入 |
+| diff / doctor | 支持，只读 | 支持，只读 |
+| recover | 无独立命令；失败由事务回滚 | 默认只读诊断；`recover --apply` 恢复未完成事务 |
+| prune | `sync --prune` | `sync --plan --prune` 预览，`sync --apply --prune` 写入 |
+| update / upgrade | 只更新 CLI 程序 | 只更新 CLI 程序 |
 
-本手册描述 GitHub 当前实现。`@latest` 指 npm 已发布版本，其模板快照可能落后于 GitHub。使用前运行 `npm view <包名> version` 核对；包名占位符须替换。未发布的候选不能用对应的 npm 版本号直接安装。
+`--prune` 只删除仍与可信旧 baseline 相同的退出分发文件。用户改过的旧文件会保留并报告；`--force` 也不能放宽删除、身份、Git、gitlink 或路径安全条件。
 
-要使用尚未发布的手册版本，从对应 CLI 的 GitHub 固定提交检出，按该仓 README 的候选包步骤构建；检查 `template.snapshot.json` 的 `templateCommit` 与包版本。CLI 初始化使用包内快照，不会实时拉取最新模板。不同家族的快照和版本号分别记录。
+## 安装、创建与核对
 
-前后端专职分别使用 `create-yss-harness-backend` / `create-yss-harness-frontend` 首版候选。发布前先从同名 CLI 仓的实际 tgz 安装验收；npm 可用状态以 registry 为准。
+先确认 npm 中确有需要的版本：
 
 ```sh
-npx create-yss-harness-backend@latest init --target-dir /absolute/path/to/new-project --project-name 设备借用
-npx create-yss-harness-frontend@latest attach --target-dir /absolute/path/to/existing-project
+npm view create-yss-spec version
+npm view create-yss-harness-design version
+npm view create-yss-harness-backend version
+npm view create-yss-harness-frontend version
 ```
 
-init 只创建不存在或空目录；attach / sync 默认只预览，写入要求 `--apply`。旧仓内脚本实例不兼容，不提供 metadata 转换；新实例记录 schema v2 的模板/core来源与受管基线。冲突整次暂停，显式备份覆盖可用 `--apply --force`，但身份、业务文件和路径保护不可绕过。
+再选择一个家族创建项目，例如：
+
+```sh
+npm create yss-spec@latest
+npx create-yss-harness-design@latest init --target-dir ./design-project --project-name 设备借用 --business-domain 内部设备管理
+npx create-yss-harness-backend@latest init --target-dir ./backend-project --project-name 设备借用 --business-domain 内部设备管理
+npx create-yss-harness-frontend@latest init --target-dir ./frontend-project --project-name 设备借用 --business-domain 内部设备管理
+```
+
+`@latest` 取得 npm 已发布包，不保证等于 GitHub 当前源码。候选包必须从对应 CLI 仓库构建实际 tgz，并核对 `package.json`、`template.snapshot.json` 的 `templateCommit`、来源状态和摘要；CLI 使用包内快照，不会运行时拉取模板仓。
+
+初始化或 attach 后检查：
 
-初始化后检查 yss-project.yaml 为 `project-instance`、对应家族 metadata 和 docs/user-guide/用户手册索引.md；进入生成目录再开启 Agent。
+1. `yss-project.yaml` 是 `project-instance`。
+2. 只存在本家族 metadata，且 profile 与职责一致。
+3. 根 `CONTEXT.md`、`AGENTS.md` 和 `docs/user-guide/用户手册索引.md` 可读。
+4. Git 状态、实现仓登记、验证命令和回滚点符合项目实际情况。
 
 ## 第一次让 Agent 工作
 
-先在生成的项目实例中打开 Agent，发送：
+在生成的项目实例中发送：
 
 ```text
-请先只读检查 yss-project.yaml、根 CONTEXT.md、AGENTS.md，以及存在的 harness-profile.yaml。
+请先只读检查 yss-project.yaml、根 CONTEXT.md、AGENTS.md 和 harness-profile.yaml。
 告诉我本仓职责、当前可信阶段、上游输入、缺失证据和下一步。
-发现身份不合法或输入过期时停止并给出恢复办法；先不要写代码。
+发现身份非法、输入过期或职责越界时停止并给出恢复办法；先不要写代码。
 ```
 
-成功时应得到明确的仓库身份和可追踪输入，不是泛泛的开发计划。`template-source` 只能维护可复用模板；真实业务必须在 `project-instance` 中记录。真实业务词汇只登记在实例根 `CONTEXT.md`，不复制本手册示例当作已确认事实。
+正确结果应说明当前事实、阻塞责任和下一动作。模板文件存在、导入成功、验证包摘要成功或 Agent 自报完成，都不能替代当前批准和 Fresh Verification。
 
-## 用户确认什么
+## 用户需要确认什么
 
-| 看到的材料 | 你需要判断 | 确认后的边界 |
+| 看到的材料 | 需要判断 | 确认后的边界 |
 |---|---|---|
-| 目标、范围、规则及反例 | 是否符合业务、哪些不做 | 允许继续设计；不自动批准实现 |
-| 页面流程、状态与视觉基线 | 成功、失败、权限和恢复是否完整 | 形成对应产品设计输入 |
-| 工程/接口/脚手架方案 | 责任、兼容、数据和回滚是否可接受 | 按本仓角色政策完成适用会签 |
-| 当前 Slice Contract | 写哪些仓库与路径、怎么验收 | 必要门禁通过后才能实施 |
-| 本轮验证和发布方案 | 覆盖、风险、回滚和交付范围 | 发布及外部承诺仍需生物人 |
+| 目标、范围、规则及反例 | 业务是否正确、哪些不做 | 允许继续设计，不自动批准实现 |
+| 页面流程、状态和视觉基线 | 成功、失败、权限与恢复是否完整 | 形成当前产品设计输入 |
+| 架构、接口和脚手架方案 | 责任、兼容、数据和回滚是否可接受 | 完成对应工程会签 |
+| 当前 Slice Contract | 写哪些仓库与路径、如何验收 | 门禁通过后才允许实施 |
+| 本轮验证和发布方案 | 覆盖、风险、回滚和交付范围 | 发布与外部承诺仍需生物人 |
 
-具体批准身份和门禁以本仓 `docs/agents/digital-human-roles.yaml`、`docs/process/lifecycle-registry.yaml` 为准。Agent 起草、自报通过或文件中写 `approved` 均不能代替真实批准。`ready-for-human` 是待指定会签；只有可直接实施的切片才使用 `ready-for-agent`。
+批准身份、范围和失效条件以本地 `digital-human-roles.yaml` 与 `lifecycle-registry.yaml` 为准。编译器只起草合同；`inputs-verified` 只允许继续准备计划和合同；只有当前合同获准、阻塞清除的切片才可进入 `ready-for-agent`。
 
-## 按路线推进
+## 当前工作主线
 
-综合模板按本仓生命周期从分诊、Plan、Spec/功能架构、产品设计、工程契约、Ticket、切片推进到验证与发布。战略模板在业务交接停止；通用研发从批准上游接入；专职两端按交付合同接力。
+综合模板从分诊、Plan、Spec、产品设计、工程契约、Ticket、实现推进到验证与发布。战略模板在业务交接停止；后端模板消费批准战略并输出可核验后端交付；前端模板联合接收战略、后端、API、数据和 UI 输入后实施前端。
 
-每一步都让 Agent 说明：消费了哪些当前输入、准备了什么、缺谁确认、怎样检查结果。具体阶段和门禁从本仓注册表读取，不把别的模板阶段编号复制进本仓。
+涉及交付前提时，先运行只读 `scripts/preflight-delivery`。它只验证原始输入，不初始化项目、不运行构建、不启动服务、不生成批准或收据。导出、导入和实现边界仍要重新验证当前资产。
 
-跟随 [设备借用贯穿案例](设备借用贯穿案例.md) 练习；战术建模说明见 [战术设计指南](战术设计子项目用户手册.md)。
+完整演练见[设备借用贯穿案例](设备借用贯穿案例.md)，后端技术设计见[技术设计用户指南](技术设计用户指南.md)。
 
-## 已有项目接管与升级
+## 接管、同步与恢复
 
-只有综合/通用研发提供 attach 和 sync。先保存可恢复的 Git 基线，再选择对应包执行；以下是综合示例，通用研发仅将包名替换为 `create-yss-harness-dev`：
+综合 CLI 示例：
 
-```bash
-npx create-yss-spec@latest attach --target-dir . --project-name "设备借用" --business-domain "内部设备管理" --dry-run
-npx create-yss-spec@latest attach --target-dir . --project-name "设备借用" --business-domain "内部设备管理" --apply
+```sh
+npx create-yss-spec@latest attach --target-dir . --project-name 设备借用 --business-domain 内部设备管理 --dry-run
+npx create-yss-spec@latest attach --target-dir . --project-name 设备借用 --business-domain 内部设备管理 --apply
 npx create-yss-spec@latest sync --target-dir . --dry-run
 npx create-yss-spec@latest sync --target-dir .
+npx create-yss-spec@latest sync --target-dir . --plan --prune
 ```
 
-attach 用于尚未由对应 CLI 管理的既有项目；已存在本家族 metadata 时使用 sync。不要把上面四条不加区分连续执行。正常 sync 保留用户修改并报告 conflict、unsafe 和上游删除项；先审阅实际计划再决定如何处理冲突。源码、.git、gitlink 和挂载点按现有保护规则保留。
-
-`update`/`upgrade` 更新 CLI 程序，`sync` 更新实例受管模板，两者不同。事务校验失败会回滚本轮文件写入；成功后的撤销使用自己保存的 Git 基线或备份，不用旧 CLI 强制反向同步。
-
-战略和专职实例本次没有自动 sync/原地迁移：用同家族新目录比较受管资产，按计划迁移，重验输入和合同，保留原实例回滚。不能跨 profile 覆盖。
+专职 CLI 示例：
 
-五家族由 `.yss-template.json`、`.yss-harness-design.json`、`.yss-harness-dev.json`、`.yss-harness-backend.json`、`.yss-harness-frontend.json` 及 profile 判定。不得删除或伪造 metadata 来切换家族。
+```sh
+npx create-yss-harness-backend@latest attach --target-dir .
+npx create-yss-harness-backend@latest attach --target-dir . --apply
+npx create-yss-harness-backend@latest sync --target-dir . --plan --prune
+npx create-yss-harness-backend@latest sync --target-dir . --apply --prune
+npx create-yss-harness-backend@latest recover --target-dir .
+```
 
-异族、多重身份、损坏 metadata、未知或矛盾 profile 会在规划/写入前被拒绝；`--force` 不能绕过，`--dry-run` 同样检查。只有在身份及路径检查通过后，force 才按该命令的覆盖语义生效。遇到拒绝先核对所用家族和目标路径，保留原目录，不用战略 init 强制替代升级。
+attach 用于尚未由该家族管理的普通项目；已有本家族 metadata 时使用 sync。先审阅计划，再选择写入命令。旧 repository-local 实例、未知 schema、多重或异族身份按 CLI 输出处理，不删除 metadata 伪装普通目录。
 
 ## 常见卡点
 
-| 现象 | 下一步 |
+| 现象 | 处理 |
 |---|---|
-| Agent 立即开始写代码 | 要求只读分诊，展示当前合同和允许路径 |
-| 文件已有但无法继续 | 检查批准、摘要、依赖和 Fresh Verification，不只看文件存在 |
-| 前端输入已验证仍不能实现 | inputs-verified 只放行计划/合同准备，先完成合同批准 |
-| --force 仍失败 | 查家族、身份、unsafe 与 gitlink，不能靠删 metadata 绕过 |
-| npm 创建后没有本手册更新 | 核对 npm 版本与包内模板 SHA，使用已核验候选包或等待正式发布 |
-| 独立子项目自报完成 | 统一管理方核对跨仓版本及业务端到端证据 |
-
-## 团队与维护者
-
-业务人员确认规则和页面；架构与研发落实到冻结接口、当前合同和实际实现仓；Reviewer 独立核验。运行时代码默认进入登记的独立仓，前端优先 pnpm，后端优先根 ./mvnw；缺工具时记录受控例外与实际命令。
-
-模板维护者先读 [AGENTS.md](../../AGENTS.md) 和 [流程裁剪](../process/harness-process-tailoring.md)，维护 canonical 事实与生成投影，运行分级验证。维护流程不混入用户的日常业务步骤。
-
-各模板与 CLI 专项手册见 [用户手册索引](用户手册索引.md)。
+| Agent 立即写代码 | 要求只读分诊，展示当前合同、允许路径和批准证据 |
+| 包验证成功仍不能实现 | 继续完成目标词汇对账、接收、计划和合同批准 |
+| `--force` 仍失败 | 修复身份、冲突、unsafe 路径或 gitlink，不绕过保护 |
+| npm 包缺少新手册 | 比对 npm 版本、CLI 版本和模板 snapshot |
+| 旧手册仍在实例 | 先用 `sync --plan --prune` 判断是否可安全清理 |
+| 单个子项目自报完成 | 由统一管理方核对跨仓版本和端到端业务证据 |
+
+各家族入口见[用户手册索引](用户手册索引.md)。模板维护者另读根 [AGENTS.md](../../AGENTS.md) 和[流程裁剪](../process/harness-process-tailoring.md)。

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

@@ -2,17 +2,16 @@
 
 ## 第一次使用
 
-1. [YSS 用户手册](用户手册.md)：五类项目选型、首次创建、确认与升级。
-2. [设备借用贯穿案例](设备借用贯穿案例.md)：输入、提示词、命令、成功标准及异常恢复。
-3. [战术设计指南](战术设计子项目用户手册.md)：批准战略如何落到设计和测试。
+1. [YSS 用户手册](用户手册.md)：四个现行家族的选型、CLI、确认、同步和恢复。
+2. [设备借用贯穿案例](设备借用贯穿案例.md)：战略、后端、前端与统一验收的完整练习。
+3. [技术设计用户指南](技术设计用户指南.md)：批准战略或 Spec 如何进入 DDD / layered-mvc 技术设计和实现合同。
 
-## 专项路线
+## 按职责进入子项目
 
-- [战略：澄清、设计、交接](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)
+- [战略设计](https://github.com/iloveZzz/yss-harness-design-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)
 
-跨项目导航使用 GitHub 链接；生成实例不需要兄弟仓或 submodules 目录。链接指向各仓 main，实际执行仍核对本地 profile、包版本和固定模板 SHA。
+既有通用研发实例按其固定版本和本地 README 维护，不再作为新项目入口。生成实例通过 GitHub 链接跨项目导航，但实际操作以本地 profile、CLI `--help`、包版本和模板 snapshot 为准。
 
-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)。
+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-backend)、[前端 CLI](https://github.com/iloveZzz/create-yss-harness-frontend)。组件专项见 [YSS UI MCP](yss-ui-mcp.md)。