create-yss-spec 3.0.1 → 3.1.3

package/template/AGENTS.md

@@ -1,131 +1,92 @@
 # AGENTS.md — AI 开发入口规则
 
-> 本文件只保存 Agent 必须首先遵守的仓库身份路由、硬门禁和禁止事项。完整生命周期、流程裁剪和 YSS 实现细则以下文引用的权威资产为准。
+> 只保留入口、硬门禁和禁令。
 
 ## 1. 首先识别仓库身份
 
-每个任务开始时先读取根目录 `yss-project.yaml`：
+先读根 `yss-project.yaml`：`template-source` 走模板维护；`project-instance` 走产品生命周期。
 
-- `repository_mode: template-source`：使用“模板维护流程”，不默认生成具体产品的 Spec、原型、OpenAPI 或垂直切片 Ticket。
-- `repository_mode: project-instance`：按产品研发生命周期分诊任务。
-- 文件缺失、schema 版本不支持或模式值非法时，停止路由并执行迁移检查；不根据目录、Git 远程或占位符猜测身份。
-
-仓库身份契约由根目录 `yss-project.yaml` 和本文件共同声明。
+- `template-source` 不生成产品 Spec、原型、OpenAPI 或垂直切片 Ticket。
+- 文件缺失、schema 不支持或模式非法时停止并迁移检查；不得按目录、Git remote 或占位符猜身份。
 
 ## 2. 单一事实来源
 
-| 事实类型                    | 权威资产                                        |
-| ----------------------- | ------------------------------------------- |
-| 领域与流程词汇                 | `CONTEXT.md`                                |
-| Agent 入口、硬门禁、禁止事项       | `AGENTS.md`                                 |
-| 主阶段、门禁、产物、工作单元、证据和稳定 ID | `docs/process/lifecycle-registry.yaml`；`docs/process/lifecycle-artifact-map.md` 为派生阅读视图 |
-| 影响面触发与 `not-applicable` | `docs/process/harness-process-tailoring.md` |
-| 模板维护强度触发与最低等级 | `docs/process/maintenance-intensity.yaml` |
-| 技能清单、来源、版本、哈希和投影目标      | `skills-lock.json`                          |
-| 技能分层、别名、默认可发现性和运行时入口 | `docs/agents/yss-skill-registry.yaml`（当前 `status: active`；实现合同编译器 / 生命周期必须消费） |
-| 数字人角色、阶段协作组、运行时绑定与生命周期会签 | `docs/agents/digital-human-roles.yaml`；`docs/agents/digital-human-roles.md` 为操作说明 |
-| 视觉令牌与组件视觉变体规范 | 根目录 `DESIGN.md`；`docs/design/design.md` 为中文治理与生命周期适配，`docs/design/tokens/*` 为派生快照 |
+| 事实 | 权威资产 |
+|---|---|
+| 词汇 | `CONTEXT.md` |
+| Agent 入口红线 | `AGENTS.md` |
+| 阶段、门禁、产物、工作单元、证据、稳定 ID | `docs/process/lifecycle-registry.yaml`；`docs/process/lifecycle-artifact-map.md` 仅为派生阅读视图 |
+| 影响面、`not-applicable`、模板维护强度 | `docs/process/harness-process-tailoring.md`、`docs/process/maintenance-intensity.yaml` |
+| Skill 来源、版本、投影、路由 | `skills-lock.json`、`docs/agents/yss-skill-registry.yaml` |
+| 数字人角色、运行时与会签 | `docs/agents/digital-human-roles.yaml` |
+| 视觉规范 | `DESIGN.md`；治理见 `docs/design/design.md` |
 
-README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或解释上述事实，不重复定义同一规则。`CLAUDE.md` 是 Claude Code 入口指针，不是第二套 Agent 规则。
+其他文档和派生视图只引用，不重复定义。
 
 ## 3. 标准文档语言与规范语汇
 
-- 所有面向业务、产品、架构、实施、审查、发布和复盘的落地文档，正文统一使用简体中文。
-- 英文专有名词、代码标识、API 路径、schema、类名、方法名、枚举值、错误码、命令、文件名和协议 metadata 保持原样。
-- 新流程统一使用 Spec、Ticket、`to-spec`、`to-tickets`。过时术语和技能名只能出现在迁移指南或明确标注的旧项目上下文。
-- `CONTEXT.md` 是 Spec 构建及其落地工具链的统一语言输入，也是所有会创建或修改稳定业务、产品、架构、实施、审查、发布和复盘资产的强制前置上下文。`yss-product-lifecycle`、其原生 work unit，以及 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等显式兼容入口，在规划、起草、评审、拆 Ticket 或实现前都必须读取并持续消费它；工具无法读取或消费时必须暂停并返回 `blocked`，不得凭临场翻译、同义词或局部上下文继续。
-- 稳定业务术语必须先在 `CONTEXT.md` 中登记 PascalCase `英文标识`，再进入 Spec、原型、契约、Ticket、代码或验证资产；代码类型 / 字段与契约 property 使用该词干按 `CONTEXT.md` 文首规则变形。改中文术语或英文标识都先回写 `CONTEXT.md`，并重新检查受影响资产；与词汇或 ADR 冲突时立即指出并先解决冲突。
+- 生命周期文档用简体中文；英文专名、代码 / API 标识、schema、命令、文件名和 metadata 原样保留。新流程统一用 Spec、Ticket、`to-spec`、`to-tickets`。
+- 规划至实现全程消费根 `CONTEXT.md` 及文首合同；不可读即 `blocked`。稳定术语先登记，再以 `<ContextId>/<EnglishIdentifier>` 引用；跨上下文用 `Global/<EnglishIdentifier>`。
+- 每仓只允许根目录一个大小写精确的 `CONTEXT.md`；禁止嵌套、`CONTEXT-MAP.md`、跨仓路径和伪锚点。
+- `project-instance` 每个工作单元批准或流转前完成 `context_reconciliation`；缺失、冲突或摘要漂移即 `blocked`。`template-source` 校验模板合同并记录带原因的 `not-applicable`。
 
 ## 4. `template-source` 模板维护路由
 
