create-yss-spec 2.2.2 → 2.2.4

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 执行态正交，任务包必须同时写明。
+
+写入范围不得与其他执行者重叠；实现者不得同时担任同一切片的独立审查者，也不得会签自己起草的资产。写隔离以任务包为准。某运行时若共享磁盘或会话，不得把不同实例当成安全边界。
 
 ## 任务包
 
-每个任务包必须写明输入资产、目标、允许写路径、禁止事项、验收标准、验证命令和汇合方式。写入范围不得与其他执行者重叠；实现者不得同时担任同一切片的独立审查者。
+凡主控向数字人角色或独立运行时正式派发生命周期工作单元，都必须使用 `docs/process/schemas/digital-human-task-package.schema.json` 定义的任务包，并写明 `task_id`、`work_unit_id`、`actor_id`、数字人角色 ID、`runtime_id`、执行态、工作流状态、从 `docs/agents/digital-human-roles.yaml` 复制的 `core_skills` / `forbidden_skills`（可用 `taskPackageDefaults`）、合同类型和版本、输入资产、目标、允许写路径、禁止事项、验收标准、验证命令及其实际退出码 / 执行时间 / 证据引用、下游消费者和汇合方式。`slice-implementation` 才额外绑定 Slice Implementation Contract；禁止手写第二套技能包；任务包由 `scripts/verify-digital-human-task-package` 校验，`scripts/verify-subagent-task-package` 仅为兼容入口。
 
 ## 汇合
 
-返回结果至少包括变更文件、证据文件、实际执行的命令、结果、延期 seam、drift / violation / new impacts 和建议下一路由。主控 Agent 必须重新执行 fresh verification，并在集中 checkpoint 中保留阶段因果。
+返回结果必须符合 `workflow-execution-result-v1`，至少包括 `work_unit`、`workflow_reference`、`result`、`skill`、`changed_files` / `changed_artifacts`、`evidence_refs`、实际验证结果、`deferred_seams`、`drift`、`violation`、`new_impacts`、`stale_candidates`、`blocking_signals` 和 `next_route`。主控必须重新执行 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 / 不得覆盖他人改动 / 不得会签自己的草稿 |  |
 
 | 并行风险 | 缓解措施 | 合并负责人 | 状态 |
 |---|---|---|---|

package/template/docs/templates/local-parent-ticket-template.md

@@ -46,6 +46,14 @@ Status: ready-for-human
 - Verification：`docs/.scratch/<feature>/verification/`
 - Vertical slices：`docs/.scratch/<feature>/issues/`
 
+## 会签
+
+会签记录写在 `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`。会签桶内门禁标为 `approved` 前必须通过 `scripts/verify-approval-record`。
+
+| 门禁 | 记录路径 | 会签角色 | 状态 |
+|---|---|---|---|
+|  | `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml` | 见 `docs/agents/digital-human-roles.yaml` | pending / approved / blocked / not-applicable |
+
 ## 阻塞关系
 
 - 无 / 被 `<ticket-path>` 阻塞

package/template/docs/templates/subagent-task-package-template.md

@@ -3,7 +3,9 @@ status: template
 owner: ai
 ---
 
-# Subagent Task Package：<task_id>
+# Digital Human Task Package：<task_id>
+
+> Canonical contract: `docs/process/schemas/digital-human-task-package.schema.json`。本文件路径保留为兼容入口。
 
 > 用于主控 Agent 派发 subagent 前固定输入、输出、写范围和验收标准。没有任务包边界时，不得派发 subagent。
 
@@ -11,14 +13,23 @@ owner: ai
 
 | 字段 | 内容 |
 |---|---|
+| schema_version | `1` |
 | task_id |  |
+| work_unit_id | 对应生命周期注册表的 `work_units[].id`；实现子任务对应 Slice Contract 的 `work_units[].id` |
+| actor_id | 当前运行时实例标识；Reviewer 必须与实现者不同 |
 | Feature / Change |  |
 | 生命周期阶段 |  |
 | 对应门禁 |  |
 | Ticket / MR / PR |  |
 | 主控 Agent |  |
+| 数字人角色 | `role.` 见 `docs/agents/digital-human-roles.yaml` |
+| runtime_id | `runtime.generic` / `runtime.skill-projection` / `runtime.grok` |
+| core_skills | 从角色表复制，禁止手写 |
+| forbidden_skills | 从角色表复制，禁止手写 |
 | subagent 角色 | Explorer / Drafter / Worker / Reviewer / Verifier |
 | 任务类型 | explore / draft / work / review / verify |
+| execution_state | 与 subagent 角色一致；由主控派发 |
+| workflow_status | not-started / active / paused / resolved / failed |
 
 ## 2. 输入资产
 
@@ -31,11 +42,36 @@ owner: ai
 | Ticket / Slice / Checklist |  |  |
 | 代码 / 命令 / 其他 |  |  |
 
