create-yss-spec 2.2.2 → 2.2.4

package/template/scripts/lib/scenario-checks.mjs

@@ -3,12 +3,16 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { parseDocument } from "../vendor/yaml.mjs";
+import { lifecycleTransitionContract, validateImplementationEntry, validateNextRoute } from "./lifecycle-transition.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 const read = (relative) => readFileSync(path.join(root, relative), "utf8");
 function ensure(condition, message) { if (!condition) throw new TypeError(message); }
 function exists(relative) { return existsSync(path.join(root, relative)); }
 function includesAll(actual, expected) { return Array.isArray(actual) && expected.every((item) => actual.includes(item)); }
+function hasText(value) { return typeof value === "string" && value.trim().length > 0; }
+const virtualTicketDecompositionRef = "docs/.scratch/demo/evidence/ticket-decomposition-result.yaml";
+const virtualTicketDecomposition = "result_schema: workflow-execution-result-v1\nwork_unit: work-unit.ticket-decomposition\nresult: completed\nevidence_refs:\n  - docs/.scratch/demo/evidence/ticket-decomposition-result.yaml\n";
 
 function validateMattContract(data) {
   const direct = data.entry_routing?.direct_matt_entry;
@@ -84,13 +88,52 @@ function validateWorkflowExecutionResult(payload, contract, workUnitRoutes) {
   for (const field of contract.workflow_reference.required) ensure(typeof payload.workflow_reference?.[field] === "string" && payload.workflow_reference[field].trim(), `workflow_reference.${field} 无效`);
   const workUnit = workUnitRoutes?.[payload.work_unit];
   ensure(workUnit, `未知 Workflow Execution Result work_unit: ${payload.work_unit}`);
+  if (payload.result === "completed") {
+    const routeResult = validateNextRoute(payload.work_unit, payload.next_route);
+    ensure(routeResult.result === "allowed", `Workflow Execution Result next_route 非法: ${routeResult.blocking_signals.join(", ")}`);
+  }
   const accepted = [workUnit.native, workUnit.compatibility].filter(Boolean);
   ensure(contract.workflow_reference.allowed_sources.includes(payload.workflow_reference.source) && accepted.some((route) => route.source === payload.workflow_reference.source && route.skill === payload.workflow_reference.skill && route.invocation_mode === payload.workflow_reference.invocation_mode), "Workflow Execution Result workflow_reference 与 work_unit route 不匹配");
+  const workUnitRequirements = contract.work_unit_requirements?.[payload.work_unit];
+  if (workUnitRequirements && payload.result === "completed") {
+    for (const field of [...(workUnitRequirements.required ?? []), ...(workUnitRequirements.completed_requires ?? [])]) {
+      ensure(hasText(payload[field]), `Workflow Execution Result ${payload.work_unit} 缺少 ${field}`);
+    }
+    for (const field of workUnitRequirements.boolean_required ?? []) {
+      ensure(typeof payload[field] === "boolean", `Workflow Execution Result ${payload.work_unit} 缺少布尔字段 ${field}`);
+    }
+  }
+  if (payload.work_unit === "work-unit.slice-implementation" && payload.result === "completed") {
+    const implementationState = {
+      tracker_kind: payload.tracker_kind,
+      predecessor_work_unit: payload.predecessor_work_unit,
+      ready_for_agent: payload.ready_for_agent,
+      ticket_decomposition_result_ref: payload.ticket_decomposition_result_ref,
+      vertical_slice_ticket_ref: payload.vertical_slice_ticket_ref,
+      vertical_slice_ticket_role: payload.vertical_slice_ticket_role,
+      vertical_slice_ticket_kind: payload.vertical_slice_ticket_kind,
+      ticket_decomposition_result: { result: payload.ticket_decomposition_result_status, evidence_refs: payload.evidence_refs },
+      vertical_slice_ticket: { ref: payload.vertical_slice_ticket_ref, role: payload.vertical_slice_ticket_role, kind: payload.vertical_slice_ticket_kind },
+      slice_contract: {
+        ticket_ref: payload.slice_contract_ticket_ref,
+        status: payload.slice_contract_status,
+        persisted: payload.slice_contract_persisted,
+        current_version: payload.slice_contract_current_version,
+      },
+    };
+    const semantic = validateImplementationEntry(implementationState, {
+      // The scenario uses one explicit virtual fixture; arbitrary local refs
+      // must still pass the real readability check and cannot use a fallback.
+      exists: (ref) => exists(ref) || ref === "docs/.scratch/demo/issues/01-valid-slice.md" || ref === virtualTicketDecompositionRef,
+      read: (ref) => ref === virtualTicketDecompositionRef ? virtualTicketDecomposition : readFileSync(path.join(root, ref), "utf8"),
+    });
+    ensure(semantic.result === "allowed", `Workflow Execution Result implementation Ticket 语义非法: ${semantic.blocking_signals.join(", ")}`);
+  }
   if (payload.result !== "completed") return;
   for (const field of contract.completed_requires_empty) ensure(Array.isArray(payload[field]) && payload[field].length === 0, `completed 的 ${field} 必须为空`);
   for (const field of contract.completed_requires_non_empty) ensure(Array.isArray(payload[field]) && payload[field].length > 0, `completed 的 ${field} 不能为空`);
   if (contract.completed_requires_readable_evidence_refs) {
-    for (const reference of payload.evidence_refs) ensure(typeof reference === "string" && reference.trim() && exists(reference), `completed 证据不可读取: ${reference}`);
+    for (const reference of payload.evidence_refs) ensure(typeof reference === "string" && reference.trim() && (exists(reference) || reference === virtualTicketDecompositionRef), `completed 证据不可读取: ${reference}`);
   }
   if (contract.completed_requires_no_blocking_signals) ensure(Array.isArray(payload.blocking_signals) && payload.blocking_signals.length === 0, "completed 不得携带 blocking_signals");
 }
@@ -177,6 +220,16 @@ export function runScenario(name) {
     const releaseGate = registry.gates.find((gate) => gate.id === "gate.release-ready");
     ensure(releaseGate?.requires_gates?.includes("gate.frontend-implementation-verified"), "发布就绪未依赖前端实现还原门禁");
     const contract = parseDocument(read(".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml"), { uniqueKeys: true }).toJS({ maxAliasCount: 0 });
+    ensure(contract.ready_for_agent?.requires_vertical_slice_ticket === true && contract.ready_for_agent?.parent_ticket_as_implementation_ref === "forbidden", "ready_for_agent 未强制垂直切片且禁止父 Ticket 实现引用");
+    ensure(includesAll(contract.ready_for_agent?.required, ["ticket_decomposition_result_ref", "vertical_slice_ticket_ref", "vertical_slice_ticket_role", "vertical_slice_ticket_kind"]), "ready_for_agent 缺少 Ticket 正式化必填字段");
+    ensure(contract.ticket_formalization?.implementation_predecessor === "work-unit.ticket-decomposition" && contract.ticket_formalization?.vertical_slice_ticket?.parent_ticket_ref_forbidden === true, "Ticket 正式化实现前置或父 Ticket 禁止规则缺失");
+    ensure(contract.transition_graph?.implementation_requires_predecessor === "work-unit.ticket-decomposition", "生命周期转换图未声明实现前置工作单元");
+    ensure(JSON.stringify(contract.transition_graph?.forbidden_shortcuts) === JSON.stringify([
+      { from: "work-unit.spec-synthesis", to: "work-unit.slice-implementation" },
+      { from: "work-unit.prototype-design", to: "work-unit.slice-implementation" },
+      { from: "work-unit.technical-analysis", to: "work-unit.slice-implementation" },
+    ]), "生命周期转换图缺少 Spec/原型/技术分析到实现的越级阻断");
+    ensure(lifecycleTransitionContract.next_routes["work-unit.ticket-decomposition"]?.includes("work-unit.slice-implementation"), "转换校验器未允许 Ticket 正式化后进入实现");
     ensure(contract.release_readiness?.conditional?.ui_impact?.includes("gate.frontend-implementation-verified") && contract.frontend_implementation_plan?.acceptance?.includes("no_template_placeholders"), "发布公式或前端计划实质校验不完整");
     const templateRejected = spawnSync("scripts/verify-frontend-implementation-evidence", ["docs/process/templates/frontend-implementation-plan-template.yaml"], { cwd: root, encoding: "utf8" });
     ensure(templateRejected.status !== 0 && templateRejected.stderr.includes("template: false"), "前端实现计划占位模板可冒充正式批准证据");
@@ -200,6 +253,46 @@ export function runScenario(name) {
       blocking_signals: []
     };
     validateWorkflowExecutionResult(validResult, data.workflow_execution_result, data.work_unit_routes);
+    const validTicketResult = {
+      ...validResult,
+      work_unit: "work-unit.ticket-decomposition",
+      next_route: "work-unit.slice-implementation",
+      ticket_decomposition_result_ref: "docs/.scratch/demo/evidence/ticket-decomposition-result.yaml",
+      vertical_slice_ticket_ref: "docs/.scratch/demo/issues/01-valid-slice.md",
+    };
+    validateWorkflowExecutionResult(validTicketResult, data.workflow_execution_result, data.work_unit_routes);
+    const validImplementationResult = {
+      ...validResult,
+      evidence_refs: [virtualTicketDecompositionRef, "docs/process/lifecycle-registry.yaml"],
+      work_unit: "work-unit.slice-implementation",
+      next_route: "work-unit.code-review",
+      predecessor_work_unit: "work-unit.ticket-decomposition",
+      ready_for_agent: true,
+      ticket_decomposition_result_ref: "docs/.scratch/demo/evidence/ticket-decomposition-result.yaml",
+      ticket_decomposition_result_status: "completed",
+      vertical_slice_ticket_ref: "docs/.scratch/demo/issues/01-valid-slice.md",
+      vertical_slice_ticket_role: "ready-for-agent",
+      vertical_slice_ticket_kind: "vertical-slice-ticket",
+      slice_contract_ticket_ref: "docs/.scratch/demo/issues/01-valid-slice.md",
+      slice_contract_status: "approved",
+      slice_contract_persisted: true,
+      slice_contract_current_version: true,
+    };
+    validateWorkflowExecutionResult(validImplementationResult, data.workflow_execution_result, data.work_unit_routes);
+    for (const mutate of [
+      (item) => { item.vertical_slice_ticket_role = "ready-for-human"; },
+      (item) => { item.vertical_slice_ticket_kind = "parent-ticket"; },
+      (item) => { item.vertical_slice_ticket_ref = "docs/.scratch/demo/parent-ticket.md"; },
+      (item) => { item.slice_contract_ticket_ref = "docs/.scratch/demo/issues/02-other.md"; },
+      (item) => { item.predecessor_work_unit = "work-unit.spec-synthesis"; },
+      (item) => { item.ticket_decomposition_result_status = "blocked"; },
+      (item) => { item.ticket_decomposition_result_status = "needs-human"; },
+    ]) {
+      const invalid = structuredClone(validImplementationResult); mutate(invalid);
+      let rejected = false;
+      try { validateWorkflowExecutionResult(invalid, data.workflow_execution_result, data.work_unit_routes); } catch { rejected = true; }
+      ensure(rejected, "实现 Workflow Execution Result 的 Ticket 语义变异未被拒绝");
+    }
     const unavailableResult = structuredClone(validResult);
     unavailableResult.result = "blocked";
     unavailableResult.unavailable_skill = { skill: "yss-ui", provider: "codex", fallback: "manual-review", resolution: "needs-human" };
@@ -221,7 +314,8 @@ export function runScenario(name) {
       (item) => { item.new_impacts = ["new-api"]; },
       (item) => { item.workflow_reference.source = "untrusted/source"; },
       (item) => { item.workflow_reference.skill = "implement"; },
-      (item) => { item.workflow_reference.invocation_mode = "reference"; }
+      (item) => { item.workflow_reference.invocation_mode = "reference"; },
+      (item) => { item.next_route = "work-unit.slice-implementation"; }
     ]) {
       const invalid = structuredClone(validResult); mutate(invalid);
       let rejected = false;

package/template/scripts/lib/task-package.mjs

@@ -0,0 +1,214 @@
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { parseDocument } from "../vendor/yaml.mjs";
+import { loadDigitalHumanRoles, taskPackageDefaults } from "./digital-human-roles.mjs";
+import { loadRegistry, ROOT } from "./lifecycle-registry.mjs";
+import { loadMaintenanceCheckpoint, validateMaintenanceCheckpoint } from "./maintenance-intensity.mjs";
+import { validateNextRoute } from "./lifecycle-transition.mjs";
+
+export const TASK_PACKAGE_SCHEMA = path.join(ROOT, "docs/process/schemas/digital-human-task-package.schema.json");
+export const LEGACY_TASK_PACKAGE_SCHEMA = path.join(ROOT, "docs/process/schemas/subagent-task-package.schema.json");
+export const TASK_PACKAGE_REGISTRY_REF = "docs/agents/digital-human-roles.yaml";
+export const CONTRACT_KINDS = new Set(["lifecycle-work-unit", "slice-implementation", "template-maintenance"]);
+export const EXECUTION_STATES = new Set(["Explorer", "Drafter", "Worker", "Reviewer", "Verifier"]);
+export const WORKFLOW_STATUSES = new Set(["not-started", "active", "paused", "resolved", "failed"]);
+
+function fail(message) { throw new TypeError(message); }
+function requireString(value, field) { if (typeof value !== "string" || !value.trim()) fail(`${field} 不能为空`); }
+function equalArrays(actual, expected) { return Array.isArray(actual) && actual.length === expected.length && actual.every((value, index) => value === expected[index]); }
+
+function parseYaml(source, label) {
+  const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length > 0) fail(`无法解析${label}: ${document.errors[0].message}`);
+  return document.toJS({ maxAliasCount: 0 });
+}
+
+function assertSafeRelativePath(value, field) {
+  requireString(value, field);
+  if (path.isAbsolute(value)) fail(`${field} 必须是仓库相对路径`);
+  const resolved = path.resolve(ROOT, value);
+  const relative = path.relative(ROOT, resolved);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`)) fail(`${field} 不得越出仓库根目录`);
+  return resolved;
+}
+
+function assertReadableEvidenceRef(value, field) {
+  requireString(value, field);
+  if (/^https?:\/\//.test(value)) return;
+  const evidencePath = assertSafeRelativePath(value, field);
+  if (!existsSync(evidencePath)) fail(`${field} 不可读: ${value}`);
+}
+
+export function loadTaskPackage(filePath) {
+  const sourcePath = path.resolve(filePath);
+  if (!existsSync(sourcePath)) fail(`任务包不存在: ${filePath}`);
+  const value = parseYaml(readFileSync(sourcePath, "utf8"), "任务包");
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail("任务包必须是对象");
+  return { value, sourcePath };
+}
+
+export function validateTaskPackageSchema(value, schemaPath = TASK_PACKAGE_SCHEMA) {
+  const effectiveSchema = path.resolve(schemaPath) === path.resolve(LEGACY_TASK_PACKAGE_SCHEMA) ? TASK_PACKAGE_SCHEMA : schemaPath;
+  if (!existsSync(effectiveSchema)) fail(`缺少任务包 schema: ${effectiveSchema}`);
+  const validator = String.raw`
+import json
+import sys
+from jsonschema import Draft202012Validator
+schema = json.load(open(sys.argv[1], encoding="utf-8"))
+value = json.load(sys.stdin)
+errors = sorted(Draft202012Validator(schema).iter_errors(value), key=lambda error: list(error.absolute_path))
+for error in errors:
+    location = ".".join(str(part) for part in error.absolute_path) or "<root>"
+    print(f"{location}: {error.message}", file=sys.stderr)
+sys.exit(1 if errors else 0)
+`;
+  const result = spawnSync("python3", ["-c", validator, effectiveSchema], { cwd: ROOT, encoding: "utf8", input: JSON.stringify(value) });
+  if (result.status !== 0) fail(`${result.stdout}${result.stderr}`.trim());
+}
+
+function validateSkillSource(value, registry) {
+  const defaults = taskPackageDefaults(value.role_id, registry);
+  if (value.skill_source.registry_ref !== TASK_PACKAGE_REGISTRY_REF) fail(`skill_source.registry_ref 必须为 ${TASK_PACKAGE_REGISTRY_REF}`);
+  if (value.skill_source.defaults_ref !== `taskPackageDefaults(${value.role_id})`) fail(`skill_source.defaults_ref 必须为 taskPackageDefaults(${value.role_id})`);
+  if (!equalArrays(value.skill_source.core_skills, defaults.core_skills)) fail("skill_source.core_skills 必须与角色注册表完全一致");
+  if (!equalArrays(value.skill_source.forbidden_skills, defaults.forbidden_skills)) fail("skill_source.forbidden_skills 必须与角色注册表完全一致");
+}
+
+function validateCommon(value, registry, lifecycle) {
+  const workUnit = lifecycle.work_units.find((item) => item.id === value.work_unit_id);
+  if (!workUnit && value.contract.kind !== "slice-implementation") fail(`未知 work_unit_id: ${value.work_unit_id}`);
+  const roleDefaults = taskPackageDefaults(value.role_id, registry);
+  const runtimeIds = new Set((registry.runtimes || []).map((runtime) => runtime.id));
+  if (!runtimeIds.has(value.runtime_id)) fail(`未知 runtime_id: ${value.runtime_id}`);
+  if (!EXECUTION_STATES.has(value.execution_state)) fail(`execution_state 无效: ${value.execution_state}`);
+  if (!WORKFLOW_STATUSES.has(value.workflow_status)) fail(`workflow_status 无效: ${value.workflow_status}`);
+  if (value.stage_id) {
+    if (!lifecycle.stages.some((stage) => stage.id === value.stage_id)) fail(`未知 stage_id: ${value.stage_id}`);
+    if (!roleDefaults.stages.includes(value.stage_id)) fail(`role_id 未覆盖 stage_id: ${value.role_id} -> ${value.stage_id}`);
+  }
+  validateSkillSource(value, registry);
+  for (const allowed of value.allowed_write_paths) assertSafeRelativePath(allowed, "allowed_write_paths 条目");
+  if (value.execution_state === "Reviewer" && value.review_context.implementation_actor_id === value.actor_id) fail("Reviewer 必须与实现者使用不同 actor_id");
+  const commands = new Set(value.verification_commands);
+  for (const result of value.verification_results) {
+    if (!commands.has(result.command)) fail(`verification_results 命令未声明: ${result.command}`);
+    assertReadableEvidenceRef(result.evidence_ref, "verification_results.evidence_ref");
+  }
+  const completed = value.workflow_status === "resolved" || value.result?.result === "completed";
+  if (completed) {
+    if (!value.result || value.result.result !== "completed") fail("resolved/完成任务必须返回 result=completed 的 Workflow Execution Result");
+    if (value.workflow_status !== "resolved") fail("result=completed 的任务包必须处于 resolved 状态");
+    for (const field of ["result_schema", "work_unit", "workflow_reference", "skill", "changed_files", "evidence_refs", "deferred_seams", "drift", "violation", "new_impacts", "stale_candidates", "next_route", "blocking_signals"]) {
+      if (value.result[field] === undefined) fail(`result=completed 时 ${field} 不能为空`);
+    }
+    if (value.result.result_schema !== "workflow-execution-result-v1") fail("result_schema 必须为 workflow-execution-result-v1");
+    if (value.result.work_unit !== value.work_unit_id) fail("Workflow Execution Result.work_unit 必须与任务包 work_unit_id 一致");
+    const routeResult = validateNextRoute(value.result.work_unit, value.result.next_route);
+    if (routeResult.result !== "allowed") fail(`Workflow Execution Result next_route 非法: ${routeResult.blocking_signals.join(", ")}`);
+    value.expected_evidence_files.forEach((ref) => assertReadableEvidenceRef(ref, "expected_evidence_files"));
+    if (value.verification_results.length === 0) fail("已完成任务必须包含 verification_results");
+    if (value.verification_results.some((result) => result.exit_code !== 0)) fail("已完成任务的验证命令必须全部成功");
+    const resultCommands = new Set(value.verification_results.map((result) => result.command));
+    if (value.verification_commands.some((command) => !resultCommands.has(command))) fail("已完成任务必须覆盖全部 verification_commands");
+  }
+  if (value.result) {
+    for (const field of ["new_impacts", "stale_candidates", "blocking_signals", "drift", "violation"]) {
+      if (value.result.result === "completed" && Array.isArray(value.result[field]) && value.result[field].length > 0) fail(`result=completed 时 ${field} 必须为空`);
+    }
+    if (value.result.result === "completed") {
+      if (!Array.isArray(value.result.evidence_refs) || value.result.evidence_refs.length === 0) fail("result=completed 时 evidence_refs 不能为空");
+      value.result.evidence_refs.forEach((ref) => assertReadableEvidenceRef(ref, "result.evidence_refs"));
+    }
+    if (Array.isArray(value.result.changed_files)) {
+      for (const changed of value.result.changed_files) {
+        const changedPath = assertSafeRelativePath(changed, "changed_files 条目");
+        if (!value.allowed_write_paths.some((allowed) => {
+          const allowedPath = assertSafeRelativePath(allowed, "allowed_write_paths 条目");
+          const relative = path.relative(allowedPath, changedPath);
+          return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`));
+        })) fail(`changed_files 超出 allowed_write_paths: ${changed}`);
+      }
+    }
+  }
+  return workUnit;
+}
+
+function validateContract(value, registry, lifecycle) {
+  const contract = value.contract;
+  const implementationWorkUnit = "work-unit.slice-implementation";
+  const workUnit = lifecycle.work_units.find((item) => item.id === value.work_unit_id);
+  if (!CONTRACT_KINDS.has(contract.kind)) fail(`未知 contract.kind: ${contract.kind}`);
+  if (!new Set(["issued", "stale", "blocked"]).has(contract.status)) fail(`contract.status 无效: ${contract.status}`);
+  if (contract.status === "stale" && value.workflow_status !== "paused") fail("stale 任务包必须暂停，待主控重新路由");
+  assertReadableEvidenceRef(contract.contract_ref, "contract.contract_ref");
+  if (contract.kind === "lifecycle-work-unit") {
+    if (value.work_unit_id === implementationWorkUnit || value.convergence.parent_work_unit === implementationWorkUnit) {
+      fail("lifecycle-work-unit 不得冒充垂直切片实现任务；实现任务必须使用 slice-implementation");
+    }
+    if (workUnit?.scope === "template-source") fail("template-source 工作单元必须使用 template-maintenance");
+    if (contract.slice_contract_ref || contract.maintenance_ref) fail("lifecycle-work-unit 不得携带专项合同引用");
+    assertReadableEvidenceRef(contract.lifecycle_ref, "contract.lifecycle_ref");
+    return;
+  }
+  if (contract.kind === "template-maintenance") {
+    if (contract.slice_contract_ref || contract.lifecycle_ref) fail("template-maintenance 不得携带其他合同引用");
+    const checkpointPath = assertSafeRelativePath(contract.maintenance_ref, "contract.maintenance_ref");
+    if (!existsSync(checkpointPath)) fail(`维护 checkpoint 不存在: ${contract.maintenance_ref}`);
+    validateMaintenanceCheckpoint(loadMaintenanceCheckpoint(contract.maintenance_ref));
+    if (lifecycle.work_units.find((item) => item.id === value.work_unit_id)?.scope !== "template-source") fail("template-maintenance 必须绑定 template-source work unit");
+    return;
+  }
+  if (contract.lifecycle_ref || contract.maintenance_ref) fail("slice-implementation 不得携带其他合同引用");
+  if (!/^stage\.vertical-slice-implementation$/.test(value.stage_id)) fail("slice-implementation 必须绑定垂直切片实现阶段");
+  if (value.convergence.parent_work_unit !== implementationWorkUnit) fail("slice-implementation 必须汇合到 work-unit.slice-implementation");
+  if (/^https?:\/\//.test(contract.slice_contract_ref)) fail("slice_contract_ref 必须引用本地已持久化的 Slice Implementation Contract");
+  const contractPath = assertSafeRelativePath(contract.slice_contract_ref, "contract.slice_contract_ref");
+  if (!existsSync(contractPath)) fail(`Slice Implementation Contract 不存在: ${contract.slice_contract_ref}`);
+  const document = parseYaml(readFileSync(contractPath, "utf8"), "Slice Implementation Contract");
+  const slice = document.slice_contract || document;
+  if (slice.schema_version !== 1 || typeof slice.slice_id !== "string" || !slice.lifecycle_refs || !slice.readiness || !Array.isArray(slice.work_units)) fail("Slice Implementation Contract 缺少 schema_version/slice_id/lifecycle_refs/readiness/work_units");
+  if (slice.contract_id !== contract.contract_id || slice.contract_version !== contract.contract_version || slice.status !== "approved") fail("Slice Contract 必须是当前 approved 版本");
+  const sliceUnit = slice.work_units.find((item) => item && item.id === value.work_unit_id);
+  if (!sliceUnit) fail(`Slice Implementation Contract 缺少 work_unit_id: ${value.work_unit_id}`);
+  for (const field of ["role_id", "runtime_id", "task_package_ref", "contract_id", "contract_version", "allowed_write_paths"]) if (sliceUnit[field] === undefined) fail(`Slice Contract work_unit 缺少 ${field}`);
+  if (sliceUnit.role_id !== value.role_id || sliceUnit.runtime_id !== value.runtime_id || sliceUnit.contract_id !== contract.contract_id || sliceUnit.contract_version !== contract.contract_version || sliceUnit.task_package_ref !== value.work_unit_id) fail("任务包与 Slice Contract work_unit 不一致");
+  for (const allowed of value.allowed_write_paths) if (!sliceUnit.allowed_write_paths.includes(allowed)) fail(`allowed_write_paths 未获 Slice Contract 授权: ${allowed}`);
+}
+
+export function validateTaskPackage(value, { rolesDoc, lifecycleDoc } = {}) {
+  validateTaskPackageSchema(value);
+  const registry = rolesDoc || loadDigitalHumanRoles();
+  const lifecycle = lifecycleDoc || loadRegistry();
+  validateCommon(value, registry, lifecycle);
+  validateContract(value, registry, lifecycle);
+  return value;
+}
+
+export function generateTaskPackageDefaults(roleId, overrides = {}, { rolesDoc } = {}) {
+  const defaults = taskPackageDefaults(roleId, rolesDoc || loadDigitalHumanRoles());
+  return {
+    schema_version: 1,
+    role_id: defaults.role_id,
+    skill_source: {
+      registry_ref: TASK_PACKAGE_REGISTRY_REF,
+      defaults_ref: `taskPackageDefaults(${roleId})`,
+      core_skills: defaults.core_skills,
+      forbidden_skills: defaults.forbidden_skills
+    },
+    ...overrides
+  };
+}
+
+export function validateTaskPackageSet(packages, options = {}) {
+  if (!Array.isArray(packages) || packages.length === 0) fail("任务包集合不能为空");
+  packages.forEach((pkg) => validateTaskPackage(pkg, options));
+  const slicePackages = packages.filter((pkg) => pkg.contract.kind === "slice-implementation");
+  if (slicePackages.length > 0) {
+    const contracts = new Set(slicePackages.map((pkg) => `${pkg.contract.contract_id}@${pkg.contract.contract_version}`));
+    if (contracts.size !== 1) fail("同一切片的任务包必须消费同一 contract_id/contract_version");
+    const workers = new Set(slicePackages.filter((pkg) => pkg.execution_state === "Worker").map((pkg) => pkg.actor_id));
+    slicePackages.filter((pkg) => pkg.execution_state === "Reviewer").forEach((pkg) => { if (workers.has(pkg.actor_id)) fail("Reviewer 不得与实现者使用同一 actor_id"); });
+  }
+  return packages;
+}

package/template/scripts/verify-approval-record

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { validateApprovalRecordFile } from "./lib/approval-record.mjs";
+
+try {
+  const { positionals } = parseArgs({ allowPositionals: true, strict: true });
+  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-approval-record <approval-record.yaml>");
+  validateApprovalRecordFile(positionals[0]);
+  process.stdout.write("会签记录校验通过\n");
+} catch (error) {
+  process.stderr.write(`会签记录校验失败: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/verify-digital-human-roles

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { validateDefaultDigitalHumanRoles } from "./lib/digital-human-roles.mjs";
+
+try {
+  const result = validateDefaultDigitalHumanRoles();
+  process.stdout.write(`数字人角色注册表校验通过（${result.role_count} 个角色，${result.group_count} 个协作组，${result.runtime_count} 个运行时）\n`);
+} catch (error) {
+  process.stderr.write(`数字人角色注册表校验失败: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/verify-digital-human-roles-scenarios

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+import { validateDefaultDigitalHumanRoles, validateDigitalHumanRoles, loadDigitalHumanRoles, skillIdsFromRegistry } from "./lib/digital-human-roles.mjs";
+import { loadRegistry } from "./lib/lifecycle-registry.mjs";
+import { loadSkillRegistry } from "./lib/skill-registry.mjs";
+import { validateApprovalRecord, validateApprovalRecordFile } from "./lib/approval-record.mjs";
+
+function clone() {
+  return structuredClone(loadDigitalHumanRoles());
+}
+
+function deps() {
+  const lifecycle = loadRegistry();
+  const skills = loadSkillRegistry();
+  const ids = (records) => new Set(records.map((record) => record.id));
+  return {
+    skillIds: skillIdsFromRegistry(skills),
+    stageIds: ids(lifecycle.stages),
+    gateIds: ids(lifecycle.gates),
+    artifactIds: ids(lifecycle.artifacts),
+    evidenceIds: ids(lifecycle.evidence),
+    workUnitIds: ids(lifecycle.work_units),
+    skillRegistry: skills
+  };
+}
+
+function mustFail(doc, pattern, label) {
+  let failed = false;
+  let message = "";
+  try {
+    validateDigitalHumanRoles(doc, deps());
+  } catch (error) {
+    failed = true;
+    message = error.message;
+  }
+  if (!failed) throw new TypeError(`错误配置未被拒绝: ${label}`);
+  if (!pattern.test(message)) throw new TypeError(`${label} 失败原因不符合预期: ${message}`);
+}
+
+validateDefaultDigitalHumanRoles();
+
+const seven = [
+  "role.lifecycle-orchestrator",
+  "role.requirements-manager",
+  "role.product-manager",
+  "role.business",
+  "role.frontend-engineer",
+  "role.backend-engineer",
+  "role.test-engineer"
+];
+
+const genericAllowsSeven = clone();
+genericAllowsSeven.stage_groups[0].members = seven;
+validateDigitalHumanRoles(genericAllowsSeven, deps());
+
+const grokForbidsSeven = clone();
+grokForbidsSeven.stage_groups[0].members = seven;
+grokForbidsSeven.runtimes.find((runtime) => runtime.id === "runtime.grok").overflow = "forbid";
+mustFail(grokForbidsSeven, /禁止超过 6 人/, "Grok 适配器在 overflow=forbid 时拒绝七人协作组");
+
+const coupled = clone();
+coupled.roles[0].grok_title = "legacy";
+mustFail(coupled, /平台耦合字段/, "角色上残留 grok_title");
+
+const unknownSkill = clone();
+unknownSkill.roles[0].core_skills = ["not-a-registered-skill"];
+mustFail(unknownSkill, /未登记技能/, "未知技能");
+
+const overlap = clone();
+overlap.roles.find((role) => role.id === "role.frontend-engineer").forbidden_skills.push("yss-ui");
+mustFail(overlap, /重叠/, "启用且禁止同一技能");
+
+const selfSign = clone();
+selfSign.gate_policy.dual_digital_human[0].countersigners = ["role.requirements-manager"];
+mustFail(selfSign, /起草者不得会签自己/, "起草者自签");
+
+const releaseByBot = clone();
+releaseByBot.gate_policy.biological_human = ["gate.architecture-reviewed"];
+releaseByBot.gate_policy.digital_human_review.push({
+  gate: "gate.release-ready",
+  countersigners: ["role.product-manager"]
+});
+mustFail(releaseByBot, /gate\.release-ready/, "数字人关闭发布门禁");
+
+const missingSigners = clone();
+missingSigners.gate_policy.digital_human_review[0].countersigners = [];
+mustFail(missingSigners, /countersigners/, "单审门禁缺 countersigners");
+
+const stringReview = clone();
+stringReview.gate_policy.digital_human_review = ["gate.prototype-reviewed"];
+mustFail(stringReview, /必须是含 gate/, "单审门禁仍用字符串名单");
+
+const missingGeneric = clone();
+missingGeneric.runtimes = missingGeneric.runtimes.filter((runtime) => runtime.id !== "runtime.generic");
+mustFail(missingGeneric, /缺少运行时绑定: runtime.generic/, "缺少通用运行时");
+
+validateApprovalRecordFile("docs/templates/approval-record-template.yaml");
+
+const rolesDoc = loadDigitalHumanRoles();
+try {
+  validateApprovalRecord({
+    schema_version: 1,
+    gate_id: "gate.spec-baseline-approved",
+    decision: "approved",
+    actor_kind: "digital-human",
+    role_id: "role.requirements-manager",
+    runtime_id: "runtime.generic",
+    principal_ref: "instance:wrong"
+  }, { rolesDoc });
+  throw new TypeError("错误配置未被拒绝: 错误角色会签");
+} catch (error) {
+  if (!/会签角色必须是/.test(error.message)) throw new TypeError(`错误角色会签 失败原因不符合预期: ${error.message}`);
+}
+
+try {
+  validateApprovalRecord({
+    schema_version: 1,
+    gate_id: "gate.spec-baseline-approved",
+    decision: "approved",
+    actor_kind: "digital-human",
+    role_id: "role.requirements-manager",
+    runtime_id: "runtime.generic",
+    principal_ref: "instance:req",
+    drafter_role_id: "role.requirements-manager"
+  }, { rolesDoc });
+  throw new TypeError("错误配置未被拒绝: 起草者自签会签记录");
+} catch (error) {
+  if (!/会签角色必须是|起草者不得会签自己/.test(error.message)) {
+    throw new TypeError(`起草者自签会签记录 失败原因不符合预期: ${error.message}`);
+  }
+}
+
+try {
+  validateApprovalRecord({
+    schema_version: 1,
+    gate_id: "gate.release-ready",
+    decision: "approved",
+    actor_kind: "digital-human",
+    role_id: "role.product-manager",
+    runtime_id: "runtime.generic",
+    principal_ref: "instance:pm"
+  }, { rolesDoc });
+  throw new TypeError("错误配置未被拒绝: 数字人关发布会签记录");
+} catch (error) {
+  if (!/必须由生物人会签/.test(error.message)) throw new TypeError(`数字人关发布会签记录 失败原因不符合预期: ${error.message}`);
+}
+
+process.stdout.write("数字人角色压力场景验证通过\n");

package/template/scripts/verify-digital-human-task-package

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { loadTaskPackage, validateTaskPackage } from "./lib/task-package.mjs";
+
+try {
+  const { positionals } = parseArgs({ allowPositionals: true, strict: true });
+  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-digital-human-task-package <task-package.yaml|task-package.json>");
+  const { value } = loadTaskPackage(positionals[0]);
+  validateTaskPackage(value);
+  process.stdout.write("数字人任务包验证通过\n");
+} catch (error) {
+  process.stderr.write(`数字人任务包验证失败: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/verify-digital-human-task-package-scenarios

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const result = spawnSync(process.execPath, [path.join(root, "scripts/verify-subagent-task-package-scenarios"), ...process.argv.slice(2)], { stdio: "inherit" });
+process.exitCode = result.status ?? 1;

package/template/scripts/verify-lifecycle-checkpoint

@@ -5,6 +5,7 @@ import path from "node:path";
 import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
 import { parseDocument } from "./vendor/yaml.mjs";
+import { assertCheckpointApprovals } from "./lib/approval-record.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const schemaPath = path.join(root, "docs/process/schemas/lifecycle-checkpoint.schema.json");
@@ -30,6 +31,7 @@ try {
   const value = document.toJS({ maxAliasCount: 0 });
   const result = spawnSync("python3", ["-c", validator, schemaPath], { cwd: root, encoding: "utf8", input: JSON.stringify(value) });
   if (result.status !== 0) throw new TypeError(`${result.stdout}${result.stderr}`.trim());
+  assertCheckpointApprovals(value, sourcePath);
   process.stdout.write("生命周期 checkpoint 验证通过\n");
 } catch (error) {
   process.stderr.write(`生命周期 checkpoint 验证失败: ${error.message}\n`);