-按“影响面 → 单一事实来源 → 投影 / 派生资产 → 分级证据”维护。强度分级、最低证据和 checkpoint 合同见 `docs/process/harness-process-tailoring.md`。
-
-- 创建、修改或退役 skill 时使用 `maintaining-skills`，并先按 `docs/process/harness-process-tailoring.md` 判定 L1 / L2 / L3；L3 日常记录维护者自检与 fresh verification，正式发布前执行完整模板门禁。
-- `.agents/skills` 是跨 Agent 共享技能的权威内容；`.claude/skills`、`.codex/skills`、`.cursor/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的共享技能是生成投影，禁止分别手工修改。Cursor 的契约运行时入口是 `.cursor/skills`；不得把 canonical `.agents/skills` 与某个平台投影当作同权双入口。
-- 模板维护默认以 `scripts/verify-template-fast` 完成 `implementation-ready`；显式晋级审查时用 `scripts/verify-template-candidate`，首次冻结前和最终发布前仍必须执行完整 `scripts/verify-template`。后者是不可裁剪的模板发布阻断门禁。模板与外部 `create-yss-spec` 的跨仓库契约未完成集成验证时，不得声称可发布。
+- 按“影响面 → 事实源 → 投影 / 派生 → 分级证据”维护；改 Skill 必须用 `maintaining-skills`，并按 `docs/process/harness-process-tailoring.md` 判定 L1 / L2 / L3。
+- `.agents/skills` 是共享 Skill 权威目录；其他 Agent root 下的同名 Skill 是生成投影，不得手改或与 canonical 并列维护。
+- 内循环运行 `scripts/verify-template-fast`；晋级审查运行 `scripts/verify-template-candidate`；首次冻结和最终发布前运行不可裁剪的 `scripts/verify-template`。外部 `create-yss-spec` 集成未闭合不得称可发布。
 
 ## 5. `project-instance` 产品研发路由
 
-先用 `docs/process/harness-process-tailoring.md` 判定变更类型、影响面和最近可信阶段，再按 `docs/process/lifecycle-registry.yaml` 执行命中的工作单元和条件门禁。
-
-下表是与 `yss-product-lifecycle` 对齐的阶段级导航索引；阶段、工作单元、技能和门禁不是同一层，条件细节以注册表及 lifecycle skill references 为准。
-
-| 主阶段（registry） | 原生工作单元 | 技能入口（按影响面裁剪） | 关键产物 / 门禁 |
-|---|---|---|---|
-| 入口分诊 `stage.entry-triage` | `work-unit.entry-triage` | `yss-product-lifecycle` | 仓库身份、影响面、最近可信阶段；`gate.repository-identity-valid` |
-| Discovery `stage.discovery` | `work-unit.discovery-opportunity`、`work-unit.discovery-requirements`、`work-unit.domain-strategy-design`、`work-unit.stage-decision` | `yss-product-lifecycle`；按事实 / 领域影响使用 `competitive-intelligence`、`yss-research`、`grilling`、`domain-modeling`、`yss-stage-decision` | Discovery、用户/MVP/非目标/成功标准、测试 seam；必要时 DDD 战略设计与阶段决策包；`gate.domain-strategy-approved`、`gate.stage-decision-package-approved` |
-| Spec / 功能架构 `stage.spec-architecture` | `work-unit.spec-synthesis` | `yss-product-lifecycle`；`to-spec` 仅为显式兼容入口 | Spec、产品总体设计、功能架构；必要时 Spec Delta；`gate.spec-baseline-approved` |
-| 产品设计 `stage.product-design` | `work-unit.prototype-design` | `yss-prototype-stage` 为主合同：`yss-design-system` → 低保真 / 状态矩阵 → 独立 `prototype-review` → H1/H2 档位路由 → 档位适配器 → 浏览器 / Design QA / 无障碍验证；`yss-antd-design` 只用于相关 H2，原型阶段禁止调用生产实现技能 `yss-ui` | 交互说明、低保真、状态矩阵、原型交付物；`gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` |
-| 系统 / 数据架构与工程契约 `stage.system-data-engineering` | `work-unit.technical-analysis` | `yss-implementation-contract-compiler`；按影响使用 `yss-openapi-governance`、`yss-openapi-draft-review`、`codebase-design`、`implementation-repo-onboarding`、`yss-tactical-design` | OpenAPI Draft / Freeze、数据架构、工程基线、架构审查；无 API 影响记录；必要时 Tactical DDD Check；`gate.openapi-draft-reviewed`、`gate.design-reviewed`、`gate.openapi-frozen`、`gate.engineering-baseline-accepted`、`gate.architecture-reviewed` |
-| Ticket 正式化 `stage.ticket-formalization` | `work-unit.ticket-decomposition` | `yss-product-lifecycle` + `yss-implementation-contract-compiler`；`to-tickets` 仅为显式兼容入口 | 功能父 Ticket、垂直切片、Slice Implementation Contract；切片初始 `ready-for-human`；`gate.slice-contract-approved`、`gate.slice-ready-for-agent` |
-| 垂直切片实现 `stage.vertical-slice-implementation` | `work-unit.slice-implementation` | `yss-implementation-contract-compiler` + `tdd`；UI 影响追加 `yss-ui`、`yss-page-module-development` 及条件专项 skill；`implement` 仅为显式兼容入口 | 前后端代码、TDD、YSS Skill Execution Result；仅允许 `ready-for-agent` 且合同当前 |
-| 验证 / 发布 / 复盘 `stage.verification-release-retrospective` | `work-unit.frontend-implementation-verification`、`work-unit.code-review`、`work-unit.release-and-retrospective` | `code-review`（唯一入口，Standards 消费 YSS / Alibaba 专项检查输入）；UI 影响追加 `yss-ui` + `yss-design-system`；发布 / 复盘由 `yss-product-lifecycle` 持有 | 不可变候选快照、独立审查、findings 按合同分流、fresh verification、发布 / 回滚证据、复盘；UI 影响追加 `gate.frontend-implementation-verified`；`gate.release-ready` |
-
-- 生命周期注册表中的条件门禁全部按影响面强制。命中触发条件时必须完成；未命中时只记录 `not-applicable` 及原因，不生成空文档；不得把产物、工作单元或证据统称为门禁。
-- 安全 / 权限不设独立生命周期资料或专属门禁。日常功能不做额外登记、`not-applicable` 或推导校验；只有需求或冻结资产明确要求改变认证、授权、租户隔离、敏感数据或合规行为时，才把该行为写入普通 Spec、API、架构、验收和测试 seam，并仅按实际 UI、API、Backend、Data、High-risk 影响触发既有门禁。普通 action 注册、沿用既有认证中间件、未变化的 `401` / `403`、一般字段、SQL / DDL / 迁移和上传 / 下载本身不构成安全 / 权限专项。
-- `seam-deferred` 只能显式记录风险、责任人、后续 Ticket、验证计划和目标版本或发布日期。
-- 新功能或较大变更先进入 `yss-product-lifecycle` 的原生 Discovery / 需求分析工作单元；`grill-with-docs` 与 `to-spec` 仅作为用户显式兼容入口，Spec 基线和产品设计影响的完整判定以注册表和裁剪规则为准。
-- API 契约变更先形成 OpenAPI 3.1 Draft，经必要的工程基线、系统 / 数据架构和设计审查后 Freeze，再进入实现。
-- Spec Delta 只记录相对既有冻结 Spec 基线的高风险行为差异；全新产品、全新模块和低风险调整不生成 Spec Delta。
-- OpenAPI Freeze 或无 API 影响记录完成后，由生命周期原生 Ticket 正式化工作单元拆成可独立验证的窄垂直切片；用户显式 `to-tickets` 仅作为兼容入口，禁止只按 Adapter / Application / Domain / Infrastructure 横向拆分。
+主流程：分诊 → Discovery → Spec / 功能架构 → 产品设计 → 工程契约 → Ticket → 切片 → 验证 / 发布 / 复盘。
+
+- 先按 `docs/process/harness-process-tailoring.md` 判定影响面和最近可信阶段，再由 `yss-product-lifecycle` 执行 `docs/process/lifecycle-registry.yaml`；阅读导航见 `docs/process/lifecycle-artifact-map.md`。
+- 命中门禁必须完成；仅未命中时记录带原因的 `not-applicable`，不得生成空文档或混淆门禁、产物、工作单元、证据。安全 / 权限写入普通 Spec、契约、架构、验收和 seam，按实际影响触发门禁。
+- 新功能和较大变更先进入 Discovery；`grill-with-docs`、`to-spec`、`to-tickets`、`implement` 仅为用户显式兼容入口。API 变更先形成 OpenAPI 3.1 Draft，审查后 Freeze，再实现。
+- Spec Delta 只记冻结基线的高风险行为差异。OpenAPI Freeze 或无 API 影响记录后拆窄垂直切片，禁止仅按技术层横拆。
+- `seam-deferred` 必须记录风险、责任人、后续 Ticket、验证计划和目标版本或发布日期。
 
 ## 6. Ticket 与状态
 
-- 每个功能先建立功能父 Ticket，用于汇总 Spec、设计、审查、OpenAPI Freeze、阻塞项和阶段证据。
-- Spec 初稿、产品设计、原型、OpenAPI Draft 和待冻结资产使用 `ready-for-human`。
-- 只有通过必要门禁、阻塞边已清除并具备直接实现条件的垂直切片 Ticket，才能使用 `ready-for-agent`。
-- Ticket、Spec 和阶段证据按 `docs/agents/issue-tracker.md` 选定的主 tracker 持久化；Git remote 不代表 tracker 选择，平台不可用时按该文档生成待发布草案。五态标签见 `docs/agents/triage-labels.md`。
+- 每个功能先建父 Ticket，汇总阶段资产、审查、阻塞和证据。
+- Spec、设计、原型、OpenAPI Draft 和待冻结资产使用 `ready-for-human`；只有门禁通过、阻塞清除且可直接实现的垂直切片才能使用 `ready-for-agent`。
+- 按 `docs/agents/issue-tracker.md` 持久化主 tracker，不从 Git remote 推断；平台不可用时生成待发布草案。五态见 `docs/agents/triage-labels.md`。
 
 ## 7. 实现与 YSS 路由硬门禁
 
-进入实现时先读 `docs/process/implementation-repo-integration.md`，登记实现仓库、项目根、分支、CI、验证命令和回滚点；再使用 `yss-implementation-contract-compiler` 编译最小 skill 集合与当前实现合同。
-
-- 无可复用工程时，先确认外部目标仓库或输出目录，再使用 `yss-ddd-scaffold-generator` / `yss-frontend-scaffold-generator`；当前仓库缺少 frontend / backend 目录不改变此路由。
-- 脚手架只在 `scaffold_status=required` 且受控生成合同已持久化、获得生命周期批准后运行；它只产生机械骨架，业务行为回到 实现合同编译器 并使用 `behavior-tdd`。
-- 正式垂直切片必须消费已批准、已持久化且版本当前的 Slice Implementation Contract。实现合同编译器 只生成草案，不批准合同、不设置 `ready-for-agent`、不宣布完成。合同 schema、Backend 子合同和证据字段以 `yss-implementation-contract-compiler` references 为准。
-- UI 影响切片必须在 `ready-for-agent` 前具备通过校验的 `frontend_implementation_plan`，实现完成后补齐 `frontend_implementation_verification`；截图 / 视觉回归、状态与交互、console warning 和实际 `pnpm` 退出码均须有证据，不能只做 type-check 或声称“已对齐”。
-- 前端测试、type-check 与构建优先使用 `pnpm`；后端校验、测试与编译优先使用项目根 `./mvnw`。不要默认 `npm` / `yarn` 或裸 `mvn`。既有仓库确实没有 pnpm 或 Maven Wrapper 时，必须记录受控例外和实际命令。登记字段见 `docs/process/implementation-repo-integration.md`。
-- 路径越界、证据缺失、未执行验证、`drift`、`violation` 或 `new_impacts` 时停止实现并重新路由。
-
-实现细则由已批准合同、YSS skills 和实现接入文档定义；`AGENTS.md` 只保留入口与边界。
+- 实现前按 `docs/process/implementation-repo-integration.md` 登记仓库、项目根、分支、CI、验证命令、回滚点；再用 `yss-implementation-contract-compiler` 编译最小 Skill 集和当前合同。
+- 无工程先确认外部仓库或输出目录。Backend `scaffold_status=required` 时，由生命周期推荐 `domain-driven` / `layered-mvc`，用户逐项目确认后路由；Frontend 用 `yss-frontend-scaffold-generator`。缺目录不改路由。
+- 脚手架仅在 `scaffold-architecture-decisions.yaml` 已确认且当前、schema v3 合同已持久化并获批准后无交互运行，只生成机械骨架。既有工程不得重选或覆盖；架构转换单独立项。
+- 正式切片只消费已批准、已持久化且当前的 Slice Implementation Contract；编译器只起草，不批准、不设置 `ready-for-agent`、不宣布完成。
+- UI 切片在 `ready-for-agent` 前须有已校验的 `frontend_implementation_plan`，实现后补 `frontend_implementation_verification`，覆盖截图 / 视觉回归、状态交互、console warning、实际 `pnpm` 退出码。
+- 前端验证优先 `pnpm`，后端优先根 `./mvnw`；缺少时记录受控例外和实际命令。
+- 路径越界、证据缺失、验证未执行、`drift`、`violation` 或 `new_impacts` 时停止实现并重新路由。
 
 ## 8. 专项任务的强制入口
 
-本表补充跨阶段的触发型技能；主阶段对应的原生工作单元和条件技能以第 5 节、`yss-product-lifecycle` 及 `orchestration-contract.yaml` 为准。
-
-| 触发情形 | 必须使用 |
-|---|---|
-| 技术事实、标准、第三方 API 或框架行为影响决策，或外部证据进入领域战略 / 阶段决策 | `yss-research`；技术事实使用 `technical-evidence`，战略决策证据使用 `strategy-evidence`；旧名 `research` 仅为 deprecated alias |
-| 竞品、市场或用户口碑事实 | `competitive-intelligence` |
-| UI 设计、原型、组件或主题 | `yss-prototype-stage` 持有阶段合同：`yss-design-system` → 低保真 / 状态矩阵 → 独立 `prototype-review` → 确定性选择 H1 视觉或 H2 流程 → 档位适配器 → 浏览器 / 统一 Design QA / 无障碍验证。`yss-antd-design` 仅用于相关 H2；原型阶段不得调用 `yss-ui`。真实 YSS/AntDV 组件与 lockfile 事实只在前端实现计划、已批准切片的实现和实现还原验证中消费 |
-| Bug、测试失败或性能回退 | `diagnosing-bugs` 建立可复现反馈，再用 `tdd` |
-| merge / rebase 冲突 | `resolving-merge-conflicts` |
-| 架构治理、难测模块或深模块设计 | `codebase-design`；`improve-codebase-architecture` 仅作为用户显式兼容入口 |
-| 跨线程、跨仓库、上下文过长或原型结论回流 | `handoff` 或等价交接记录 |
-| 数字人角色、Agent 运行时协同或生命周期会签 | 先读 `docs/agents/digital-human-roles.yaml`。职称实例叠加在编排器上，不另起生命周期，不批准 Slice 合同、不设 `ready-for-agent`、不宣布可发布 |
-| 本地知识库 init / refresh / rebuild，或要把研究结果落成持久 wiki | `llm-wiki`（落成持久 wiki 用 `ingest`；已映射 live 源变了用 `refresh`）。`template-source` 的 wiki-root 为 `.template-source/wiki`；`project-instance` 不附带源仓库编译树，需要时在仓库根 `wiki/` 执行 `init` |
-
-业务行为默认按 `tdd` 的 `behavior-tdd` 模式使用已确认的公开 seam 逐切片实现。一次性生成、纯配置或流程文档不适用代码 TDD 时，必须记录例外理由和可执行验证方式。
+- 技术事实、标准、第三方 API 或框架行为用 `yss-research`（`technical-evidence` / `strategy-evidence`）；竞品、市场、口碑用 `competitive-intelligence`。
+- 产品设计由 `yss-prototype-stage` 持有合同并调用设计系统、独立评审、H1 / H2 适配器；原型禁用 `yss-ui`。真实组件事实只用于实现计划、已批准实现和还原验证。
+- 数字人协同或会签先读 `docs/agents/digital-human-roles.yaml`；角色不得另起生命周期、批准 Slice 合同、设置 `ready-for-agent` 或宣布可发布。
+- 业务行为默认按 `tdd` 的 `behavior-tdd` 使用已确认公开 seam 逐切片实现；一次性生成、纯配置或流程文档不适用时，记录例外理由和可执行验证。
 
 ## 9. 工作区与实现仓库边界
 
-当前仓库默认是研发管理仓库，运行时代码优先位于已登记的独立实现仓库（`repository_scope: external-repository`）。只有用户明确选择当前仓库承载实现代码时，才使用同源的 `apps/backend/<project>/` 或 `apps/frontend/<project>/`（`harness-apps`），或以 Git submodule 把独立实现仓挂到同一 `apps/` 布局（`git-submodule`）。三种 scope 必须用登记字段、Git 身份和工作树 gitlink 区分；空 gitlink、detached HEAD 或 `--force` 覆盖挂载点不得当成普通目录。
-
-`apps/backend/` 和 `apps/frontend/` 只是项目容器；`app/backend/`、`app/frontend/` 及其子路径禁止作为工程输出。`git-submodule` 不得登记为 `harness-apps`，也不得把实现源码复制进 Harness。完整登记字段、嵌套 Git 授权和跨仓约束见 `docs/process/implementation-repo-integration.md`。
+- 运行时代码默认进入已登记的 `external-repository`；仅用户明确选择时使用 `apps/backend/<project>`、`apps/frontend/<project>` 的 `harness-apps`，或以真实 gitlink 使用 `git-submodule`。三种 scope 按实现接入文档登记。
+- 禁止向 `app/backend/`、`app/frontend/` 输出；空 gitlink、detached HEAD、`--force` 挂载点不得视为普通目录；不得把 submodule 登记为 `harness-apps` 或复制源码冒充。
 
 ## 10. 独立审查、验证和追踪
 
-- 实现者不能承担命中的独立审查（含数字人）。模板维护的 L3 日常路径使用维护者自检；L2 仍按需使用聚焦独立审查，正式发布仍执行完整模板门禁。模板发布、代码切片和高风险变更仍必须满足各自独立审查要求。产品切片与模板维护共用同一 finding 闭环：`violation` 由实现者在原合同路径修复后重新捕获并全轴复审；`drift` / `new_impacts` 使合同 `stale` 并回 实现合同编译器。审查者不得写实现。命中后的 mandatory 不得豁免；未命中才 `not-applicable`。
-- 任何“完成 / 可合并 / 可发布”结论必须基于 fresh verification，不接受“之前跑过”或实现者自述。
-- 会签门禁按 `docs/agents/digital-human-roles.yaml` 的 `gate_policy` 关闭，会签文件经 `scripts/verify-approval-record` 核验；`gate.release-ready`、对外商务承诺和运行时外部副作用仍须生物人。
-- 在会签暂停、handoff、进入实现、合并或发布边界集中同步范围、验证证据、风险、会签点、Ticket 状态和下一步；阻塞、责任人变化或资产单独批准时立即同步。
-- Git checkpoint 只包含本轮明确范围；获得用户授权后才提交或推送。
-- 发布后或阶段性完成后做复盘判断；出现架构返工、验证返工、IMPORTANT / CRITICAL review finding 或人工确认延期时，落简体中文复盘并修订权威资产。
+- 实现者不做独立审查，Reviewer 不写实现；代码审查统一用 `code-review`。mandatory 不豁免；`violation` 修复后重审，`drift` / `new_impacts` 使合同 `stale` 并回编译器。
+- “完成 / 可合并 / 可发布”仅基于 Fresh Verification；历史结果、自述无效。
+- 会签按角色表 `gate_policy` 并经 `scripts/verify-approval-record --require-approved` 核验；`user_decision_policy` 命中的关键决定必须先展示可审阅资产，再取得提问者或其明确指定负责人的真实回复。无回复保持等待，数字人不能代答；原始来源、范围、复用和失效见生命周期 `references/user-decisions.md`。发布、商务承诺、运行时外部副作用仍须生物人。
+- 会签暂停、handoff、实现、合并、发布边界同步范围、证据、风险、会签点、Ticket 状态和下一步。Git checkpoint 只含本轮范围；提交 / 推送须用户授权。
+- 发布或阶段完成时判断复盘；架构 / 验证返工、IMPORTANT / CRITICAL finding、人工确认延期时，落中文复盘并修订事实源。
 
 ## 11. Subagent 协同
 
-使用 subagent 或其它 Agent 运行时前按 `docs/process/subagent-collaboration.md` 定义任务包和不重叠的写入范围，并同时写明数字人角色、`runtime_id`、从角色表复制的 `core_skills` / `forbidden_skills` 与 Explorer / Drafter / Worker / Reviewer / Verifier 执行态。实现者不担任独立审查者；仓库身份、Ticket 最终状态、Git checkpoint、Slice 合同批准和完成结论仍由主控数字人按编排器规则决定。会签恢复前校验 `scripts/verify-approval-record`。写隔离靠任务包；共享工作区不是默认沙箱。
+- 使用 subagent 或其他运行时前读 `docs/process/subagent-collaboration.md`，建立含角色、`runtime_id`、执行态、技能约束和不重叠写范围的任务包；共享工作区不是安全边界。
+- 仓库身份、Ticket 最终状态、Git checkpoint、Slice 合同批准和完成结论由主控裁决；实现者不得兼任独立审查者或会签自己的资产。
 
 ## 12. 测试质量基线
 
-模板推荐值为 Domain / Application `>= 90%`、API `>= 80%`、前端组件 `>= 75%`、已明确的关键流程 `100% E2E`。只有项目实例在测试策略中明确采纳或覆盖后才构成 CI 门禁；未定义关键流程清单时，不声称其 E2E 覆盖率达到 100%。
+模板推荐 Domain / Application `>= 90%`、API `>= 80%`、前端组件 `>= 75%`、关键流程 `100% E2E`；`project-instance` 明确采纳后才是 CI 门禁，未定义关键流程不得称 100% E2E。

package/template/CONTEXT.md

@@ -1,8 +1,11 @@
-# 领域上下文
+---
+context_schema_version: 1
+---
+# 业务上下文
 
-本文档是项目的领域词汇表，只记录稳定业务语言和协作概念，不记录实现细节、计划草稿或架构说明。
+本文档是项目的业务词汇表，只记录稳定业务语言和协作概念，不记录实现细节、计划草稿或架构说明。
 
-`英文标识` 是 PascalCase 词干，不是英语释义。`## 业务术语` 必须填写该列；`## 流程术语` 填 `—`。代码类型名、字段名和契约 property 由该词干变形：类名 = 词干 + YSS 工程后缀；字段与 JSON property 为 camelCase；数据库列为 snake_case；枚举常量为 UPPER_SNAKE。工程后缀以 YSS skill 和当前工程惯例为准，不作为领域词写入本表。JSON 与 Java 字段不一致时，以 DTO wire shape / OpenAPI 为准，不在本表另开列。改中文术语或英文标识都是统一语言变更，必须先回写本表。`避免 / 备注` 同时记录禁用中文和禁用英文别名。
+`英文标识` 是 PascalCase 词干，不是英语释义。`## 业务术语` 必须填写该列，并使用 `Global` 或“业务边界与规则设计”中已确认的 PascalCase `context_id` 填写 `适用业务责任区`；术语稳定身份仍是 `<ContextId>/<EnglishIdentifier>`，该编号由 Agent 维护，业务人员只需确认名称、含义和适用范围。`## 流程术语` 的英文标识填 `—`。代码类型名、字段名和契约 property 由该词干变形：类名 = 词干 + YSS 工程后缀；字段与 JSON property 为 camelCase；数据库列为 snake_case；枚举常量为 UPPER_SNAKE。工程后缀以 YSS skill 和当前工程惯例为准，不作为业务词写入本表。JSON 与 Java 字段不一致时，以 DTO wire shape / OpenAPI 为准，不在本表另开列。改中文术语、英文标识、含义或适用业务责任区都是统一业务词汇变更，必须先回写本表。`避免 / 备注` 中的禁用别名使用 `避免：别名一、别名二`，其他说明使用 `备注：...`。
 
 只有在计划、分诊、调试或架构讨论中明确沉淀出稳定语言时，才新增术语。
 