+## 2.1 合同与技能来源
+
+| 字段 | 内容 |
+|---|---|
+| contract_id |  |
+| contract_version |  |
+| contract_kind | `lifecycle-work-unit` / `slice-implementation` / `template-maintenance` |
+| contract_status | `issued` / `stale` / `blocked`；不替代生命周期门禁批准 |
+| contract_ref |  |
+| lifecycle_ref | 生命周期工作单元使用 |
+| Slice Implementation Contract | 仅 `slice-implementation` 填写 |
+| maintenance_ref | 仅 `template-maintenance` 填写维护 checkpoint |
+| 技能注册表 | `docs/agents/digital-human-roles.yaml` |
+| 技能默认值 | `taskPackageDefaults(<role_id>)` |
+
 ## 3. 输出要求
 
 | 输出 | 路径 / 链接 | 完成标准 |
 |---|---|---|
 |  |  |  |
+| expected_evidence_files |  |  |
+
+## 3.1 下游与汇合
+
+| 字段 | 内容 |
+|---|---|
+| downstream_consumers |  |
+| parent_work_unit | `<work-unit.id>` |
+| convergence_ref |  |
+| conflict_escalation |  |
 
 ## 4. 写范围
 
@@ -73,6 +109,12 @@ owner: ai
 | 主控 Agent 合并动作 | 采纳 / 部分采纳 / 不采纳 / 需返工 |
 | 未采纳原因 |  |
 
