create-yss-spec 2.2.3 → 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-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-transition-scenarios

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { validateImplementationEntry, validateNextRoute, validateTicketFormalization } from "./lib/lifecycle-transition.mjs";
+
+const exists = (ref) => [
+  "docs/process/lifecycle-registry.yaml",
+  "docs/.scratch/demo/issues/01-valid-slice.md",
+  "docs/.scratch/demo/evidence/ticket-decomposition-result.yaml",
+].includes(ref);
+const decompositionResult = `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`;
+const read = (ref) => ref === "docs/.scratch/demo/evidence/ticket-decomposition-result.yaml" ? decompositionResult : "";
+const options = { exists, read };
+
+const validTicketState = {
+  predecessor_work_unit: "work-unit.ticket-decomposition",
+  tracker_kind: "local-markdown",
+  ticket_decomposition_result_ref: "docs/.scratch/demo/evidence/ticket-decomposition-result.yaml",
+  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",
+  ticket_decomposition_result: {
+    result: "completed",
+    evidence_refs: ["docs/.scratch/demo/evidence/ticket-decomposition-result.yaml"],
+  },
+  vertical_slice_ticket: {
+    ref: "docs/.scratch/demo/issues/01-valid-slice.md",
+    kind: "vertical-slice-ticket",
+    role: "ready-for-agent",
+  },
+  slice_contract: {
+    ticket_ref: "docs/.scratch/demo/issues/01-valid-slice.md",
+    status: "approved",
+    persisted: true,
+    current_version: true,
+  },
+};
+
+const valid = validateTicketFormalization(validTicketState, options);
+assert.equal(valid.result, "allowed");
+
+const implementation = validateImplementationEntry({
+  ...validTicketState,
+  ready_for_agent: true,
+}, options);
+assert.equal(implementation.result, "allowed");
+
+const cases = [
+  ["missing decomposition result ref", { ...validTicketState, ticket_decomposition_result_ref: undefined }, "ticket-decomposition-result-ref-missing"],
+  ["missing slice ref", { ...validTicketState, vertical_slice_ticket_ref: undefined }, "vertical-slice-ticket-ref-missing"],
+  ["missing slice role", { ...validTicketState, vertical_slice_ticket_role: undefined }, "vertical-slice-ticket-role-missing"],
+  ["missing slice kind", { ...validTicketState, vertical_slice_ticket_kind: undefined }, "vertical-slice-ticket-kind-missing"],
+  ["missing vertical slice", { ...validTicketState, vertical_slice_ticket: undefined }, "vertical-slice-ticket-required"],
+  ["parent ticket reference", { ...validTicketState, vertical_slice_ticket: { ref: "docs/.scratch/demo/parent-ticket.md", kind: "parent-ticket", role: "ready-for-agent" } }, "parent-ticket-forbidden"],
+  ["human-ready slice", { ...validTicketState, vertical_slice_ticket: { ...validTicketState.vertical_slice_ticket, role: "ready-for-human" } }, "ticket-not-ready-for-agent"],
+  ["uncompleted decomposition", { ...validTicketState, ticket_decomposition_result: { result: "blocked", evidence_refs: [] } }, "ticket-decomposition-incomplete"],
+  ["needs-human decomposition", { ...validTicketState, ticket_decomposition_result: { result: "needs-human", evidence_refs: [] } }, "ticket-decomposition-incomplete"],
+  ["unreadable decomposition evidence", { ...validTicketState, ticket_decomposition_result: { ...validTicketState.ticket_decomposition_result, evidence_refs: ["docs/.scratch/demo/missing-evidence.md"] } }, "ticket-formalization-evidence-missing"],
+  ["wrong slice kind", { ...validTicketState, vertical_slice_ticket: { ...validTicketState.vertical_slice_ticket, kind: "parent-ticket" }, vertical_slice_ticket_kind: "parent-ticket" }, "parent-ticket-forbidden"],
+  ["unapproved contract", { ...validTicketState, slice_contract: { ...validTicketState.slice_contract, status: "draft" } }, "slice-contract-not-approved"],
+  ["unpersisted contract", { ...validTicketState, slice_contract: { ...validTicketState.slice_contract, persisted: false } }, "slice-contract-not-persisted"],
+  ["stale formalization", { ...validTicketState, stale: true }, "ticket-formalization-stale"],
+  ["wrong implementation predecessor", { ...validTicketState, predecessor_work_unit: "work-unit.spec-synthesis" }, "invalid-implementation-predecessor"],
+  ["contract bound to another ticket", { ...validTicketState, slice_contract: { ...validTicketState.slice_contract, ticket_ref: "docs/.scratch/demo/issues/02-other.md" } }, "slice-contract-ticket-mismatch"],
+  ["unreadable slice", { ...validTicketState, vertical_slice_ticket: { ...validTicketState.vertical_slice_ticket, ref: "docs/.scratch/demo/issues/03-missing.md" } }, "vertical-slice-ticket-unreadable"],
+];
+
+for (const [name, state, signal] of cases) {
+  const result = validateImplementationEntry(state, options);
+  assert.equal(result.result, "blocked", name);
+  assert.ok(result.blocking_signals.includes(signal), `${name}: missing ${signal}`);
+}
+
+const parentOnly = validateTicketFormalization({
+  ...validTicketState,
+  vertical_slice_ticket: { ref: "docs/.scratch/demo/parent-ticket.md", kind: "parent-ticket", role: "ready-for-human" },
+}, options);
+assert.equal(parentOnly.result, "blocked");
+
+assert.equal(validateNextRoute("work-unit.ticket-decomposition", "work-unit.slice-implementation").result, "allowed");
+for (const current of ["work-unit.spec-synthesis", "work-unit.prototype-design", "work-unit.technical-analysis"]) {
+  const result = validateNextRoute(current, "work-unit.slice-implementation");
+  assert.equal(result.result, "blocked", current);
+  assert.ok(result.blocking_signals.includes("ticket-formalization-required"), current);
+}
+assert.equal(validateNextRoute("work-unit.spec-synthesis", "work-unit.ticket-decomposition").result, "allowed");
+assert.equal(validateNextRoute("work-unit.intensity-aware-verification", "work-unit.intensity-aware-review").result, "allowed");
+assert.equal(validateNextRoute("work-unit.release-and-rollback", null).result, "allowed");
+const arbitraryReadable = validateTicketFormalization({
+  ...validTicketState,
+  ticket_decomposition_result_ref: "docs/process/lifecycle-registry.yaml",
+  ticket_decomposition_result: { result: "completed", evidence_refs: ["docs/process/lifecycle-registry.yaml"] },
+}, options);
+assert.equal(arbitraryReadable.result, "blocked");
+assert.ok(arbitraryReadable.blocking_signals.includes("ticket-decomposition-incomplete"));
+assert.equal(validateTicketFormalization({
+  ...validTicketState,
+  tracker_kind: "github",
+  ticket_decomposition_result_ref: "https://github.com/example/project/issues/1",
+  ticket_decomposition_result: { result: "completed", evidence_refs: ["https://github.com/example/project/issues/1"] },
+  vertical_slice_ticket_ref: "https://github.com/example/project/issues/1",
+  vertical_slice_ticket: { ref: "https://github.com/example/project/issues/1", kind: "vertical-slice-ticket", role: "ready-for-agent" },
+  slice_contract: { ...validTicketState.slice_contract, ticket_ref: "https://github.com/example/project/issues/1" },
+}, { ...options, exists: (ref) => ref === "https://github.com/example/project/issues/1", read: (ref) => ref === "https://github.com/example/project/issues/1" ? decompositionResult.replace("docs/.scratch/demo/evidence/ticket-decomposition-result.yaml", "https://github.com/example/project/issues/1") : "" }).result, "allowed");
+
+process.stdout.write("生命周期转换压力场景验证通过\n");

package/template/scripts/verify-subagent-task-package

@@ -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-digital-human-task-package"), ...process.argv.slice(2)], { stdio: "inherit" });
+process.exitCode = result.status ?? 1;