@@ -19,6 +22,7 @@
 | 主控数字人 | 运行 `yss-product-lifecycle` 的协调实例。 | — | 不是第八个业务职称；默认兼任项目经理。 |
 | 角色配置 | 某数字人角色的关注阶段、技能包、可起草产物和禁止事项。 | — | 不是独立编排器，也不含平台群聊人数。 |
 | 生命周期会签 | 指定数字人或生物人关闭 `gate.*` / 独立审查并写入 `evidence.approval-record`。 | — | 不是运行时副作用审批。会签人由 `docs/agents/digital-human-roles.yaml` 的 `gate_policy` 指定。起草者不得会签自己起草的资产。`paused-human-gate` 表示等待该会签人，不是必须生物人。 |
+| 用户决定 | 提问者或其明确指定的生物人负责人针对已展示资产、版本及范围作出的可追溯回复。 | — | 数字人审查不能代答；原始回复、指定依据及批准范围按用户决定协议记录。 |
 | 运行时副作用审批 | 对发消息、改生产、付款、删数据等工具动作的账号级确认。 | — | 点 Allow 不等于门禁已批准或可发布。避免只称「Grok 平台审批」。 |
 | Ticket 状态 | Tracker 五态：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。 | — | 不要称为数字人角色或「标准角色」。 |
 | 阶段协作组 | 某阶段需要共同可见会签的逻辑成员集合。 | — | 不是某个产品的群聊；平台人数上限只写在对应 `runtimes`。 |
