create-yss-spec 2.2.1 → 2.2.3

package/template/.trae/skills/yss-router/references/slice-implementation-contract.md

@@ -9,6 +9,7 @@ slice_contract:
   contract_version: 1
   slice_id:
   status: draft
+  suggested_owner_role_id: # role.frontend-engineer | role.backend-engineer | role.test-engineer；Router 只建议，编排器派活并批准
   lifecycle_refs:
     spec:
     ticket:

package/template/AGENTS.md

@@ -10,7 +10,7 @@
 - `repository_mode: project-instance`：按产品研发生命周期分诊任务。
 - 文件缺失、schema 版本不支持或模式值非法时，停止路由并执行迁移检查；不根据目录、Git 远程或占位符猜测身份。
 
-仓库身份契约见 `docs/adr/0002-yss-project-repository-mode.md`。
+仓库身份契约由根目录 `yss-project.yaml` 和本文件共同声明。
 
 ## 2. 单一事实来源
 
@@ -23,6 +23,7 @@
 | 模板维护强度触发与最低等级 | `docs/process/maintenance-intensity.yaml` |
 | 技能清单、来源、版本、哈希和投影目标      | `skills-lock.json`                          |
 | 技能分层、别名、默认可发现性和运行时入口 | `docs/agents/yss-skill-registry.yaml`（当前 `status: shadow`，不作为 Router / 生命周期运行时入口） |
+| 数字人角色、阶段协作组、运行时绑定与生命周期会签 | `docs/agents/digital-human-roles.yaml`；`docs/agents/digital-human-roles.md` 为操作说明 |
 
 README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或解释上述事实，不重复定义同一规则。`CLAUDE.md` 是 Claude Code 入口指针，不是第二套 Agent 规则。
 
@@ -83,6 +84,7 @@ README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或
 | merge / rebase 冲突 | `resolving-merge-conflicts` |
 | 架构治理、难测模块或深模块设计 | `improve-codebase-architecture` / `codebase-design` |
 | 跨线程、跨仓库、上下文过长或原型结论回流 | `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` 使用已确认的公开 seam 逐切片实现。一次性生成、纯配置或流程文档不适用代码 TDD 时，必须记录例外理由和可执行验证方式。
@@ -95,28 +97,17 @@ README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或
 
 ## 10. 独立审查、验证和追踪
 
-- 实现者不能承担命中的独立审查。模板维护按 L1 / L2 / L3 分别使用 self-check / 人工 checkpoint、聚焦独立审查、正式独立审查；模板发布、代码切片和高风险变更仍必须由其他 Agent 或人工独立审查。
+- 实现者不能承担命中的独立审查（含数字人）。模板维护按 L1 / L2 / L3 分别使用 self-check / 人工 checkpoint、聚焦独立审查、正式独立审查；模板发布、代码切片和高风险变更仍必须由其他 Agent 或独立审查者完成。
 - 任何“完成 / 可合并 / 可发布”结论必须基于 fresh verification，不接受“之前跑过”或实现者自述。
-- 在人工暂停、handoff、进入实现、合并或发布边界集中同步范围、验证证据、风险、人工审查点、Ticket 状态和下一步；阻塞、责任人变化或资产单独批准时立即同步。
+- 会签门禁按 `docs/agents/digital-human-roles.yaml` 的 `gate_policy` 关闭，会签文件经 `scripts/verify-approval-record` 核验；`gate.release-ready`、对外商务承诺和运行时外部副作用仍须生物人。
+- 在会签暂停、handoff、进入实现、合并或发布边界集中同步范围、验证证据、风险、会签点、Ticket 状态和下一步；阻塞、责任人变化或资产单独批准时立即同步。
 - Git checkpoint 只包含本轮明确范围；获得用户授权后才提交或推送。
 - 发布后或阶段性完成后做复盘判断；出现架构返工、验证返工、IMPORTANT / CRITICAL review finding 或人工确认延期时，落简体中文复盘并修订权威资产。
 
 ## 11. Subagent 协同
 
