create-yss-spec 2.2.3 → 2.2.5

package/template/scripts/lib/lifecycle-transition.mjs

@@ -0,0 +1,259 @@
+import { existsSync, readFileSync } from "node:fs";
+import { parseDocument } from "../vendor/yaml.mjs";
+
+const IMPLEMENTATION_WORK_UNIT = "work-unit.slice-implementation";
+const TICKET_DECOMPOSITION_WORK_UNIT = "work-unit.ticket-decomposition";
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const child of Object.values(value)) deepFreeze(child);
+  return value;
+}
+
+const NEXT_ROUTES = deepFreeze({
+  "work-unit.entry-triage": ["work-unit.discovery-opportunity", "work-unit.discovery-requirements"],
+  "work-unit.ssot-update": ["work-unit.skill-projection-sync", "work-unit.intensity-aware-verification"],
+  "work-unit.skill-projection-sync": ["work-unit.template-snapshot-build", "work-unit.intensity-aware-verification"],
+  "work-unit.template-snapshot-build": ["work-unit.attach-sync-integration", "work-unit.intensity-aware-verification"],
+  "work-unit.attach-sync-integration": ["work-unit.intensity-aware-verification"],
+  "work-unit.intensity-aware-verification": ["work-unit.intensity-aware-review"],
+  "work-unit.intensity-aware-review": ["work-unit.release-and-rollback"],
+  "work-unit.release-and-rollback": [],
+  "work-unit.discovery-opportunity": ["work-unit.discovery-requirements", "work-unit.domain-strategy-design", "work-unit.stage-decision", "work-unit.spec-synthesis"],
+  "work-unit.discovery-requirements": ["work-unit.domain-strategy-design", "work-unit.stage-decision", "work-unit.spec-synthesis"],
+  "work-unit.domain-strategy-design": ["work-unit.stage-decision", "work-unit.spec-synthesis"],
+  "work-unit.stage-decision": ["work-unit.spec-synthesis"],
+  "work-unit.spec-synthesis": ["work-unit.prototype-design", "work-unit.technical-analysis", TICKET_DECOMPOSITION_WORK_UNIT],
+  "work-unit.prototype-design": ["work-unit.technical-analysis", TICKET_DECOMPOSITION_WORK_UNIT],
+  "work-unit.technical-analysis": [TICKET_DECOMPOSITION_WORK_UNIT],
+  [TICKET_DECOMPOSITION_WORK_UNIT]: [IMPLEMENTATION_WORK_UNIT],
+  [IMPLEMENTATION_WORK_UNIT]: ["work-unit.frontend-implementation-verification", "work-unit.code-review"],
+  "work-unit.frontend-implementation-verification": ["work-unit.code-review"],
+  "work-unit.code-review": ["work-unit.release-and-retrospective", IMPLEMENTATION_WORK_UNIT],
+  "work-unit.release-and-retrospective": [],
+});
+
+const BLOCKING_SIGNALS = Object.freeze({
+  invalidRoute: "illegal-next-route",
+  implementationBeforeTickets: "ticket-formalization-required",
+  invalidPredecessor: "invalid-implementation-predecessor",
+  decompositionIncomplete: "ticket-decomposition-incomplete",
+  decompositionRefMissing: "ticket-decomposition-result-ref-missing",
+  missingSlice: "vertical-slice-ticket-required",
+  sliceRefMissing: "vertical-slice-ticket-ref-missing",
+  parentTicket: "parent-ticket-forbidden",
+  wrongKind: "vertical-slice-ticket-kind-invalid",
+  kindMissing: "vertical-slice-ticket-kind-missing",
+  unreadableSlice: "vertical-slice-ticket-unreadable",
+  wrongRole: "ticket-not-ready-for-agent",
+  roleMissing: "vertical-slice-ticket-role-missing",
+  contractMismatch: "slice-contract-ticket-mismatch",
+  contractNotApproved: "slice-contract-not-approved",
+  contractNotPersisted: "slice-contract-not-persisted",
+  contractNotCurrent: "slice-contract-not-current",
+  missingEvidence: "ticket-formalization-evidence-missing",
+  stale: "ticket-formalization-stale",
+});
+
+const allowedResult = (evidenceRefs = []) => ({
+  result: "allowed",
+  blocking_signals: [],
+  missing_requirements: [],
+  evidence_refs: evidenceRefs,
+  next_work_unit: null,
+});
+
+const blockedResult = (signals, missing = [], evidenceRefs = []) => ({
+  result: "blocked",
+  blocking_signals: [...new Set(signals)],
+  missing_requirements: [...new Set(missing)],
+  evidence_refs: evidenceRefs,
+  next_work_unit: null,
+});
+
+function hasText(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function isReadable(ref, exists) {
+  return hasText(ref) && exists(ref);
+}
+
+function readDecompositionResult(ref, read) {
+  if (!hasText(ref)) return null;
+  try {
+    const document = parseDocument(read(ref), { maxAliasCount: 0, uniqueKeys: true });
+    if (document.errors.length > 0) return null;
+    const value = document.toJS({ maxAliasCount: 0 });
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function validateTicketPath(ref) {
+  if (!hasText(ref)) return false;
+  return /^docs\/\.scratch\/[^/]+\/issues\/[^/]+\.md$/.test(ref);
+}
+
+function validateTicketReference(ref, trackerKind) {
+  if (trackerKind === "github" || trackerKind === "gitlab") {
+    return /^(https?:\/\/|(?:github|gitlab):)[^\s]+$/.test(ref);
+  }
+  return validateTicketPath(ref);
+}
+
+/**
+ * Validate a lifecycle work-unit transition without mutating state.
+ * `nextRoute` is null only for a terminal work unit. A blocked or needs-human
+ * Workflow Execution Result may omit a route; completed results are checked
+ * by `validateWorkflowExecutionResult` before this function is called.
+ */
+export function validateNextRoute(currentWorkUnit, nextRoute) {
+  const routes = NEXT_ROUTES[currentWorkUnit];
+  if (!routes) return blockedResult([BLOCKING_SIGNALS.invalidRoute], ["known_current_work_unit"]);
+  if (nextRoute === null && routes.length === 0) return allowedResult();
+  if (!hasText(nextRoute) || !routes.includes(nextRoute)) {
+    const signals = [BLOCKING_SIGNALS.invalidRoute];
+    if (nextRoute === IMPLEMENTATION_WORK_UNIT && currentWorkUnit !== TICKET_DECOMPOSITION_WORK_UNIT) {
+      signals.push(BLOCKING_SIGNALS.implementationBeforeTickets);
+    }
+    return blockedResult(signals, ["allowed_next_route"]);
+  }
+  return allowedResult();
+}
+
+/**
+ * Validate that Ticket formalization produced a real, implementable vertical slice.
+ * `exists` is injectable so external adapters can resolve their own tracker refs.
+ */
+export function validateTicketFormalization(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8") } = {}) {
+  const decomposition = state?.ticket_decomposition_result;
+  const ticket = state?.vertical_slice_ticket;
+  const contract = state?.slice_contract;
+  const decompositionRef = state?.ticket_decomposition_result_ref;
+  const sliceRef = state?.vertical_slice_ticket_ref;
+  const sliceRole = state?.vertical_slice_ticket_role;
+  const sliceKind = state?.vertical_slice_ticket_kind;
+  const trackerKind = state?.tracker_kind ?? "local-markdown";
+  const evidenceRefs = decomposition?.evidence_refs ?? [];
+  const persistedDecomposition = readDecompositionResult(decompositionRef, read);
+  const signals = [];
+  const missing = [];
+
+  if (decomposition?.result !== "completed") {
+    signals.push(BLOCKING_SIGNALS.decompositionIncomplete);
+    missing.push("ticket_decomposition_result.result=completed");
+  }
+  if (!persistedDecomposition || persistedDecomposition.result_schema !== "workflow-execution-result-v1" || persistedDecomposition.result !== "completed" || persistedDecomposition.work_unit !== TICKET_DECOMPOSITION_WORK_UNIT) {
+    signals.push(BLOCKING_SIGNALS.decompositionIncomplete);
+    missing.push("ticket_decomposition_result_ref must contain completed work-unit.ticket-decomposition result");
+  }
+  if (persistedDecomposition && Array.isArray(persistedDecomposition.evidence_refs)) {
+    if (persistedDecomposition.evidence_refs.some((ref) => !isReadable(ref, exists))) {
+      signals.push(BLOCKING_SIGNALS.missingEvidence);
+      missing.push("persisted decomposition result evidence_refs must be readable");
+    }
+  }
+  if (!isReadable(decompositionRef, exists) || !evidenceRefs.includes(decompositionRef)) {
+    signals.push(BLOCKING_SIGNALS.decompositionRefMissing);
+    missing.push("readable ticket_decomposition_result_ref included in evidence_refs");
+  }
+  if (!Array.isArray(evidenceRefs) || evidenceRefs.length === 0 || evidenceRefs.some((ref) => !isReadable(ref, exists))) {
+    signals.push(BLOCKING_SIGNALS.missingEvidence);
+    missing.push("readable ticket_decomposition_result.evidence_refs");
+  }
+  if (!hasText(sliceRef)) {
+    signals.push(BLOCKING_SIGNALS.sliceRefMissing);
+    missing.push("vertical_slice_ticket_ref");
+  }
+  if (!hasText(sliceKind)) {
+    signals.push(BLOCKING_SIGNALS.kindMissing);
+    missing.push("vertical_slice_ticket_kind");
+  }
+  if (!hasText(sliceRole)) {
+    signals.push(BLOCKING_SIGNALS.roleMissing);
+    missing.push("vertical_slice_ticket_role");
+  }
+  if (!ticket || !hasText(ticket.ref)) {
+    signals.push(BLOCKING_SIGNALS.missingSlice);
+    missing.push("vertical_slice_ticket.ref");
+  } else {
+    if (sliceRef !== ticket.ref) {
+      signals.push(BLOCKING_SIGNALS.contractMismatch);
+      missing.push("vertical_slice_ticket_ref=vertical_slice_ticket.ref");
+    }
+    if (sliceKind !== ticket.kind) {
+      signals.push(BLOCKING_SIGNALS.wrongKind);
+      missing.push("vertical_slice_ticket_kind=vertical_slice_ticket.kind");
+    }
+    if (sliceRole !== ticket.role) {
+      signals.push(BLOCKING_SIGNALS.wrongRole);
+      missing.push("vertical_slice_ticket_role=vertical_slice_ticket.role");
+    }
+    if (!validateTicketReference(ticket.ref, trackerKind)) {
+      signals.push(ticket.kind === "parent-ticket" || ticket.ref.endsWith("/parent-ticket.md") ? BLOCKING_SIGNALS.parentTicket : BLOCKING_SIGNALS.missingSlice);
+      missing.push(trackerKind === "local-markdown" ? "vertical_slice_ticket.ref under docs/.scratch/<feature>/issues/" : "remote tracker Ticket reference");
+    }
+    if (ticket.kind === "parent-ticket" || ticket.ref.endsWith("/parent-ticket.md")) {
+      signals.push(BLOCKING_SIGNALS.parentTicket);
+      missing.push("vertical_slice_ticket.kind=vertical-slice-ticket");
+    } else if (ticket.kind !== "vertical-slice-ticket") {
+      signals.push(BLOCKING_SIGNALS.wrongKind);
+      missing.push("vertical_slice_ticket.kind=vertical-slice-ticket");
+    }
+    if (ticket.role !== "ready-for-agent") {
+      signals.push(BLOCKING_SIGNALS.wrongRole);
+      missing.push("vertical_slice_ticket.role=ready-for-agent");
+    }
+    if (trackerKind === "local-markdown" && !isReadable(ticket.ref, exists)) {
+      signals.push(BLOCKING_SIGNALS.unreadableSlice);
+      missing.push("readable vertical_slice_ticket.ref");
+    }
+  }
+  if (!contract || !hasText(contract.ticket_ref) || contract.ticket_ref !== ticket?.ref) {
+    signals.push(BLOCKING_SIGNALS.contractMismatch);
+    missing.push("slice_contract.ticket_ref=vertical_slice_ticket.ref");
+  }
+  if (contract?.status !== "approved") {
+    signals.push(BLOCKING_SIGNALS.contractNotApproved);
+    missing.push("slice_contract.status=approved");
+  }
+  if (contract?.persisted !== true) {
+    signals.push(BLOCKING_SIGNALS.contractNotPersisted);
+    missing.push("slice_contract.persisted=true");
+  }
+  if (contract?.current_version !== true) {
+    signals.push(BLOCKING_SIGNALS.contractNotCurrent);
+    missing.push("slice_contract.current_version=true");
+  }
+  if (state?.stale === true || (Array.isArray(state?.stale_inputs) && state.stale_inputs.length > 0)) {
+    signals.push(BLOCKING_SIGNALS.stale);
+    missing.push("ticket formalization inputs are current");
+  }
+
+  return signals.length === 0 ? allowedResult(evidenceRefs) : blockedResult(signals, missing, evidenceRefs);
+}
+
+/**
+ * Validate the complete implementation entry seam after ready-for-agent promotion.
+ */
+export function validateImplementationEntry(state, options = {}) {
+  const ticketResult = validateTicketFormalization(state, options);
+  if (ticketResult.result === "blocked") return ticketResult;
+  if (state?.predecessor_work_unit !== TICKET_DECOMPOSITION_WORK_UNIT) {
+    return blockedResult([BLOCKING_SIGNALS.invalidPredecessor], ["predecessor_work_unit=work-unit.ticket-decomposition"], ticketResult.evidence_refs);
+  }
+  if (state?.ready_for_agent !== true) {
+    return blockedResult([BLOCKING_SIGNALS.wrongRole], ["ready_for_agent=true"], ticketResult.evidence_refs);
+  }
+  return ticketResult;
+}
+
+export const lifecycleTransitionContract = Object.freeze({
+  implementation_work_unit: IMPLEMENTATION_WORK_UNIT,
+  ticket_decomposition_work_unit: TICKET_DECOMPOSITION_WORK_UNIT,
+  next_routes: NEXT_ROUTES,
+  blocking_signals: BLOCKING_SIGNALS,
+});

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;