@@ -30,7 +34,7 @@
 | Matt Engineering Skills | 来自 `mattpocock/skills` 的轻量工程流程技能集合。 | — | 用于澄清、Spec、Ticket、实现、TDD、诊断、审查和架构治理，不替代 YSS 专项规范。 |
 | 上游技能基线 | 从外部技能源锁定的可追溯 revision 及其未经项目适配的原始内容。 | — | 不等同于项目当前实际生效的 skill；上游更新不得直接覆盖 YSS 适配。 |
 | YSS 技能适配 | 在上游技能基线之上，为 YSS 仓库身份、门禁、状态、授权和专项规范保留的可追溯差异。 | — | 必须同时保留上游内容哈希、有效内容哈希和适配依据，不作无记录的直接 fork。 |
-| YSS skills | 本项目内置的 YSS 工程规范技能。 | — | 用于 DDD、UI、OpenAPI、Repository、Controller、DTO、组件和编码规范。 |
+| YSS skills | 本项目内置的 YSS 工程规范技能。 | — | 用于业务方案设计、UI、OpenAPI、后端工程、组件和编码规范。 |
 | 技能投影 | 从权威共享技能生成、供特定 Agent root 加载的同步副本。 | — | 投影不是独立维护的技能源，不应在各 Agent root 中分别修改。 |
 | Spec | 记录用户问题、解决方案、用户故事、关键决策、验收标准和测试 seam 的产品研发规格。 | — | 新资产统一使用 Spec；旧规格称谓只在迁移记录中保留。 |
 | Spec Delta | 记录相对于既有冻结 Spec 基线的 `ADDED / MODIFIED / REMOVED` 行为、验收场景和测试映射。 | — | 不用于全新产品或全新模块，也不替代完整 Spec、OpenAPI 或架构资产。 |
