create-yss-spec 2.2.2 → 2.2.4

package/template/scripts/lib/digital-human-roles.mjs

@@ -0,0 +1,398 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parseDocument } from "../vendor/yaml.mjs";
+import { loadRegistry, ROOT } from "./lifecycle-registry.mjs";
+import { loadSkillRegistry } from "./skill-registry.mjs";
+
+export const DEFAULT_DIGITAL_HUMAN_ROLES = path.join(ROOT, "docs/agents/digital-human-roles.yaml");
+
+const ROLE_ID = /^role\.[a-z0-9][a-z0-9-]*$/;
+const GROUP_ID = /^group\.[a-z0-9][a-z0-9-]*$/;
+const RUNTIME_ID = /^runtime\.[a-z0-9][a-z0-9-]*$/;
+const REQUIRED_ROLES = [
+  "role.requirements-manager",
+  "role.product-manager",
+  "role.business",
+  "role.project-manager",
+  "role.frontend-engineer",
+  "role.backend-engineer",
+  "role.test-engineer"
+];
+const REQUIRED_RUNTIMES = ["runtime.generic", "runtime.skill-projection", "runtime.grok"];
+const REQUIRED_DUAL_HAT_SPLIT = ["cross-repo-load", "responsibility-conflict"];
+const STRING_GATE_BUCKETS = [
+  "evidence_only",
+  "orchestrator",
+  "product_digital_human_with_biological_veto",
+  "biological_human"
+];
+const COUNTERSIGN_STRING_BUCKETS = ["product_digital_human_with_biological_veto", "biological_human"];
+export const BIOLOGICAL_ROLE_ID = "role.biological-human";
+const OVERFLOWS = new Set(["not-applicable", "one-to-one-handoff", "forbid"]);
+const GROK_FIELDS = ["grok_title", "grok_description", "grok_default_dual_hat", "grok_runtime_root", "grok_platform_approval"];
+
+function fail(message) {
+  throw new TypeError(message);
+}
+
+function yamlFromFile(filePath, label) {
+  let source;
+  try {
+    source = readFileSync(filePath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") fail(`缺少${label}: ${filePath}`);
+    throw error;
+  }
+  const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length > 0) fail(`无法解析${label}: ${document.errors[0].message}`);
+  const value = document.toJS({ maxAliasCount: 0 });
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(`${label}必须是对象`);
+  return value;
+}
+
+function requireString(value, field) {
+  if (typeof value !== "string" || !value.trim()) fail(`${field} 不能为空`);
+}
+
+function requireStringArray(value, field) {
+  if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== "string" || !item.trim())) {
+    fail(`${field} 必须是非空字符串数组`);
+  }
+  if (new Set(value).size !== value.length) fail(`${field} 包含重复项`);
+}
+
+function idsFromCollection(records, kind) {
+  if (!Array.isArray(records)) fail(`生命周期注册表缺少 ${kind}`);
+  return new Set(records.map((record) => record.id));
+}
+
+export function skillIdsFromRegistry(skillRegistry) {
+  const ids = new Set();
+  for (const collection of ["skills", "platform_skills", "external_skills"]) {
+    const records = skillRegistry[collection];
+    if (!records) continue;
+    if (!Array.isArray(records)) fail(`技能注册表 ${collection} 必须是数组`);
+    for (const record of records) {
+      if (!record?.id) fail(`技能注册表 ${collection} 缺少 id`);
+      ids.add(record.id);
+    }
+  }
+  return ids;
+}
+
+function rejectGrokCoupling(object, label) {
+  if (!object || typeof object !== "object") return;
+  for (const field of GROK_FIELDS) {
+    if (Object.hasOwn(object, field)) fail(`${label} 不得包含平台耦合字段 ${field}`);
+  }
+}
+
+function knownActorIds(doc) {
+  return new Set([doc.orchestrator.id, ...doc.roles.map((role) => role.id)]);
+}
+
+function validateSkills(list, field, skillIds) {
+  requireStringArray(list, field);
+  for (const skill of list) {
+    if (!skillIds.has(skill)) fail(`${field} 引用了未登记技能: ${skill}`);
+  }
+}
+
+function validateActor(actor, { skillIds, stageIds, artifactIds, evidenceIds, expectedKind }) {
+  rejectGrokCoupling(actor, actor?.id || expectedKind);
+  requireString(actor.id, `${expectedKind}.id`);
+  if (!ROLE_ID.test(actor.id)) fail(`${actor.id} 不符合 role.*`);
+  requireString(actor.name, `${actor.id}.name`);
+  if (actor.kind !== expectedKind) fail(`${actor.id}.kind 必须为 ${expectedKind}`);
+  requireString(actor.title, `${actor.id}.title`);
+  requireString(actor.description, `${actor.id}.description`);
+  requireStringArray(actor.stages, `${actor.id}.stages`);
+  for (const stage of actor.stages) {
+    if (!stageIds.has(stage)) fail(`${actor.id} 引用了未知阶段: ${stage}`);
+  }
+  if (actor.draft_artifact_ids) {
+    requireStringArray(actor.draft_artifact_ids, `${actor.id}.draft_artifact_ids`);
+    for (const artifact of actor.draft_artifact_ids) {
+      if (!artifactIds.has(artifact)) fail(`${actor.id} 引用了未知产物: ${artifact}`);
+    }
+  }
+  if (actor.owned_evidence_ids) {
+    requireStringArray(actor.owned_evidence_ids, `${actor.id}.owned_evidence_ids`);
+    for (const evidence of actor.owned_evidence_ids) {
+      if (!evidenceIds || !evidenceIds.has(evidence)) fail(`${actor.id} 引用了未知证据: ${evidence}`);
+    }
+  }
+  validateSkills(actor.core_skills, `${actor.id}.core_skills`, skillIds);
+  validateSkills(actor.forbidden_skills, `${actor.id}.forbidden_skills`, skillIds);
+  const overlap = actor.core_skills.filter((skill) => actor.forbidden_skills.includes(skill));
+  if (overlap.length > 0) fail(`${actor.id} 的 core_skills 与 forbidden_skills 重叠: ${overlap.join(", ")}`);
+}
+
+function validateRuntimes(doc, skillRegistry, groupSizes) {
+  if (!Array.isArray(doc.runtimes) || doc.runtimes.length === 0) fail("缺少 runtimes");
+  const ids = [];
+  let sawProjection = false;
+  for (const runtime of doc.runtimes) {
+    requireString(runtime.id, "runtimes.id");
+    if (!RUNTIME_ID.test(runtime.id)) fail(`${runtime.id} 不符合 runtime.*`);
+    ids.push(runtime.id);
+    requireString(runtime.kind, `${runtime.id}.kind`);
+    requireString(runtime.instance_kind, `${runtime.id}.instance_kind`);
+    requireString(runtime.collaboration, `${runtime.id}.collaboration`);
+    requireString(runtime.side_effect_approval, `${runtime.id}.side_effect_approval`);
+    if (runtime.side_effect_approval !== "biological-human") {
+      fail(`${runtime.id}.side_effect_approval 必须为 biological-human`);
+    }
+    if (!OVERFLOWS.has(runtime.overflow)) fail(`${runtime.id}.overflow 无效`);
+    if (typeof runtime.covers_skill_registry_roots !== "boolean") {
+      fail(`${runtime.id}.covers_skill_registry_roots 必须是布尔值`);
+    }
+    if (runtime.covers_skill_registry_roots) sawProjection = true;
+    const max = runtime.max_collaboration_group_size;
+    if (max == null) {
+      if (runtime.overflow !== "not-applicable") fail(`${runtime.id} 无人数上限时 overflow 必须为 not-applicable`);
+    } else {
+      if (!Number.isInteger(max) || max < 2) fail(`${runtime.id}.max_collaboration_group_size 必须是 >=2 的整数`);
+      if (runtime.overflow === "not-applicable") fail(`${runtime.id} 有人数上限时必须声明 overflow`);
+      if (runtime.overflow === "forbid") {
+        for (const [groupId, size] of groupSizes) {
+          if (size > max) fail(`${runtime.id} 禁止超过 ${max} 人的阶段协作组: ${groupId} 有 ${size} 人`);
+        }
+      }
+    }
+    if (runtime.id === "runtime.grok") {
+      if (runtime.kind !== "grok-bot") fail("runtime.grok.kind 必须为 grok-bot");
+      if (runtime.max_collaboration_group_size !== 6) fail("runtime.grok 群聊上限必须为 6");
+      if (runtime.shared_workspace_is_not_security_boundary !== true) {
+        fail("runtime.grok 必须声明共享工作区不是安全边界");
+      }
+    }
+    if (runtime.id === "runtime.generic" && runtime.max_collaboration_group_size != null) {
+      fail("runtime.generic 不得设置平台群聊上限");
+    }
+  }
+  if (new Set(ids).size !== ids.length) fail("runtimes.id 重复");
+  for (const required of REQUIRED_RUNTIMES) {
+    if (!ids.includes(required)) fail(`缺少运行时绑定: ${required}`);
+  }
+  if (!sawProjection) fail("必须有 covers_skill_registry_roots=true 的运行时，以覆盖技能注册表投影根");
+  const roots = skillRegistry.agent_runtime_roots;
+  if (!roots || typeof roots !== "object") fail("技能注册表缺少 agent_runtime_roots");
+}
+
+function validateSignRule(rule, { actors, gateIds, claimed, field }) {
+  if (!rule || typeof rule !== "object") fail(`${field} 必须是对象`);
+  requireString(rule.gate, `${field}.gate`);
+  if (!gateIds.has(rule.gate)) fail(`${field} 引用了未知门禁: ${rule.gate}`);
+  if (claimed.has(rule.gate)) fail(`门禁被多个会签桶重复占用: ${rule.gate}`);
+  claimed.add(rule.gate);
+  if (rule.drafter != null) {
+    requireString(rule.drafter, `${rule.gate}.drafter`);
+    if (!actors.has(rule.drafter)) fail(`${rule.gate} 起草者未知: ${rule.drafter}`);
+  }
+  requireStringArray(rule.countersigners, `${rule.gate}.countersigners`);
+  if (rule.drafter && rule.countersigners.includes(rule.drafter)) fail(`${rule.gate} 起草者不得会签自己`);
+  for (const signer of rule.countersigners) {
+    if (!actors.has(signer)) fail(`${rule.gate} 会签人未知: ${signer}`);
+  }
+}
+
+export function collectCountersignGateIds(policy) {
+  const ids = [];
+  for (const bucket of COUNTERSIGN_STRING_BUCKETS) {
+    const gates = policy?.[bucket];
+    if (Array.isArray(gates)) ids.push(...gates);
+  }
+  for (const rule of policy?.digital_human_review || []) {
+    if (rule?.gate) ids.push(rule.gate);
+  }
+  for (const rule of policy?.dual_digital_human || []) {
+    if (rule?.gate) ids.push(rule.gate);
+  }
+  return ids;
+}
+
+export function countersignRuleForGate(policy, gateId) {
+  const dual = (policy?.dual_digital_human || []).find((rule) => rule.gate === gateId);
+  if (dual) return { bucket: "dual_digital_human", ...dual };
+  const review = (policy?.digital_human_review || []).find((rule) => rule.gate === gateId);
+  if (review) return { bucket: "digital_human_review", ...review };
+  if ((policy?.product_digital_human_with_biological_veto || []).includes(gateId)) {
+    return { bucket: "product_digital_human_with_biological_veto", gate: gateId, countersigners: ["role.product-manager"] };
+  }
+  if ((policy?.biological_human || []).includes(gateId)) {
+    return { bucket: "biological_human", gate: gateId, countersigners: [BIOLOGICAL_ROLE_ID] };
+  }
+  return null;
+}
+
+export function taskPackageDefaults(roleId, doc) {
+  const registry = doc || loadDigitalHumanRoles();
+  const actor = roleId === registry.orchestrator.id
+    ? registry.orchestrator
+    : registry.roles.find((role) => role.id === roleId);
+  if (!actor) fail(`未知角色: ${roleId}`);
+  return {
+    role_id: actor.id,
+    kind: actor.kind,
+    stages: [...actor.stages],
+    core_skills: [...actor.core_skills],
+    forbidden_skills: [...actor.forbidden_skills],
+    draft_artifact_ids: actor.draft_artifact_ids ? [...actor.draft_artifact_ids] : [],
+    owned_evidence_ids: actor.owned_evidence_ids ? [...actor.owned_evidence_ids] : []
+  };
+}
+
+export function validateDigitalHumanRoles(doc, { skillIds, stageIds, gateIds, artifactIds, evidenceIds, workUnitIds, skillRegistry } = {}) {
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) fail("数字人角色注册表必须是对象");
+  if (doc.schema_version !== 1) fail("schema_version 必须为 1");
+  if (doc.registry_id !== "yss.digital-human-roles") fail("registry_id 必须为 yss.digital-human-roles");
+  if (doc.status !== "active") fail("status 必须为 active");
+  requireString(doc.description, "description");
+  if (doc.canonical_path !== "docs/agents/digital-human-roles.yaml") fail("canonical_path 必须为 docs/agents/digital-human-roles.yaml");
+  rejectGrokCoupling(doc.runtime_policy, "runtime_policy");
+  rejectGrokCoupling(doc.gate_policy, "gate_policy");
+  const runtime = doc.runtime_policy;
+  if (!runtime || typeof runtime !== "object") fail("缺少 runtime_policy");
+  if (runtime.overlay_on_lifecycle !== true) fail("runtime_policy.overlay_on_lifecycle 必须为 true");
+  if (runtime.git_is_ssot !== true) fail("runtime_policy.git_is_ssot 必须为 true");
+  if (runtime.default_invocation !== "orchestrator") fail("default_invocation 必须为 orchestrator");
+  if (runtime.dispatch !== "orchestrator-one-to-one") fail("dispatch 必须为 orchestrator-one-to-one");
+  if (runtime.per_feature_instances !== "forbidden") fail("per_feature_instances 必须为 forbidden");
+  if (runtime.implementer_must_differ !== true) fail("implementer_must_differ 必须为 true");
+  if (runtime.biological_veto !== true) fail("biological_veto 必须为 true");
+  if (runtime.write_isolation !== "task-package-policy") fail("write_isolation 必须为 task-package-policy");
+  requireStringArray(runtime.dual_hat_split_when, "runtime_policy.dual_hat_split_when");
+  for (const required of REQUIRED_DUAL_HAT_SPLIT) {
+    if (!runtime.dual_hat_split_when.includes(required)) {
+      fail(`runtime_policy.dual_hat_split_when 必须包含 ${required}`);
+    }
+  }
+  if (runtime.max_group_size != null || runtime.min_group_size != null) {
+    fail("平台群聊人数上限属于 runtimes，不得写在 runtime_policy");
+  }
+
+  const orchestrator = doc.orchestrator;
+  if (!orchestrator || typeof orchestrator !== "object") fail("缺少 orchestrator");
+  validateActor(orchestrator, { skillIds, stageIds, artifactIds, evidenceIds, expectedKind: "orchestrator" });
+  requireStringArray(orchestrator.default_dual_hat, "orchestrator.default_dual_hat");
+  if (!Array.isArray(doc.roles) || doc.roles.length === 0) fail("roles 不能为空");
+  const roleIds = [];
+  for (const role of doc.roles) {
+    validateActor(role, { skillIds, stageIds, artifactIds, evidenceIds, expectedKind: "digital-human" });
+    roleIds.push(role.id);
+  }
+  if (new Set(roleIds).size !== roleIds.length) fail("roles.id 重复");
+  if (roleIds.slice().sort().join("\0") !== REQUIRED_ROLES.slice().sort().join("\0")) {
+    fail(`v1 必须恰好包含: ${REQUIRED_ROLES.join(", ")}`);
+  }
+  if (roleIds.includes(orchestrator.id)) fail("orchestrator 不得再出现在 roles");
+  for (const dual of orchestrator.default_dual_hat) {
+    if (!roleIds.includes(dual)) fail(`default_dual_hat 引用了未知角色: ${dual}`);
+  }
+
+  const actors = knownActorIds(doc);
+  if (!Array.isArray(doc.stage_groups) || doc.stage_groups.length === 0) fail("缺少 stage_groups");
+  const groupIds = [];
+  const groupSizes = [];
+  for (const group of doc.stage_groups) {
+    requireString(group.id, "stage_groups.id");
+    if (!GROUP_ID.test(group.id)) fail(`${group.id} 不符合 group.*`);
+    groupIds.push(group.id);
+    requireString(group.name, `${group.id}.name`);
+    if (!stageIds.has(group.stage)) fail(`${group.id} 引用了未知阶段: ${group.stage}`);
+    requireStringArray(group.members, `${group.id}.members`);
+    if (group.members.length < 2) fail(`${group.id} 逻辑协作组至少 2 人`);
+    groupSizes.push([group.id, group.members.length]);
+    for (const member of group.members) {
+      if (!actors.has(member)) fail(`${group.id} 包含未知成员: ${member}`);
+    }
+  }
+  if (new Set(groupIds).size !== groupIds.length) fail("stage_groups.id 重复");
+  validateRuntimes(doc, skillRegistry, groupSizes);
+
+  const policy = doc.gate_policy;
+  if (!policy || typeof policy !== "object") fail("缺少 gate_policy");
+  if (policy.default_if_unlisted !== "biological-human") fail("default_if_unlisted 必须为 biological-human");
+  if (policy.runtime_side_effect_approval !== "biological-human") fail("runtime_side_effect_approval 必须为 biological-human");
+  if (policy.commercial_contract !== "biological-human") fail("commercial_contract 必须为 biological-human");
+  if (policy.unlisted_kept_biological) {
+    requireStringArray(policy.unlisted_kept_biological, "gate_policy.unlisted_kept_biological");
+    for (const gate of policy.unlisted_kept_biological) {
+      if (!gateIds.has(gate)) fail(`unlisted_kept_biological 引用了未知门禁: ${gate}`);
+    }
+  }
+  const claimed = new Set();
+  for (const bucket of STRING_GATE_BUCKETS) {
+    requireStringArray(policy[bucket], `gate_policy.${bucket}`);
+    for (const gate of policy[bucket]) {
+      if (!gateIds.has(gate)) fail(`gate_policy.${bucket} 引用了未知门禁: ${gate}`);
+      if (claimed.has(gate)) fail(`门禁被多个会签桶重复占用: ${gate}`);
+      claimed.add(gate);
+    }
+  }
+  if (!Array.isArray(policy.digital_human_review) || policy.digital_human_review.length === 0) {
+    fail("缺少 digital_human_review");
+  }
+  for (const [index, rule] of policy.digital_human_review.entries()) {
+    if (typeof rule === "string") fail("digital_human_review 必须是含 gate 与 countersigners 的规则");
+    validateSignRule(rule, { actors, gateIds, claimed, field: `digital_human_review[${index}]` });
+    if (rule.gate === "gate.release-ready") fail("gate.release-ready 不得放入 digital_human_review");
+  }
+  if (!policy.biological_human.includes("gate.release-ready")) {
+    fail("gate.release-ready 必须属于 biological_human");
+  }
+  if (!Array.isArray(policy.digital_human_review_work_units) || policy.digital_human_review_work_units.length === 0) {
+    fail("缺少 digital_human_review_work_units");
+  }
+  const workUnitSeen = new Set();
+  for (const [index, rule] of policy.digital_human_review_work_units.entries()) {
+    if (typeof rule === "string") fail("digital_human_review_work_units 必须是含 work_unit 与 countersigners 的规则");
+    requireString(rule.work_unit, `digital_human_review_work_units[${index}].work_unit`);
+    if (!workUnitIds.has(rule.work_unit)) fail(`未知工作单元: ${rule.work_unit}`);
+    if (workUnitSeen.has(rule.work_unit)) fail(`工作单元重复: ${rule.work_unit}`);
+    workUnitSeen.add(rule.work_unit);
+    requireStringArray(rule.countersigners, `${rule.work_unit}.countersigners`);
+    for (const signer of rule.countersigners) {
+      if (!actors.has(signer)) fail(`${rule.work_unit} 会签人未知: ${signer}`);
+    }
+    if (rule.implementer_must_differ !== true) {
+      fail(`${rule.work_unit}.implementer_must_differ 必须为 true`);
+    }
+  }
+  if (!Array.isArray(policy.dual_digital_human) || policy.dual_digital_human.length === 0) {
+    fail("缺少 dual_digital_human");
+  }
+  for (const [index, rule] of policy.dual_digital_human.entries()) {
+    validateSignRule(rule, { actors, gateIds, claimed, field: `dual_digital_human[${index}]` });
+    if (!rule.drafter) fail(`${rule.gate} 双数字人会签必须有 drafter`);
+  }
+  for (const gate of policy.unlisted_kept_biological || []) {
+    if (claimed.has(gate)) fail(`unlisted_kept_biological 与会签桶重复: ${gate}`);
+  }
+
+  return {
+    role_count: doc.roles.length,
+    group_count: doc.stage_groups.length,
+    runtime_count: doc.runtimes.length,
+    claimed_gates: claimed.size
+  };
+}
+
+export function loadDigitalHumanRoles(filePath = DEFAULT_DIGITAL_HUMAN_ROLES) {
+  return yamlFromFile(filePath, "数字人角色注册表");
+}
+
+export function validateDefaultDigitalHumanRoles() {
+  const lifecycle = loadRegistry();
+  const skills = loadSkillRegistry();
+  return validateDigitalHumanRoles(loadDigitalHumanRoles(), {
+    skillIds: skillIdsFromRegistry(skills),
+    stageIds: idsFromCollection(lifecycle.stages, "stages"),
+    gateIds: idsFromCollection(lifecycle.gates, "gates"),
+    artifactIds: idsFromCollection(lifecycle.artifacts, "artifacts"),
+    evidenceIds: idsFromCollection(lifecycle.evidence, "evidence"),
+    workUnitIds: idsFromCollection(lifecycle.work_units, "work_units"),
+    skillRegistry: skills
+  });
+}

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,
+});