-使用 subagent 前按 `docs/process/subagent-collaboration.md` 定义任务包和不重叠的写入范围。实现者不担任独立审查者；仓库身份、需求 / 契约冻结、Ticket 最终状态、Git checkpoint 和完成结论仍由主控 Agent 或人工决定。
+使用 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`。写隔离靠任务包；共享工作区不是默认沙箱。
 
 ## 12. 测试质量基线
 
 模板推荐值为 Domain / Application `>= 90%`、API `>= 80%`、前端组件 `>= 75%`、已明确的关键流程 `100% E2E`。只有项目实例在测试策略中明确采纳或覆盖后才构成 CI 门禁；未定义关键流程清单时，不声称其 E2E 覆盖率达到 100%。
-
-## Cursor Cloud specific instructions
-
-本仓库是 `template-source` Harness / 研发管理仓库，没有前端 / 后端运行时应用；可运行、可测试的表面只有 Node 工具链与治理校验脚本。
-
-- 依赖与工具链：Node `>=22 <27`（`.nvmrc` 固定 22）；`pnpm` 通过 `packageManager` 字段由 corepack 自动切换到 `10.15.0`，无需手工切换。Node 依赖只装在 `.template-source/tooling/node`，仓库根没有 `package.json`。本仓 wiki-root 为 `.template-source/wiki`。
-- 测试：`pnpm --dir .template-source/tooling/node test`（`node --test`，共 16 个用例）。
-- 构建 / lint：`pnpm --dir .template-source/tooling/node build:vendor` 与 `check:vendor` 维护 `scripts/vendor/*.mjs`；顶层 lint 是 `verify-template` 内对所有脚本执行的 `node --check`。
-- 完整发布门禁（相当于"运行应用"）：`scripts/verify-template`，成功输出 `模板发布校验通过`。它串联证据索引、`pnpm test`、`check:vendor` 和全部 `scripts/verify-*` 场景校验。
-- 非显然的坑：`scripts/verify-lifecycle-registry`（及其对应测试 `Node lifecycle registry verifier ...`）会 shell out 到 `python3` 并 `import jsonschema` 做 JSON Schema 校验。缺少该 Python 模块时测试会以 `ModuleNotFoundError: No module named 'jsonschema'` 失败，而不是代码问题；update script 已负责 `pip3 install jsonschema`。
-- `pnpm install` 输出的 `Ignored build scripts: esbuild` 警告可忽略：esbuild 0.28.2 在本平台自带二进制，`build:vendor` / `check:vendor` 无需 `pnpm approve-builds`。
-- 常用只读入口：`scripts/repository-mode`（返回仓库身份）、`scripts/generate-lifecycle-artifacts`（从 `docs/process/lifecycle-registry.yaml` 派生产物，输出应无 diff）、`scripts/export-yss-skills --output <dir>`（导出公开技能）。

package/template/CONTEXT.md

@@ -12,7 +12,19 @@
 
 | 术语 | 含义 | 英文标识 | 避免 / 备注 |
 |---|---|---|---|
-| Agent | 执行特定工作流步骤的 AI 协作者。 | — | 不要与人工审查者混用。 |
+| Agent | 执行特定工作流步骤的 AI 协作者。 | — | 不要与生物人审查者、数字人角色或 Ticket 状态混用。运行时实例（Cursor Agent、Claude Code、Grok Bot 等）是 Agent 的承载，不是角色本身。 |
+| 运行时绑定 | 把数字人角色落到某个 Agent 平台的适配声明，权威清单在数字人角色注册表的 `runtimes`。 | — | 不要为每个平台复制一套职称职责。 |
+| Grok Bot | Grok 平台上的持久数字队友实例；对应 `runtime.grok`。 | — | 不是数字人角色、技能或门禁。 |
+| 数字人角色 | 叠加在生命周期编排器上的职称配置；一个运行时实例绑定一种。v1 清单以 `docs/agents/digital-human-roles.yaml` 为准。 | — | 不要称为 Ticket「标准角色」、职能 Agent 或某个平台的产品名。 |
+| 主控数字人 | 运行 `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`。 |
+| 需求经理 | 主责 Discovery 语言、用户/MVP/非目标、Spec 正文与测试 seam 的数字人角色。 | — | 不拥有原型视觉定稿，不 Freeze API，不写实现。 |
+| 产品经理 | 主责优先级、产品设计影响、原型确认建议和范围裁剪的数字人角色。 | — | 不写生产代码，不单独 Freeze API。 |
+| 商务 | 主责机会调研商业约束、交付承诺和发布窗口商务非目标的数字人角色。 | — | 不参与 Spec 定稿、契约、代码或 Ticket 状态推进。 |
 | Agent 入口规则 | Agent 启动任务时必须先遵守的全局路由、硬门禁和禁止事项。 | — | 不作为 YSS 后端、前端或其他专项编码规范的完整手册。 |
 | 标准文档语言 | 面向业务、产品、架构、实施、审查、发布和复盘的持久化文档所使用的默认语言。 | — | 统一使用简体中文；英文专有名词、代码标识、API 路径、schema、文件名和协议 metadata 保持原样。 |
 | Matt Engineering Skills | 来自 `mattpocock/skills` 的轻量工程流程技能集合。 | — | 用于澄清、Spec、Ticket、实现、TDD、诊断、审查和架构治理，不替代 YSS 专项规范。 |
@@ -25,7 +37,7 @@
 | Ticket | 在追踪平台上承载功能生命周期或可实现工作单元的通用追踪对象。 | — | GitHub Issues / GitLab Issues 是具体平台对象名称；领域资产统一称为 Ticket。 |
 | 功能父 Ticket | 汇总一个功能从 Spec 到契约冻结的阶段状态、资产链接、审查结论和阻塞项的 Ticket。 | — | 不作为 Agent 直接实现的垂直切片。 |
 | 垂直切片 Ticket | 契约冻结后生成的可独立验证实现单元，记录范围、阻塞关系、验收标准和验证证据。 | — | 只有通过必要门禁并具备直接实现条件时才能标记 `ready-for-agent`。 |
-| `ready-for-human` | 表示 Spec、设计、契约草案或其他资产仍需人工审查或确认的流程状态。 | — | 此状态不表示可以直接进入实现。 |
+| `ready-for-human` | 表示 Spec、设计、契约草案或其他资产仍需会签（指定数字人或生物人）。 | — | 此状态不表示可以直接进入实现；也不等于某个数字人角色。 |
 | `ready-for-agent` | 表示垂直切片已通过必要门禁并具备直接实现条件的流程状态。 | — | 不得用于 Spec 初稿、原型、OpenAPI Draft 或其他未冻结资产。 |
 | OpenAPI Draft | review-only 的 OpenAPI 3.1 契约草案。 | — | Freeze 前不得作为前后端稳定实现契约。 |
 | OpenAPI Freeze | 已通过评审、可作为前后端实现和契约测试输入的 OpenAPI 3.1 契约。 | — | Freeze 后变更必须回到 API 影响分析和设计审查。 |

package/template/docs/adr/README.md

@@ -0,0 +1,7 @@
+# 产品架构决策
+
+本目录只记录当前项目自身的架构决策，不承载 `yss-spec-project-template` 模板源仓库的治理决策。
+
+创建 ADR 时使用 [`docs/templates/adr-template.md`](../templates/adr-template.md)，并为每条决策补充状态、背景、取舍、后果和相关资产。
+
+模板源仓库的 ADR 保存在 `.template-source/adr/`，不会随 `create-yss-spec` 进入 `project-instance`。

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

@@ -0,0 +1,83 @@
+# 数字人角色
+
+结构化事实源是 `docs/agents/digital-human-roles.yaml`。角色、技能、协作组和会签级别与运行时无关。Claude Code、Cursor、Codex、Hermes、Grok Bot 等只通过 YAML `runtimes` 绑定。冲突时以 YAML 为准。
+
+## 何时读本文
+
+按职称派活、写会签、把数字人角色和 Ticket 状态 / 职能 Agent / 执行态弄混，或要在某个 Agent 平台上实例化这些角色时。
+
+## 四条正交轴
+
+| 轴 | 是什么 | 不是什么 |
+|---|---|---|
+| 数字人角色 | 职称配置（需求经理、前端工程师…） | Ticket 五态、某个平台的 Bot |
+| 主控数字人 | 生命周期编排器的运行时实例 | 第八个业务职称 |
+| 职能工作单元 | Discovery / Spec / Code / Review | 职称 |
+| 执行态 | Explorer / Drafter / Worker / Reviewer / Verifier | 数字人角色 |
+| 运行时绑定 | 如何在 Cursor / Claude / Grok 等落地 | 角色职责本身 |
+
+一次任务包同时写明数字人角色、执行态、当前 `runtime_id`，以及从角色表复制的 `core_skills` / `forbidden_skills`。可用 `taskPackageDefaults(roleId)`（`scripts/lib/digital-human-roles.mjs`）读取，禁止手写第二套技能包。
+
+## 会签人
+
+`gate_policy.digital_human_review` 与 `dual_digital_human` 是「门禁 × 起草者 × 会签人」规则，不是门禁名单。主控按 `countersigners` 派会签任务。
+
+| 门禁 / 工作单元 | 起草 | 会签 |
+|---|---|---|
+| `gate.prototype-reviewed` | `role.product-manager` | `role.frontend-engineer` |
+| `gate.openapi-draft-reviewed` | `role.backend-engineer` | `role.frontend-engineer` |
+| `gate.engineering-baseline-accepted` | （实现者） | `role.test-engineer` |
+| `gate.frontend-implementation-verified` | `role.frontend-engineer` | `role.test-engineer` |
+| `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.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`。
+
+`paused-human-gate` 表示等待上述指定会签人，不是「必须是生物人」。
+
+主控默认兼任项目经理，直到 `dual_hat_split_when`（`cross-repo-load` 或 `responsibility-conflict`）要求分体。
+
+## 跨平台协同（默认）
+
+1. 人默认只跟主控说话。
+2. 主控按阶段 1:1 指定一个 owner，并给任务包（输入、写范围、禁止 skill、验收、验证命令）。
+3. 需要可见会签时使用 YAML `stage_groups` 的**逻辑协作组**。这不是某个产品的群聊人数限制。
+4. 权威结论写回 git。运行时记忆只记该数字人的稳定偏好。
+5. 写隔离一律靠任务包。某运行时若共享磁盘或会话，适配器必须声明 `shared_workspace_is_not_security_boundary: true`，不得把实例当成沙箱。
+6. `project-instance` 复制角色实例并绑定仓库路径。禁止按功能再拆实例。
+7. 技能权威仍是 `.agents/skills`。已有投影根走 `runtime.skill-projection`，不要为职称再维护一份 skill。任务包的技能列表必须从角色表复制。
+
+## 运行时绑定
+
+| ID | 覆盖 | 落地方式 |
+|---|---|---|
+| `runtime.generic` | 任何能加载 `core_skills` 并接受任务包的 Agent | 通用会话 / 人设 / system prompt |
+| `runtime.skill-projection` | `yss-skill-registry.yaml` 的 `agent_runtime_roots`（claude、codex、cursor、hermes、pi、qoder、trae） | 投影技能 + subagent 任务包 |
+| `runtime.grok` | Grok Bot | 持久 Bot、群聊或 1:1 交接；群超过 6 人改 1:1，不改逻辑协作组 |
+
+新增平台：先加 `runtimes` 条目，再写适配说明。不要把平台限制写进 `roles`。
+
+Grok 专用操作见 `docs/templates/grok-bot-profile-template.md`。通用实例化见 `docs/templates/digital-human-runtime-profile-template.md`。
+
+## 两套批准
+
+| 名称 | 关闭什么 | 谁点 |
+|---|---|---|
+| 运行时副作用审批 | 发消息、改生产、付款、删数据等工具动作 | 生物人（各平台自己的 Allow / 确认框） |
+| 生命周期会签 | `gate.*` 与独立 code review | 见 YAML `gate_policy` |
+
+会签写入 `docs/templates/approval-record-template.yaml`，带 `runtime_id`、`principal_ref` 与实例引用。起草者不得出现在会签人里。`gate.release-ready`、对外商务合同、运行时外部副作用，以及未列入会签表的 `gate.design-reviewed` / `gate.architecture-reviewed` 仍须生物人。
+
+## 实例化
+
+- 模板仓：`publish-singleton-profiles`。账户级只发布一套职称 profile，不按功能再拆。
+- `project-instance`：`duplicate-and-bind-repo-path`。复制 YAML 的 `title` / `description` / `core_skills`，写入本仓库路径，选择 `runtime_id`。步骤见 `docs/templates/digital-human-runtime-profile-template.md`。外部 `create-yss-spec` 尚未接管此步骤。
+
+## 任务包最低字段
+
+数字人角色 ID、`runtime_id`、执行态、从角色表复制的 `core_skills` / `forbidden_skills`、输入资产、允许写路径、禁止事项、验收、验证命令、汇合方式。

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

@@ -0,0 +1,253 @@
+schema_version: 1
+registry_id: yss.digital-human-roles
+status: active
+description: >-
+  数字人角色、主控、阶段协作组、技能启用/禁止与生命周期会签的单一事实源。
+  角色配置与运行时无关；Claude / Cursor / Codex / Grok 等只通过 runtimes 绑定。
+  Ticket 五态不是数字人角色。
+canonical_path: docs/agents/digital-human-roles.yaml
+runtime_policy:
+  overlay_on_lifecycle: true
+  consumed_by_lifecycle: true
+  git_is_ssot: true
+  default_invocation: orchestrator
+  dispatch: orchestrator-one-to-one
+  per_feature_instances: forbidden
+  project_instance_instantiation: duplicate-and-bind-repo-path
+  template_instantiation: publish-singleton-profiles
+  biological_veto: true
+  implementer_must_differ: true
+  write_isolation: task-package-policy
+  dual_hat_split_when: [cross-repo-load, responsibility-conflict]
+
+runtimes:
+  - id: runtime.generic
+    kind: generic
+    instance_kind: agent-session
+    skill_root: null
+    covers_skill_registry_roots: false
+    collaboration: task-package-and-handoff
+    max_collaboration_group_size: null
+    overflow: not-applicable
+    shared_workspace_is_not_security_boundary: false
+    side_effect_approval: biological-human
+    notes: 任何能加载 core_skills 并接受任务包的 Agent 会话。
+  - id: runtime.skill-projection
+    kind: projected-agent-root
+    instance_kind: agent-session-or-subagent
+    skill_root: from-skill-registry
+    covers_skill_registry_roots: true
+    collaboration: subagent-task-package
+    max_collaboration_group_size: null
+    overflow: not-applicable
+    shared_workspace_is_not_security_boundary: false
+    side_effect_approval: biological-human
+    notes: >-
+      覆盖 docs/agents/yss-skill-registry.yaml 的 agent_runtime_roots
+      （claude / codex / cursor / hermes / pi / qoder / trae）。
+      技能仍从 .agents/skills 投影，不按职称再维护一份。
+  - id: runtime.grok
+    kind: grok-bot
+    instance_kind: durable-bot
+    skill_root: null
+    covers_skill_registry_roots: false
+    collaboration: group-chat-or-async-dm
+    max_collaboration_group_size: 6
+    min_collaboration_group_size: 2
+    overflow: one-to-one-handoff
+    shared_workspace_is_not_security_boundary: true
+    side_effect_approval: biological-human
+    notes: >-
+      Grok Bot 适配。群聊 2–6 人；超出则改 1:1 交接，不改逻辑阶段协作组。
+      全部 Bot 共享云计算机，写范围只靠任务包。不新增 agent_runtime_roots.grok。
+
+orchestrator:
+  id: role.lifecycle-orchestrator
+  name: 主控数字人
+  kind: orchestrator
+  title: YSS 生命周期主控
+  default_dual_hat: [role.project-manager]
+  stages: [stage.entry-triage, stage.discovery, stage.spec-architecture, stage.product-design, stage.system-data-engineering, stage.ticket-formalization, stage.vertical-slice-implementation, stage.verification-release-retrospective]
+  core_skills: [yss-product-lifecycle, yss-router]
+  forbidden_skills: [yss-domain, yss-ui, yss-page-module-development, yss-web-controller, yss-repository, implement]
+  description: >-
+    Own YSS lifecycle routing. Read yss-project.yaml and CONTEXT.md first.
+    Select the next unblocked work unit, compile a task package, and assign
+    one owner per stage. Do not implement business code. Do not approve Slice
+    contracts into ready-for-agent without the full formula. Do not announce
+    releasable. Default dual-hat: project manager until a separate instance
+    is required. Authoritative artifacts live in git.
+
+roles:
+  - id: role.requirements-manager
+    name: 需求经理
+    kind: digital-human
+    title: YSS 需求经理
+    stages: [stage.discovery, stage.spec-architecture]
+    draft_artifact_ids: [artifact.discovery-record, artifact.spec]
+    core_skills: [grilling, domain-modeling, research, competitive-intelligence, grill-with-docs]
+    forbidden_skills: [yss-ui, yss-domain, yss-web-controller, yss-repository, yss-ddd-scaffold-generator, yss-frontend-scaffold-generator, implement, tdd]
+    description: >-
+      Own Discovery language, users, MVP, non-goals, success criteria, test
+      seams, and Spec prose. Propose CONTEXT.md glossary entries. Do not freeze
+      visual prototypes, OpenAPI, or code. Do not guess unconfirmed business
+      rules. Hand off to the orchestrator when the frontier is empty.
+
+  - id: role.product-manager
+    name: 产品经理
+    kind: digital-human
+    title: YSS 产品经理
+    stages: [stage.discovery, stage.spec-architecture, stage.product-design, stage.verification-release-retrospective]
+    draft_artifact_ids: [artifact.product-overview, artifact.functional-architecture, artifact.interaction-spec, artifact.state-matrix, artifact.prototype-confirmation]
+    core_skills: [yss-design-system, yss-prototype-stage, prototype-review, yss-antd-design]
+    forbidden_skills: [yss-ui, yss-domain, yss-repository, yss-web-controller, yss-ddd-scaffold-generator, implement, tdd]
+    description: >-
+      Own priority, product-design impact, interaction, state matrix, and
+      prototype confirmation recommendation. May reject Spec scope. Do not write
+      production code or freeze OpenAPI alone. Frontend implementation uses the
+      frontend-engineer role and yss-ui, not yss-antd-design.
+
+  - id: role.business
+    name: 商务
+    kind: digital-human
+    title: YSS 商务
+    stages: [stage.discovery, stage.verification-release-retrospective]
+    draft_artifact_ids: [artifact.discovery-record]
+    core_skills: [competitive-intelligence, research]
+    forbidden_skills: [yss-ui, yss-domain, yss-web-controller, yss-openapi-governance, to-spec, to-tickets, implement, tdd, yss-router]
+    description: >-
+      Own commercial constraints, delivery promises, and business non-goals in
+      Discovery and release windows. Do not finalize Spec, API, tickets, or
+      code. External quotes and contracts stay behind runtime side-effect
+      approval by a biological human.
+
+  - id: role.project-manager
+    name: 项目经理
+    kind: digital-human
+    title: YSS 项目经理
+    stages: [stage.entry-triage, stage.discovery, stage.spec-architecture, stage.product-design, stage.system-data-engineering, stage.ticket-formalization, stage.vertical-slice-implementation, stage.verification-release-retrospective]
+    draft_artifact_ids: [artifact.parent-ticket, artifact.vertical-slice-ticket]
+    core_skills: [yss-product-lifecycle, handoff, implementation-repo-onboarding, cross-repo-implementation-routing]
+    forbidden_skills: [yss-domain, yss-ui, implement, tdd, yss-web-controller]
+    description: >-
+      Own parent Ticket hygiene, checkpoints, handoff, risk, and implementation
+      repo registry. Do not set ready-for-agent; the orchestrator recomputes
+      that formula. Do not approve Spec or OpenAPI Freeze. Do not write business
+      code or serve as independent Reviewer. Default dual-hat on the
+      orchestrator instance until dual_hat_split_when
+      (cross-repo-load or responsibility-conflict) requires a separate instance.
+
+  - id: role.frontend-engineer
+    name: 前端工程师
+    kind: digital-human
+    title: YSS 前端工程师
+    stages: [stage.product-design, stage.system-data-engineering, stage.ticket-formalization, stage.vertical-slice-implementation, stage.verification-release-retrospective]
+    draft_artifact_ids: [artifact.frontend-implementation-plan]
+    core_skills: [yss-ui, yss-page-module-development, yss-components, yss-formily, formily-foundation, formily-linkage-effects, formily-mode-slot-detail, formily-step-flow, ytable-usage, ytree-usage, yedit-table-usage, yss-api-integration, yss-hook, theme-token-usage, page-skeleton, page-list-module, page-form-module, component-selection-imports, vue3-best-practices, tdd]
+    forbidden_skills: [yss-domain, yss-application, yss-repository, yss-mybatis, yss-web-controller, yss-ddd-scaffold-generator, java-backend-commit]
+    description: >-
+      Own Vue page modules, frontend tests, and frontend_implementation_plan.
+      Review OpenAPI Draft for client fit and prototype feasibility. Write only
+      contract-allowed frontend paths. Verify with pnpm. Do not freeze API, own
+      backend domain, or countersign your own merge.
+
+  - id: role.backend-engineer
+    name: 后端工程师
+    kind: digital-human
+    title: YSS 后端工程师
+    stages: [stage.system-data-engineering, stage.ticket-formalization, stage.vertical-slice-implementation, stage.verification-release-retrospective]
+    draft_artifact_ids: [artifact.openapi-draft, artifact.data-architecture]
+    core_skills: [yss-router, yss-domain, yss-application, yss-repository, yss-mybatis, yss-web-controller, yss-dto, yss-exception, yss-validation, tdd, yss-ddd-scaffold-generator]
+    forbidden_skills: [yss-ui, yss-page-module-development, yss-formily, yss-frontend-scaffold-generator, yss-antd-design, page-list-module, page-form-module]
+    description: >-
+      Own OpenAPI Draft, data-architecture contributions, and backend tests.
+      Write only contract-allowed backend paths. Verify with ./mvnw. Do not
+      Freeze OpenAPI, treat UI copy as requirements, or countersign your own
+      implementation.
+
+  - id: role.test-engineer
+    name: 测试工程师
+    kind: digital-human
+    title: YSS 测试工程师
+    stages: [stage.spec-architecture, stage.vertical-slice-implementation, stage.verification-release-retrospective]
+    draft_artifact_ids: [artifact.frontend-implementation-verification]
+    owned_evidence_ids: [evidence.fresh-verification, evidence.frontend-implementation-verification]
+    core_skills: [tdd, diagnosing-bugs, code-review]
+    forbidden_skills: [yss-ddd-scaffold-generator, yss-frontend-scaffold-generator, implement, to-spec]
+    description: >-
+      Own test code, defect records, fresh verification, and frontend
+      implementation verification evidence. Review every implementation slice.
+      Recommend release readiness; do not close gate.release-ready. Do not
+      change product scope or write feature implementation. Must be a different
+      instance from the implementer.
+
+stage_groups:
+  - id: group.discovery
+    name: Discovery
+    stage: stage.discovery
+    members: [role.lifecycle-orchestrator, role.requirements-manager, role.product-manager, role.business]
+  - id: group.spec
+    name: Spec
+    stage: stage.spec-architecture
+    members: [role.lifecycle-orchestrator, role.requirements-manager, role.product-manager, role.test-engineer]
+  - id: group.product-design
+    name: 产品设计
+    stage: stage.product-design
+    members: [role.lifecycle-orchestrator, role.product-manager, role.requirements-manager, role.frontend-engineer]
+  - id: group.contract
+    name: 契约
+    stage: stage.system-data-engineering
+    members: [role.lifecycle-orchestrator, role.backend-engineer, role.frontend-engineer, role.test-engineer, role.product-manager]
+  - id: group.tickets
+    name: Ticket 正式化
+    stage: stage.ticket-formalization
+    members: [role.lifecycle-orchestrator, role.project-manager, role.frontend-engineer, role.backend-engineer, role.test-engineer]
+  - id: group.implementation
+    name: 实现
+    stage: stage.vertical-slice-implementation
+    members: [role.lifecycle-orchestrator, role.frontend-engineer, role.backend-engineer, role.test-engineer]
+  - id: group.release
+    name: 发布
+    stage: stage.verification-release-retrospective
+    members: [role.lifecycle-orchestrator, role.project-manager, role.test-engineer, role.product-manager, role.business]
+
+gate_policy:
+  default_if_unlisted: biological-human
+  unlisted_kept_biological:
+    - gate.design-reviewed
+    - gate.architecture-reviewed
+  evidence_only:
+    - gate.repository-identity-valid
+    - gate.prototype-verified
+  orchestrator:
+    - gate.slice-contract-approved
+    - gate.slice-ready-for-agent
+  digital_human_review:
+    - gate: gate.prototype-reviewed
+      drafter: role.product-manager
+      countersigners: [role.frontend-engineer]
+    - gate: gate.openapi-draft-reviewed
+      drafter: role.backend-engineer
+      countersigners: [role.frontend-engineer]
+    - gate: gate.engineering-baseline-accepted
+      countersigners: [role.test-engineer]
+    - gate: gate.frontend-implementation-verified
+      drafter: role.frontend-engineer
+      countersigners: [role.test-engineer]
+  digital_human_review_work_units:
+    - work_unit: work-unit.code-review
+      countersigners: [role.test-engineer]
+      implementer_must_differ: true
+  dual_digital_human:
+    - gate: gate.spec-baseline-approved
+      drafter: role.requirements-manager
+      countersigners: [role.product-manager]
+    - gate: gate.openapi-frozen
+      drafter: role.backend-engineer
+      countersigners: [role.product-manager, role.test-engineer]
+  product_digital_human_with_biological_veto:
+    - gate.user-confirmation
+  biological_human:
+    - gate.release-ready
+  runtime_side_effect_approval: biological-human
+  commercial_contract: biological-human

package/template/docs/agents/skills-maintenance.md

@@ -57,7 +57,7 @@
    scripts/verify-template
    ```
 
-   若模板维护引入或更新分发到实例的 Node 工具，先在 `.template-source/tooling/node/` 使用 `pnpm install --frozen-lockfile`，再运行 `pnpm build:vendor` 与 `pnpm check:vendor`；实例门禁不得安装依赖或重建 vendor。运行时、公开入口和跨仓回滚规则以 `.template-source/adr/0009-zero-install-node-tooling-runtime.md` 及对应契约为准。
+   模板源维护引入或更新分发到实例的 Node 工具时，维护侧依赖、构建和 vendor 校验只在模板源治理区及 CI 中执行；实例门禁不得安装依赖或重建 vendor。实例只消费已提交的 `scripts/lib/*.mjs` 与 `scripts/vendor/*.mjs`，具体维护侧命令和治理决策不属于项目实例文档。
 
 6. 需要重新加载技能的客户端在变更落地后重启或刷新项目。
 

package/template/docs/agents/triage-labels.md

@@ -1,15 +1,15 @@
 # Triage 标签
 
-本文定义 Agent 分诊时使用的五种标准角色，以及它们在当前 Ticket tracker 中对应的标签。
+本文定义 Agent 分诊时使用的五种 **Ticket 状态**，以及它们在当前 Ticket tracker 中对应的标签。不要把它们叫做数字人角色。
 
-| 标准角色 | Tracker 标签 | 含义 |
+| Ticket 状态 | Tracker 标签 | 含义 |
 | --- | --- | --- |
 | `needs-triage` | `needs-triage` | 等待维护者评估 Ticket |
 | `needs-info` | `needs-info` | 等待报告者补充信息 |
 | `ready-for-agent` | `ready-for-agent` | 必要门禁已通过、阻塞边已清除，可由 Agent 直接实现的垂直切片 Ticket |
-| `ready-for-human` | `ready-for-human` | Spec、设计、契约草案或其他资产需要人工审查、判断或特权访问 |
+| `ready-for-human` | `ready-for-human` | Spec、设计、契约草案或其他资产需要会签（指定数字人或生物人）或特权访问 |
 | `wontfix` | `wontfix` | 不会处理 |
 
-当 skill 提及某个标准角色时，使用表中对应的 Tracker 标签。
+当 skill 提及某个 Ticket 状态时，使用表中对应的 Tracker 标签。会签人由 `docs/agents/digital-human-roles.yaml` 指定，不由本表指定。
 
-Local Markdown 主 tracker 不调用远程标签：在 Ticket 文件顶部使用同名 `Status:` 值记录标准角色。Wayfinder 的 `claimed` / `resolved` 仅是临时工作状态，不属于本表五态；进入交付 Ticket 前必须转换为标准 `Status:`。
+Local Markdown 主 tracker 不调用远程标签：在 Ticket 文件顶部使用同名 `Status:` 值记录 Ticket 状态。Wayfinder 的 `claimed` / `resolved` 仅是临时工作状态，不属于本表五态；进入交付 Ticket 前必须转换为标准 `Status:`。

package/template/docs/process/implementation-repo-integration.md

@@ -30,7 +30,7 @@ apps/
 - **frontend**：依赖安装、测试、type-check 与构建优先使用 `pnpm`（例如 `pnpm test`、`pnpm type-check`、`pnpm build`）。不要默认 `npm` 或 `yarn`。
 - **backend**：校验、测试与编译优先使用项目根 `./mvnw`（例如 `./mvnw validate`、`./mvnw test`、`./mvnw package`）。不要默认裸 `mvn`。
 - Ticket、Slice Implementation Contract、CI 和 Review 证据必须写下实际执行的上述命令。既有仓库缺少 `pnpm` 或 Maven Wrapper 时，先记录受控例外、替代命令和责任人，再执行。
-- 本模板源仓库没有产品 frontend / backend 运行时；其 Node 校验仍按 `AGENTS.md` 的 Cursor Cloud 说明使用 `pnpm --dir .template-source/tooling/node`。
+- 本模板源仓库没有产品 frontend / backend 运行时；模板源维护侧的 Node 校验命令和环境约束只记录在 `.template-source/` 治理区及 CI 配置中，不属于项目实例实现命令。
 
 ## 1.3 `repository_scope: git-submodule`
 

package/template/docs/process/schemas/lifecycle-checkpoint.schema.json

@@ -37,7 +37,8 @@
           "properties": {
             "status": { "enum": ["not-evaluated", "blocked", "ready-for-human", "approved", "stale", "not-applicable"] },
             "reason": { "type": "string" },
-            "evidence_refs": { "type": "array", "items": { "type": "string" } }
+            "evidence_refs": { "type": "array", "items": { "type": "string" } },
+            "approval_ref": { "type": ["string", "null"] }
           }
         }
       },

package/template/docs/process/subagent-collaboration.md

@@ -1,11 +1,13 @@
 # Subagent 协作规则
 
-Subagent 只接收边界清晰的任务包，主控 Agent 负责仓库身份、Spec baseline、门禁、Ticket 状态、Git checkpoint 和完成结论。
+Subagent 和其它运行时实例只接收边界清晰的任务包。主控数字人负责仓库身份、门禁计算、Ticket 状态、Git checkpoint 和完成结论。数字人角色、`runtime_id` 与 Explorer / Drafter / Worker / Reviewer / Verifier 执行态正交，任务包必须同时写明。
+
+写入范围不得与其他执行者重叠；实现者不得同时担任同一切片的独立审查者，也不得会签自己起草的资产。写隔离以任务包为准。某运行时若共享磁盘或会话，不得把不同实例当成安全边界。
 
 ## 任务包
 
-每个任务包必须写明输入资产、目标、允许写路径、禁止事项、验收标准、验证命令和汇合方式。写入范围不得与其他执行者重叠；实现者不得同时担任同一切片的独立审查者。
+每个任务包必须写明数字人角色 ID、`runtime_id`、执行态、从 `docs/agents/digital-human-roles.yaml` 复制的 `core_skills` / `forbidden_skills`（可用 `taskPackageDefaults`）、输入资产、目标、允许写路径、禁止事项、验收标准、验证命令和汇合方式。禁止手写第二套技能包。
 
 ## 汇合
 
-返回结果至少包括变更文件、证据文件、实际执行的命令、结果、延期 seam、drift / violation / new impacts 和建议下一路由。主控 Agent 必须重新执行 fresh verification，并在集中 checkpoint 中保留阶段因果。
+返回结果至少包括变更文件、证据文件、实际执行的命令、结果、延期 seam、drift / violation / new impacts 和建议下一路由。主控必须重新执行 fresh verification，并在集中 checkpoint 中保留阶段因果。会签写入 `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`（形状见 `docs/templates/approval-record-template.yaml`），不能用聊天表情代替。恢复前校验 `scripts/verify-approval-record`。

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

@@ -14,6 +14,8 @@ gates:
   <stable-gate-id>:
     status: <not-evaluated|blocked|ready-for-human|approved|stale|not-applicable>
     reason: <why this status applies>
+    evidence_refs: []
+    approval_ref: <docs/.scratch/<feature>/gates/<gate-id>-approval.yaml when approved countersign gate>
 phase_boundary:
   decision: <continue|clear|handoff|subagent|compact>
   reason: <decision evidence>
@@ -41,4 +43,4 @@ blockers: []
 rollback: []
 ```
 
-阶段 checkpoint 只在人工暂停、handoff、进入实现、合并或发布边界集中回写；出现阻塞、责任人变化或资产单独批准时立即回写，并保留阶段因果。
+阶段 checkpoint 只在会签暂停、handoff、进入实现、合并或发布边界集中回写；出现阻塞、责任人变化或资产单独批准时立即回写，并保留阶段因果。`paused-human-gate` 表示等待 YAML `gate_policy` 指定的会签人（数字人或生物人），不是「必须是生物人」。会签桶内门禁标为 `approved` 时必须有可读的 `approval_ref`。

package/template/docs/templates/approval-record-template.yaml

@@ -0,0 +1,14 @@
+schema_version: 1
+gate_id: gate.spec-baseline-approved
+decision: approved
+actor_kind: digital-human
+role_id: role.product-manager
+runtime_id: runtime.generic
+runtime_instance_ref: "runtime.generic:role.product-manager"
+principal_ref: "instance:role.product-manager"
+drafter_role_id: role.requirements-manager
+countersigner_role_ids:
+  - role.product-manager
+evidence_refs: []
+biological_veto: false
+notes: 会签必须可读取；起草者不得出现在 countersigner_role_ids。运行时表情/reaction 无效。

package/template/docs/templates/digital-human-runtime-profile-template.md

@@ -0,0 +1,38 @@
+# 数字人运行时 Profile：<数字人角色>
+
+> 从 `docs/agents/digital-human-roles.yaml` 复制 title / description / skill。不要手写第二套职责。先选 `runtime_id`，再按该运行时适配器落地。
+
+## 绑定
+
+| 字段 | 内容 |
+|---|---|
+| 数字人角色 ID | `role.` |
+| 运行时 | `runtime.generic` / `runtime.skill-projection` / `runtime.grok` / 新增适配器 |
+| title | YAML `title` |
+| description | YAML `description` 全文，加上本 `project-instance` 仓库路径 |
+| 兼任 | 仅主控默认兼任 `role.project-manager`，直到 `dual_hat_split_when` |
+| 仓库路径 | 本 `project-instance` 的 git 根路径 |
+
+## Skills
+
+- 启用：YAML `core_skills`（投影根从 `.agents/skills` 加载同名 skill）
+- 保持关闭：YAML `forbidden_skills`
+- 账户或客户端能发现更多 skill，不等于该数字人可用
+
+## `project-instance` 绑定清单
+
+模板仓只 `publish-singleton-profiles`。实例仓按本表 duplicate，禁止按功能再拆实例。外部 `create-yss-spec` 尚未接管此步骤。
+
+- [ ] 从 YAML 复制 `title`、`description`、`core_skills`、`forbidden_skills`，不手写第二套职责
+- [ ] 选择一个 `runtime_id`（`runtime.generic` / `runtime.skill-projection` / `runtime.grok`）
+- [ ] `description` 末尾写明本仓库路径
+- [ ] 会签文件落在 `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`
+- [ ] 未命中 `dual_hat_split_when` 时，主控与项目经理共用同一实例
+
+## 协同
+
+- 人默认只跟主控说话。
+- 逻辑协作组以 YAML `stage_groups` 为准。
+- 当前运行时若声明了 `max_collaboration_group_size` 且 `overflow=one-to-one-handoff`，超员时改 1:1，不改逻辑组。
+- 会签按 YAML `gate_policy` 写 `docs/templates/approval-record-template.yaml`，填 `runtime_id` 与 `principal_ref`。恢复前跑 `scripts/verify-approval-record`。
+- 权威产物写 git。

package/template/docs/templates/grok-bot-profile-template.md

@@ -0,0 +1,24 @@
+# Grok Bot Profile：<数字人角色>
+
+> 这是 `runtime.grok` 适配模板。角色职责仍以 `docs/agents/digital-human-roles.yaml` 为准。通用流程见 `docs/templates/digital-human-runtime-profile-template.md`。
+
+## Profile
+
+| 字段 | 内容 |
+|---|---|
+| 数字人角色 ID | `role.` |
+| runtime_id | `runtime.grok` |
+| Grok title | YAML `title` |
+| Description | YAML `description` 全文，加上本 `project-instance` 仓库路径 |
+| 兼任 | 仅主控默认兼任 `role.project-manager`，直到 `dual_hat_split_when` |
+
+## Skills
+
+- 在 Grok **Settings → Plugins → Yours** 仅为该 Bot 启用 `core_skills`
+- `forbidden_skills` 保持关闭
+
+## Grok 约束
+
+- 群聊 2–6 人。逻辑协作组更大时用 1:1 异步交接，不要改 YAML `stage_groups`。
+- 全部 Bot 共享云计算机。写范围只写在任务包里。
+- 发邮件、改生产等走 Grok Allow；不等于生命周期门禁已过。会签写 git 记录并跑 `scripts/verify-approval-record`。

package/template/docs/templates/implementation-routing-template.md

@@ -275,9 +275,9 @@ owner: ai
 
 ## 6. Subagent 执行计划
 
-| task_id | subagent 角色 | 责任范围 | 允许修改文件 / 模块 | 禁止事项 | 输出回填位置 |
-|---|---|---|---|---|---|
-|  | Explorer / Drafter / Worker / Reviewer / Verifier | frontend / backend / test / review / verify / docs |  | 不得 Freeze / 不得安全放行 / 不得覆盖他人改动 |  |
+| task_id | 数字人角色 | runtime_id | core_skills（从角色表复制） | subagent 角色 | 责任范围 | 允许修改文件 / 模块 | 禁止事项 | 输出回填位置 |
+|---|---|---|---|---|---|---|---|---|
+|  | role.frontend-engineer | runtime.skill-projection | 从 YAML `core_skills` 复制 | Explorer / Drafter / Worker / Reviewer / Verifier | frontend / backend / test / review / docs |  | 不得 Freeze / 不得覆盖他人改动 / 不得会签自己的草稿 |  |
 
 | 并行风险 | 缓解措施 | 合并负责人 | 状态 |
 |---|---|---|---|