@@ -57,6 +61,7 @@
 | `review-ready` | 模板维护候选已完成 candidate 核验、首次完整发布门禁和摘要冻结，可以派发独立审查。 | — | Reviewer 必须消费同一候选摘要；候选字节变化后旧审查失效。 |
 | `release-ready` | 模板维护冻结候选已经通过独立审查和最终完整 Fresh Verification。 | — | 仍不替代 `gate.release-ready` 所需的生物人发布裁决。 |
 | 实现验证命令 | 前端测试 / 构建优先 `pnpm`，后端校验 / 测试 / 编译优先 `./mvnw`。 | — | 不要默认 `npm`、`yarn` 或裸 `mvn`；仓库确实缺少 pnpm 或 Maven Wrapper 时记受控例外。 |
+| 脚手架架构选择 | 新建后端工程在工程基线中对 `domain-driven` 与 `layered-mvc` 的结构化选择；Agent 提供证据化推荐，用户确认后由生命周期批准并供脚手架合同消费。 | — | 不是新门禁，也不是生成器内的交互参数；缺失、未确认或摘要漂移时阻断生成。 |
 | 测试质量基线 | 项目实例明确采纳的覆盖率阈值、关键流程清单和受控例外。 | — | 模板推荐值本身不构成可执行门禁；未定义关键流程时，不得声称其 E2E 覆盖率达到 100%。 |
 | 主阶段 | 对相邻研发目标、工作单元和退出条件的粗粒度生命周期分组。 | — | 不等同于门禁编号，也不因增加门禁而自动增加主阶段。 |
 | 生命周期门禁（条件强制门禁） | 只有当影响面命中触发条件时才必须裁决的生命周期审查点。 | — | 未触发时记录 `not-applicable` 及原因，不生成空文档；门禁不是产物、工作单元或证据的统称。 |