+## 7.1 实际验证结果
+
+| 命令 | exit_code | executed_at | evidence_ref |
+|---|---:|---|---|
+|  |  |  |  |
+
 ## 8. 子代理最终回复格式
 
 ```markdown

package/template/docs/templates/vertical-slice-ticket-template.md

@@ -53,6 +53,7 @@ Status: ready-for-human
 | contract_ref |  |
 | Router 状态 | draft / blocked / ready-for-lifecycle-review |
 | 生命周期批准状态 | pending / approved / rejected |
+| suggested_owner_role_id | `role.frontend-engineer` / `role.backend-engineer` / `role.test-engineer`（Router 建议，编排器派活） |
 | Build Architecture Checklist |  |
 
 > Router 不得自行将合同批准或将本 Ticket 推进为 `ready-for-agent`。只有生命周期编排器核验并持久化当前版本合同、清除阻塞边后，才能推进状态。
@@ -107,6 +108,12 @@ Status: ready-for-human
 
 出现 `drift`、`violation` 或非空 `new_impacts` 时暂停受影响工作单元，不得先完成代码再补合同；更新合同版本并通过生命周期审查后才能恢复。
 
+## 会签
+
+| 门禁 | 记录路径 | 会签角色 | 状态 |
+|---|---|---|---|
+|  | `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml` | 见 `docs/agents/digital-human-roles.yaml` | pending / approved / blocked / not-applicable |
+
 ## 状态
 
 `ready-for-agent`

package/template/docs/user-guide//344/272/247/345/223/201/347/240/224/345/217/221/345/205/250/347/224/237/345/221/275/345/221/250/346/234/237/346/234/200/344/275/263/345/256/236/350/267/265.md

@@ -197,6 +197,8 @@ agents 是角色分工，不是越多越好。只有当任务边界清楚、上
 
 Agent 交接必须写成自包含 brief，不能只丢一句“继续上面的”。推荐使用 `docs/templates/agent-brief-template.md`。
 
+职称数字人（前端工程师、产品经理等）是叠加在上表职能分工上的配置，权威清单和会签级别见 `docs/agents/digital-human-roles.yaml`。不要用职称实例替换生命周期编排器。阶段协作组是逻辑成员；Grok 等平台的群聊人数上限只约束该运行时如何开会，不改角色表。
+
 Agent brief 最少包含：
 
 - 背景和相关资产路径。

package/template/scripts/lib/approval-record.mjs

@@ -0,0 +1,123 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parseDocument } from "../vendor/yaml.mjs";
+import {
+  BIOLOGICAL_ROLE_ID,
+  countersignRuleForGate,
+  loadDigitalHumanRoles,
+  collectCountersignGateIds
+} from "./digital-human-roles.mjs";
+import { ROOT } from "./lifecycle-registry.mjs";
+
+const DECISIONS = new Set(["approved", "rejected", "vetoed"]);
+const ACTOR_KINDS = new Set(["digital-human", "biological-human", "orchestrator"]);
+
+function fail(message) {
+  throw new TypeError(message);
+}
+
+function requireString(value, field) {
+  if (typeof value !== "string" || !value.trim()) fail(`${field} 不能为空`);
+}
+
+function yamlFromFile(filePath, label) {
+  let source;
+  try {
+    source = readFileSync(filePath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") fail(`缺少${label}: ${filePath}`);
+    throw error;
+  }
+  const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length > 0) fail(`无法解析${label}: ${document.errors[0].message}`);
+  const value = document.toJS({ maxAliasCount: 0 });
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(`${label}必须是对象`);
+  return value;
+}
+
+export function loadApprovalRecord(filePath) {
+  return yamlFromFile(filePath, "会签记录");
+}
+
+export function resolveApprovalRef(approvalRef, fromFile = ROOT) {
+  requireString(approvalRef, "approval_ref");
+  if (path.isAbsolute(approvalRef)) return approvalRef;
+  const fromRoot = path.join(ROOT, approvalRef);
+  if (existsSync(fromRoot)) return fromRoot;
+  return path.resolve(path.dirname(fromFile), approvalRef);
+}
+
+export function validateApprovalRecord(record, { rolesDoc, requireApproved = false } = {}) {
+  if (!record || typeof record !== "object" || Array.isArray(record)) fail("会签记录必须是对象");
+  if (record.schema_version !== 1) fail("会签记录 schema_version 必须为 1");
+  requireString(record.gate_id, "gate_id");
+  requireString(record.decision, "decision");
+  if (!DECISIONS.has(record.decision)) fail("decision 必须是 approved、rejected 或 vetoed");
+  requireString(record.actor_kind, "actor_kind");
+  if (!ACTOR_KINDS.has(record.actor_kind)) fail("actor_kind 无效");
+  requireString(record.role_id, "role_id");
+  requireString(record.runtime_id, "runtime_id");
+  requireString(record.principal_ref, "principal_ref");
+
+  const registry = rolesDoc || loadDigitalHumanRoles();
+  const runtimeIds = new Set((registry.runtimes || []).map((runtime) => runtime.id));
+  if (!runtimeIds.has(record.runtime_id)) fail(`未知 runtime_id: ${record.runtime_id}`);
+  if (record.actor_kind === "orchestrator") fail("编排器门禁不使用会签记录关闭");
+
+  const rule = countersignRuleForGate(registry.gate_policy, record.gate_id);
+  if (!rule) fail(`${record.gate_id} 不是会签门禁；evidence_only / orchestrator 门禁不写 approval-record`);
+
+  if (requireApproved && record.decision !== "approved") {
+    fail(`${record.gate_id} 会签 decision 必须为 approved 才能关闭门禁`);
+  }
+  if (record.decision === "approved" && record.biological_veto === true) {
+    fail(`${record.gate_id} 已被生物人否决，不能标为 approved`);
+  }
+
+  if (rule.bucket === "biological_human") {
+    if (record.actor_kind !== "biological-human") fail(`${record.gate_id} 必须由生物人会签`);
+    if (record.role_id !== BIOLOGICAL_ROLE_ID) fail(`${record.gate_id} 的 role_id 必须为 ${BIOLOGICAL_ROLE_ID}`);
+    return rule;
+  }
+
+  if (record.actor_kind !== "digital-human") fail(`${record.gate_id} 必须由数字人会签`);
+  if (!rule.countersigners.includes(record.role_id)) {
+    fail(`${record.gate_id} 会签角色必须是 ${rule.countersigners.join(" / ")}`);
+  }
+  if (rule.drafter && record.role_id === rule.drafter) fail(`${record.gate_id} 起草者不得会签自己`);
+  if (Array.isArray(record.countersigner_role_ids) && rule.drafter && record.countersigner_role_ids.includes(rule.drafter)) {
+    fail(`${record.gate_id} 起草者不得出现在 countersigner_role_ids`);
+  }
+  if (rule.drafter && record.drafter_role_id && record.drafter_role_id !== rule.drafter) {
+    fail(`${record.gate_id} drafter_role_id 必须为 ${rule.drafter}`);
+  }
+  return rule;
+}
+
+export function validateApprovalRecordFile(filePath, options = {}) {
+  return validateApprovalRecord(loadApprovalRecord(filePath), options);
+}
+
+export function assertApprovedGateHasValidApproval(gateId, gateState, { checkpointPath } = {}) {
+  const rolesDoc = loadDigitalHumanRoles();
+  const countersignGates = new Set(collectCountersignGateIds(rolesDoc.gate_policy));
+  if (!countersignGates.has(gateId)) return;
+  if (!gateState || typeof gateState !== "object") fail(`${gateId} 缺少门禁状态`);
+  if (gateState.status !== "approved") return;
+  if (!gateState.approval_ref || !String(gateState.approval_ref).trim()) {
+    fail(`${gateId} 已 approved 但缺少 approval_ref`);
+  }
+  const resolved = resolveApprovalRef(gateState.approval_ref, checkpointPath || ROOT);
+  if (!existsSync(resolved)) fail(`${gateId} 的 approval_ref 不可读: ${gateState.approval_ref}`);
+  const record = loadApprovalRecord(resolved);
+  if (record.gate_id !== gateId) fail(`${gateId} 的会签记录 gate_id 不匹配`);
+  validateApprovalRecord(record, { rolesDoc, requireApproved: true });
+}
+
+export function assertCheckpointApprovals(checkpoint, checkpointPath) {
+  const gates = checkpoint?.gates;
+  if (!gates || typeof gates !== "object") return;
+  for (const [gateId, state] of Object.entries(gates)) {
+    assertApprovedGateHasValidApproval(gateId, state, { checkpointPath });
+  }
+}