@@ -64,6 +69,10 @@
 | 工作单元 | 具有明确输入、输出、允许动作和完成条件的一次有界执行。 | — | 不等同于主阶段或门禁；一个主阶段可以包含多个工作单元。 |
 | 执行证据 | 用于证明工作单元结果、门禁裁决或完成结论的可读取引用和实际验证记录。 | — | 口头声明、计划执行的命令或无法解析的引用不构成执行证据。 |
 | 单一事实来源（Single Source of Truth） | 对某一类流程事实拥有唯一定义权的权威资产。 | — | 其他资产只引用或解释，不重复定义同一规则。 |
+| 战略交接快照包 | 将批准的战略资产及证据冻结为可离线验证的完整目录或 ZIP，并提供规则和场景的派生索引。 | — | 源规则由战略方维护；包内快照与索引不成为目标仓词汇权威。 |
+| 后端交付包 | 将后端当前切片的战略基线、冻结接口、批准合同及构建、部署和验证证据绑定为可独立接收的交付快照。 | — | 验包通过不代表真实服务当前可用，也不代表前端已获准实现。 |
+| 前端联合接收 | 前端对战略交接快照与后端交付包进行版本、词汇、场景、接口和运行条件核验的过程。 | — | 输入就绪允许准备实现计划和合同；写代码仍需批准且当前的 Slice Implementation Contract。 |
+| 战术承接记录 | 将源规则和关键场景关联到战术落点、测试 seam、处置结论及依赖切片的结构化记录。 | — | 延期登记不等于依赖切片可实现；冲突回交战略方，未知依赖扩大阻断。 |
 | 流程模板资产 | 可被不同项目复用的文档模板、技能说明、校验脚本、流程规范和目录占位文件。 | — | 不包含某个具体产品的 Spec、设计、OpenAPI 或 Ticket。 |
 | 模板维护流程 | 用于评估影响、修改权威资产、同步投影、执行压力验证并审查模板演进的工作流。 | — | 面向模板源仓库，不默认生成具体产品的 Spec、原型、OpenAPI 或垂直切片 Ticket。 |
 | 模板发布门禁 | 模板源发布前必须通过的结构、技能同步、流程语义和压力场景验证集合。 | — | 不等同于只检查文件存在、Markdown 链接或 YAML 语法。 |
@@ -94,4 +103,7 @@
 
 ## 业务术语
 
-`project-instance` 在本节新增产品对象。每一行必须有 PascalCase `英文标识`；缺该列视为统一语言未冻结。模板源不放虚构业务行。
+`project-instance` 在本节新增产品对象。每一行必须有 PascalCase `英文标识`；缺该列视为统一业务词汇未冻结。模板源不放虚构业务行。
+
+| 术语 | 含义 | 英文标识 | 适用业务责任区 | 避免 / 备注 |
+|---|---|---|---|---|

package/template/DESIGN.md

@@ -1,24 +1,30 @@
 ---
 version: alpha
 name: YSS Enterprise Design System
-description: A machine-readable visual design contract for YSS enterprise applications. It complements the product lifecycle and does not define product behavior, API contracts, permissions, or business states.
+description: A machine-readable compact visual contract for YSS enterprise applications, aligned with Ant Design v6 semantic tokens and the experimental Antdv Next provider. It complements the product lifecycle and does not define product behavior, API contracts, permissions, or business states.
 
 colors:
   primary: "#3371ff"
-  primary-hover: "#5c8dff"
-  primary-active: "#245bdb"
-  on-primary: "#000000"
+  primary-control: "#245bdb"
+  primary-control-hover: "#2f68eb"
+  primary-active: "#0958d9"
+  primary-bg: "#e6f4ff"
+  on-primary: "#ffffff"
   text: "rgba(0, 0, 0, 0.88)"
   text-secondary: "rgba(0, 0, 0, 0.65)"
   text-tertiary: "rgba(0, 0, 0, 0.45)"
   canvas-layout: "#f0f2f5"
   surface: "#ffffff"
+  surface-elevated: "#ffffff"
   surface-subtle: "#fafafa"
   border-secondary: "#f0f0f0"
   success: "#52c41a"
+  success-bg: "#f6ffed"
   warning: "#faad14"
+  warning-bg: "#fffbe6"
   error: "#f5222d"
-  selected: "#e6f4ff"
+  error-bg: "#fff2f0"
+  info-bg: "#e6f4ff"
 
 typography:
   body:
@@ -70,134 +76,172 @@ spacing:
 
 components:
   button-primary:
-    backgroundColor: "{colors.primary}"
+    backgroundColor: "{colors.primary-control}"
     textColor: "{colors.on-primary}"
     typography: "{typography.button}"
     rounded: "{rounded.md}"
-    padding: "{spacing.xs} {spacing.md}"
-    height: 32px
+    padding: "{spacing.xxs} {spacing.sm}"
+    height: 28px
   button-primary-hover:
-    backgroundColor: "{colors.primary-hover}"
+    backgroundColor: "{colors.primary-control-hover}"
     textColor: "{colors.on-primary}"
     typography: "{typography.button}"
     rounded: "{rounded.md}"
-    padding: "{spacing.xs} {spacing.md}"
-    height: 32px
+    padding: "{spacing.xxs} {spacing.sm}"
+    height: 28px
   button-primary-disabled:
     backgroundColor: "{colors.border-secondary}"
     textColor: "{colors.text-tertiary}"
     typography: "{typography.button}"
     rounded: "{rounded.md}"
-    padding: "{spacing.xs} {spacing.md}"
-    height: 32px
+    padding: "{spacing.xxs} {spacing.sm}"
+    height: 28px
   button-default:
     backgroundColor: "{colors.surface}"
     textColor: "{colors.text}"
     typography: "{typography.button}"
     rounded: "{rounded.md}"
-    padding: "{spacing.xs} {spacing.md}"
-    height: 32px
+    padding: "{spacing.xxs} {spacing.sm}"
+    height: 28px
   input-default:
     backgroundColor: "{colors.surface}"
     textColor: "{colors.text}"
     typography: "{typography.body}"
     rounded: "{rounded.md}"
-    padding: "{spacing.xs} {spacing.sm}"
-    height: 32px
+    padding: "{spacing.xxs} {spacing.xs}"
+    height: 28px
   input-error:
     backgroundColor: "{colors.surface}"
     textColor: "{colors.text}"
     typography: "{typography.body}"
     rounded: "{rounded.md}"
-    padding: "{spacing.xs} {spacing.sm}"
-    height: 32px
+    padding: "{spacing.xxs} {spacing.xs}"
+    height: 28px
   table-header:
     backgroundColor: "{colors.surface-subtle}"
     textColor: "{colors.text}"
     typography: "{typography.body-strong}"
     padding: "{spacing.xs} {spacing.sm}"
   table-row-selected:
-    backgroundColor: "{colors.selected}"
+    backgroundColor: "{colors.primary-bg}"
     textColor: "{colors.text}"
     typography: "{typography.body}"
     padding: "{spacing.xs} {spacing.sm}"
   modal-default:
-    backgroundColor: "{colors.surface}"
+    backgroundColor: "{colors.surface-elevated}"
     textColor: "{colors.text}"
     typography: "{typography.body}"
     rounded: "{rounded.lg}"
     padding: "{spacing.md}"
   button-primary-active:
     backgroundColor: "{colors.primary-active}"
-    textColor: "#ffffff"
+    textColor: "{colors.on-primary}"
     typography: "{typography.button}"
     rounded: "{rounded.md}"
-    padding: "{spacing.xs} {spacing.md}"
-    height: 32px
+    padding: "{spacing.xxs} {spacing.sm}"
+    height: 28px
   page-shell:
     backgroundColor: "{colors.canvas-layout}"
     textColor: "{colors.text}"
     typography: "{typography.body}"
     padding: "{spacing.md}"
   alert-success:
-    backgroundColor: "{colors.success}"
-    textColor: "#000000"
+    backgroundColor: "{colors.success-bg}"
+    textColor: "{colors.text}"
     typography: "{typography.body}"
     rounded: "{rounded.sm}"
     padding: "{spacing.xs} {spacing.sm}"
   alert-warning:
-    backgroundColor: "{colors.warning}"
-    textColor: "#000000"
+    backgroundColor: "{colors.warning-bg}"
+    textColor: "{colors.text}"
     typography: "{typography.body}"
     rounded: "{rounded.sm}"
     padding: "{spacing.xs} {spacing.sm}"
   alert-error:
-    backgroundColor: "{colors.error}"
-    textColor: "#000000"
+    backgroundColor: "{colors.error-bg}"
+    textColor: "{colors.text}"
+    typography: "{typography.body}"
+    rounded: "{rounded.sm}"
+    padding: "{spacing.xs} {spacing.sm}"
+  alert-info:
+    backgroundColor: "{colors.info-bg}"
+    textColor: "{colors.text}"
     typography: "{typography.body}"
     rounded: "{rounded.sm}"
     padding: "{spacing.xs} {spacing.sm}"
+  badge-processing-solid:
+    backgroundColor: "{colors.primary}"
+    textColor: "#000000"
+    typography: "{typography.caption}"
+    rounded: "{rounded.sm}"
+    padding: "{spacing.xxs} {spacing.xs}"
+  badge-success-solid:
+    backgroundColor: "{colors.success}"
+    textColor: "#000000"
+    typography: "{typography.caption}"
+    rounded: "{rounded.sm}"
+    padding: "{spacing.xxs} {spacing.xs}"
+  badge-warning-solid:
+    backgroundColor: "{colors.warning}"
+    textColor: "#000000"
+    typography: "{typography.caption}"
+    rounded: "{rounded.sm}"
+    padding: "{spacing.xxs} {spacing.xs}"
+  badge-error-solid:
+    backgroundColor: "{colors.error}"
+    textColor: "#000000"
+    typography: "{typography.caption}"
+    rounded: "{rounded.sm}"
+    padding: "{spacing.xxs} {spacing.xs}"
   secondary-copy:
     textColor: "{colors.text-secondary}"
     typography: "{typography.caption}"
+  card-compact:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.text}"
+    typography: "{typography.body}"
+    rounded: "{rounded.lg}"
+    padding: "{spacing.md}"
 
 ---
 
-# Overview
+## Overview
 
 YSS is an enterprise UI system for dense, scannable work surfaces: tables, forms, filters, workflows and operational feedback. This file is the normative source for visual tokens and component visual variants. Product behavior remains in Spec, interaction specifications and state matrices.
 
-The visual baseline is Ant Design semantic tokens mapped to YSS UI. Production applications use Vue 3 + YSS UI / Ant Design Vue 4.x; high-fidelity prototypes use React + Ant Design 6.x. Both tracks consume the same semantic intent.
+The visual baseline is Ant Design v6 semantic tokens mapped to YSS UI. Production applications use Vue 3 + YSS UI / Ant Design Vue 4.x; high-fidelity React prototypes use Ant Design 6.x, while experimental Vue prototypes may use the draft Antdv Next provider against an exact-version fact pack. These tracks share visual intent, not framework APIs.
 
-# Colors
+## Colors
 
 Use semantic roles (`primary`, `text`, `surface`, `border`, `success`, `warning`, `error`) instead of literal values in product pages. Keep a single primary action per decision area. State colors must be paired with readable text or an icon and must meet WCAG 2.2 AA.
 
-# Typography
+## Typography
 
 Use the system font stack, 14px body text and 400/600 weights. Use `caption` only for supporting information; do not encode business status through weight alone.
 
-# Layout
+## Layout
 
-Use a 4px spacing grid and the spacing tokens above. Default controls are 32px high. Page, container and overlay surfaces form the base three-layer model. On narrow screens, toolbars and filters reflow or collapse; table overflow is restricted to the table container.
+Use a 4px spacing grid and the spacing tokens above. Keep the Ant Design seed `controlHeight` at 32px, then apply the compact algorithm once; the default prototype and dense-work-surface result is 28px. Never seed 28px and apply compact again. Page, container and overlay surfaces form the base three-layer model. On narrow screens, toolbars and filters reflow or collapse; table overflow is restricted to the table container.
 
-# Elevation & Depth
+## Elevation & Depth
 
 Prefer surface and border changes over decorative shadows. Use the component library elevation tokens when available. Shadow values remain an implementation detail until the upstream DESIGN.md schema provides a stable structured elevation contract.
 
-# Shapes
+## Shapes
 
 Controls use `rounded.md` (6px); cards and overlays use `rounded.lg` (8px); compact tags may use `rounded.sm` or `rounded.pill`. A container radius must not be smaller than the radius of its child controls.
 
-# Components
+## Components
 
-The component keys above describe visual variants, not business states. Required implementation states include hover, focus, active, disabled, loading, error, empty, readonly, no-permission, conflict and success. Define those behavior and acceptance details in the lifecycle state-matrix and prototype evidence assets.
+The component keys above describe compact visual variants, not business states. Controls use a 28px computed height, 14px body type, pale semantic feedback surfaces and visible focus rings. Required implementation states include hover, focus, active, disabled, loading, error, empty, readonly, no-permission, conflict and success. Define those behavior and acceptance details in the lifecycle state-matrix and prototype evidence assets.
 
-# Do’s and Don’ts
+## Do's and Don'ts
 
 - Do consume tokens through ConfigProvider, CSS variables or the target component library theme.
+- Do compose `compactAlgorithm` with `darkAlgorithm` for dark compact work surfaces.
 - Do verify desktop (`1440x900`), mobile (`390x844`) and impacted intermediate viewports.
 - Do provide visible feedback for save, submit, publish, export and retry actions.
 - Don’t use marketing hero layouts, large gradients or decorative cards in operational pages.
 - Don’t hard-code colors, arbitrary spacing or duplicate controls that already exist in YSS UI.
+- Don’t target component-library internal DOM or generated class names; v6 internal markup is not a stable contract.
 - Don’t use a Tag as the only representation of an error, permission or approval state.

package/template/README.md

@@ -130,3 +130,7 @@ scripts/verify-template-fast
 | [docs/templates/implementation-repo-registry-template.md](./docs/templates/implementation-repo-registry-template.md) | 外部实现仓库登记 |
 | [docs/templates/cross-repo-slice-template.md](./docs/templates/cross-repo-slice-template.md) | 跨仓库垂直切片记录 |
 | [docs/architecture/templates/architecture-deepening-template.md](./docs/architecture/templates/architecture-deepening-template.md) | 架构 deepening 候选与 seam 设计 |
+
+## 按职责使用与升级
+
+[五类项目用户手册](docs/user-guide/用户手册.md)提供选型、初始化及升级；[设备借用贯穿案例](docs/user-guide/设备借用贯穿案例.md)演示战略、后端、前端与统一验收。[全部手册](docs/user-guide/用户手册索引.md)区分日常使用与维护入口。GitHub 当前能力与 npm 发布快照分别核对。

package/template/__yss_dotfile__.gitignore

@@ -41,3 +41,4 @@ output
 docs/process/presentations/
 docs/process/yss-product-lifecycle-team-guide.md
 docs/graphify-out
+docs/.scratch/

package/template/docs/agents/backend-architecture-profiles.md

@@ -0,0 +1,25 @@
+# 后端架构 Profile 执行约定
+
+Profile、模块闭包、生成器、成熟度和 Recipe 的权威映射见 `yss-skill-registry.yaml`。本文件只定义分层执行边界，不从目录名推断架构。
+
+执行前比较工程基线、仓库登记、Manifest 与当前合同的 `architecture_identity`。缺失、digest 漂移、Profile 不匹配或越界写路径均停止；既有工程不能自动重选架构。新 Profile 的真实编译及首切片验证未通过前保持 `draft`，不能设置 `ready-for-agent`。
+
+## MVC 分层
+
+- `layered-mvc-service` 的用例层为 `service`；`mvc-data-analysis-v1` 的用例层为 `core`。后者是薄应用层，不是合并 Domain 的容器。MVC 不加载 `yss-domain`，不生成 DDD Gateway。
+- 用例层拥有事务、业务规则、幂等和内部 Command / Query / Result；可依赖 Spring Context / `spring-tx`，不依赖 Spring MVC、HTTP client DTO 或数据库驱动。Controller 不直连 Repository。
+- Repository 拥有 PO、MyBatis-Plus Repository / XML 及持久化转换；不得反向依赖 service/core/server/client。数据库操作的因果异常应保留，禁止把内部错误原文输出给客户端。
+- Adapter 拥有外部系统适配，Feign client 只承载远程调用契约。不得把 Repository 当作对外集成层。
+- 私有 HTTP DTO 在 server；启用 published-client 时公开 DTO 可在 client；数据分析 Profile 的公开 DTO 固定在 client。client 不依赖 service/core/repository/server。server 用 MapStruct 在 wire DTO 与内部模型之间转换；core 不依赖 client。
+- Bean Validation 在 server/client 的输入边界；业务校验及稳定错误语义在 service/core；HTTP 状态、包装和脱敏在 server。事务回滚、校验失败、已知/未知异常和序列化必须有行为测试。
+
+## 数据库与 Java 基线
+
+- 新脚手架统一 `verification_database=h2`、`production_database=not-bound`。仅测试和显式 `scaffold-local` 使用 H2；普通配置不设置数据库或默认激活 Profile。不另加生产驱动、第三方数据源或 Mock 服务。
+- 生产数据库、DDL、索引和方言在后续批准的存储工作单元接入；H2 测试不能证明生产方言兼容。脚手架不包含业务 SQL、schema/data 占位或业务 API。
+- 三种新 Profile 使用 `spring-boot-2.7-jdk8` / `javax`。组件 Skill 消费工程基线，不擅自升级 Java、Boot、处理器版本或替换依赖。MapStruct + Lombok 必须验证 binding 与生成代码编译。
+- 对 SQL 注入、敏感信息、权限和事务的规则不因 H2 或模板而豁免。MySQL 专属语法规则仅适用于批准的 MySQL 存储工作单元；框架命名/返回包装等差异须记录明确的 YSS 基线例外。
+
+## 验证含义
+
+结构测试只证明分流/生成约束。三种 Profile 各自需要临时 `CompatibilityProbe` 的真实 Maven validate/test/package 与首切片端到端证据才能声明受支持。Probe 不进入分发骨架。用户工程空骨架验证成功最多为 `empty-scaffold-verified`，不能替代自身批准的首切片验证。

package/template/docs/agents/digital-human-roles.md

@@ -31,14 +31,14 @@
 | `work-unit.code-review` | 实现者 | `role.test-engineer`（必须不同实例） |
 | `gate.spec-baseline-approved` | `role.requirements-manager` | `role.product-manager` |
 | `gate.openapi-frozen` | `role.backend-engineer` | `role.product-manager`、`role.test-engineer` |
-| `gate.user-confirmation` | — | `role.product-manager`；生物人可否决 |
+| `gate.user-confirmation` | 产品数字人提供建议 | 提问者或其明确指定的生物人负责人 |
 | `gate.release-ready` | — | 生物人（`role.biological-human`） |
 
 未列入表的门禁（含 `gate.design-reviewed`、`gate.architecture-reviewed`）走 `default_if_unlisted: biological-human`。
 
-会签写入 `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`，形状见 `docs/templates/approval-record-template.yaml`。恢复前运行 `scripts/verify-approval-record`。错误会签只能得到 `blocked`，不能把门禁标成 `approved`。Checkpoint 里会签桶门禁为 `approved` 时必须有可读 `approval_ref`。
+会签写入 `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`，形状见 `docs/templates/approval-record-template.yaml`。恢复前运行 `scripts/verify-approval-record --require-approved`。错误会签只能得到 `blocked`，不能把门禁标成 `approved`。Checkpoint 里会签桶门禁为 `approved` 时必须有可读 `approval_ref`。
 
-`paused-human-gate` 表示等待上述指定会签人，不是「必须是生物人」。
+`paused-human-gate` 表示等待指定会签人；`user_decision_policy` 命中的关键决定同时强制真实用户回复，数字人审查不能代答。请求展示、原始回复证据、复用和恢复规则见 [用户决定协议](../../.agents/skills/yss-product-lifecycle/references/user-decisions.md)。
 
 主控默认兼任项目经理，直到 `dual_hat_split_when`（`cross-repo-load` 或 `responsibility-conflict`）要求分体。