create-yss-spec 2.2.3 → 2.2.4

package/template/docs/process/lifecycle-registry-baseline.json

@@ -1,11 +1,12 @@
 {
   "schema_version": 1,
   "registry_id": "yss.lifecycle",
-  "semantic_sha256": "6c7251b7929c696d41e04218c927a0679d61bd38c7af0c21cde96ecdc2f7107f",
+  "semantic_sha256": "49ca553e83efb9cffae220d9e6fca434b1d27096126a640f8f8e172e048808df",
   "published_ids": [
     "artifact.architecture-review",
     "artifact.data-architecture",
     "artifact.discovery-record",
+    "artifact.domain-strategy",
     "artifact.engineering-baseline",
     "artifact.frontend-implementation-plan",
     "artifact.frontend-implementation-verification",
@@ -24,7 +25,9 @@
     "artifact.slice-implementation-contract",
     "artifact.spec",
     "artifact.spec-delta",
+    "artifact.stage-decision-package",
     "artifact.state-matrix",
+    "artifact.tactical-design",
     "artifact.vertical-slice-ticket",
     "evidence.antd-cli-validation",
     "evidence.approval-record",
@@ -32,6 +35,7 @@
     "evidence.checkpoint-and-rollback",
     "evidence.contract-approval",
     "evidence.design-review-result",
+    "evidence.domain-strategy-review",
     "evidence.fresh-verification",
     "evidence.frontend-implementation-verification",
     "evidence.impact-assessment",
@@ -40,9 +44,12 @@
     "evidence.prototype-confirmation",
     "evidence.prototype-review-result",
     "evidence.repository-identity-check",
+    "evidence.stage-decision-package",
+    "evidence.tactical-design-review",
     "evidence.yss-skill-execution-result",
     "gate.architecture-reviewed",
     "gate.design-reviewed",
+    "gate.domain-strategy-approved",
     "gate.engineering-baseline-accepted",
     "gate.frontend-implementation-verified",
     "gate.openapi-draft-reviewed",
@@ -54,6 +61,7 @@
     "gate.slice-contract-approved",
     "gate.slice-ready-for-agent",
     "gate.spec-baseline-approved",
+    "gate.stage-decision-package-approved",
     "gate.user-confirmation",
     "stage.discovery",
     "stage.entry-triage",
@@ -67,6 +75,7 @@
     "work-unit.code-review",
     "work-unit.discovery-opportunity",
     "work-unit.discovery-requirements",
+    "work-unit.domain-strategy-design",
     "work-unit.entry-triage",
     "work-unit.fresh-verification",
     "work-unit.independent-review",
@@ -80,6 +89,7 @@
     "work-unit.slice-implementation",
     "work-unit.spec-synthesis",
     "work-unit.ssot-update",
+    "work-unit.stage-decision",
     "work-unit.technical-analysis",
     "work-unit.ticket-decomposition",
     "work-unit.template-snapshot-build"

package/template/docs/process/lifecycle-registry.yaml

@@ -48,6 +48,15 @@ evidence:
   - id: evidence.impact-assessment
     name: 影响面分析记录
     description: 受影响仓库、资产、风险与最近可信阶段。
+  - id: evidence.domain-strategy-review
+    name: DDD 战略设计评审证据
+    description: 子域、限界上下文、统一语言、Context Map、场景和不变量的结构化评审结果。
+  - id: evidence.tactical-design-review
+    name: DDD 战术设计评审证据
+    description: 聚合、Entity、Value Object、不变量、状态机、一致性、Gateway 与 API 隔离的结构化评审结果。
+  - id: evidence.stage-decision-package
+    name: 阶段决策包验证证据
+    description: 阶段决策包的 Schema、引用、语义一致性、影响传播和下游消费验证结果。
   - id: evidence.maintenance-intensity-checkpoint
     name: 模板维护强度 checkpoint
     description: template-source 变更的 L1 / L2 / L3 分级、触发项、最低验证证据、review 模式和升级记录。
@@ -97,6 +106,17 @@ gates:
     stage: stage.entry-triage
     trigger: 每次进入流程。
     evidence: [evidence.repository-identity-check]
+  - id: gate.domain-strategy-approved
+    name: DDD 战略设计批准
+    stage: stage.discovery
+    trigger: 存在 DDD 战略设计影响或需要确定领域边界、统一语言和核心规则。
+    evidence: [evidence.domain-strategy-review, evidence.approval-record]
+  - id: gate.stage-decision-package-approved
+    name: 阶段决策包批准
+    stage: stage.discovery
+    trigger: Discovery 到 Spec 入口需要稳定的阶段决策合同。
+    evidence: [evidence.stage-decision-package, evidence.approval-record]
+    requires_gates: [gate.domain-strategy-approved]
   - id: gate.spec-baseline-approved
     name: Spec 基线批准
     stage: stage.spec-architecture
@@ -169,6 +189,14 @@ artifacts:
     name: 影响面分析
     stage: stage.entry-triage
     trigger: 每次变更。
+  - id: artifact.domain-strategy
+    name: DDD 战略设计
+    stage: stage.discovery
+    trigger: 新产品/模块、跨上下文功能、统一语言冲突、服务边界或核心规则变化。
+  - id: artifact.stage-decision-package
+    name: 阶段决策包
+    stage: stage.discovery
+    trigger: Discovery 到 Spec 入口需要结构化上游决策。
   - id: artifact.discovery-record
     name: Discovery 记录
     stage: stage.discovery
@@ -229,6 +257,10 @@ artifacts:
     name: 架构审查记录
     stage: stage.system-data-engineering
     trigger: 高风险或跨边界变化。
+  - id: artifact.tactical-design
+    name: DDD 战术设计
+    stage: stage.system-data-engineering
+    trigger: 聚合边界、状态机、一致性或持久化映射复杂到无法在系统概要设计的 Tactical DDD Check 中清楚表达。
   - id: artifact.spec-delta
     name: Spec Delta
     stage: stage.spec-architecture
@@ -319,6 +351,18 @@ work_units:
     input: 机会结论、用户反馈和领域词汇。
     output: 用户、MVP、非目标、成功标准、测试 seam 和未决项。
     completion: frontier 清空；用户确认；无 runnable blocker。
+  - id: work-unit.domain-strategy-design
+    name: DDD 战略设计
+    scope: project-instance
+    input: 已澄清的业务场景、领域词汇、约束和现有上下文。
+    output: 子域、限界上下文、Context Map、统一语言、事件、核心领域概念候选和不变量。
+    completion: 边界、语义方向、规则所有权和关键场景可审查；无未解释冲突。
+  - id: work-unit.stage-decision
+    name: 阶段决策包综合
+    scope: project-instance
+    input: Discovery、DDD 战略设计、产品和商务输入。
+    output: 带版本、digest、证据和下游映射的阶段决策包。
+    completion: 必填字段、引用、影响面和下游消费验证通过；批准门禁完成。
   - id: work-unit.spec-synthesis
     name: Spec 综合
     scope: project-instance
@@ -335,8 +379,8 @@ work_units:
     name: 技术分析与契约冻结
     scope: project-instance
     input: Spec、原型、API/数据/工程影响面。
-    output: OpenAPI、数据架构、工程基线、架构审查和 Slice 合同草案。
-    completion: 命中契约已冻结；无 API 影响有可读记录；工程基线通过。
+    output: OpenAPI、数据架构、Tactical DDD Check、工程基线、架构审查和 Slice 合同草案。
+    completion: 命中契约已冻结；无 API 影响有可读记录；命中领域影响时战术模型无未解释冲突；工程基线通过。
   - id: work-unit.ticket-decomposition
     name: 垂直切片 Ticket 正式化
     scope: project-instance

package/template/docs/process/schemas/digital-human-task-package.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.dev/schemas/digital-human-task-package.schema.json",
+  "title": "YSS Digital Human Task Package",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "task_id", "work_unit_id", "actor_id", "role_id", "runtime_id", "execution_state", "workflow_status", "skill_source", "contract", "inputs", "objective", "allowed_write_paths", "forbidden_actions", "expected_outputs", "expected_evidence_files", "verification_commands", "verification_results", "downstream_consumers", "convergence"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "task_id": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" },
+    "work_unit_id": { "type": "string", "minLength": 1, "pattern": "^work-unit\\.[a-z0-9][a-z0-9-]*$" },
+    "actor_id": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]*$" },
+    "role_id": { "type": "string", "pattern": "^role\\.[a-z0-9][a-z0-9-]*$" },
+    "runtime_id": { "type": "string", "pattern": "^runtime\\.[a-z0-9][a-z0-9-]*$" },
+    "execution_state": { "enum": ["Explorer", "Drafter", "Worker", "Reviewer", "Verifier"] },
+    "workflow_status": { "enum": ["not-started", "active", "paused", "resolved", "failed"] },
+    "stage_id": { "type": "string", "pattern": "^stage\\.[a-z0-9][a-z0-9-]*$" },
+    "feature_id": { "type": "string", "minLength": 1 },
+    "skill_source": {
+      "type": "object", "additionalProperties": false,
+      "required": ["registry_ref", "defaults_ref", "core_skills", "forbidden_skills"],
+      "properties": {
+        "registry_ref": { "const": "docs/agents/digital-human-roles.yaml" },
+        "defaults_ref": { "type": "string", "minLength": 1 },
+        "core_skills": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "forbidden_skills": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "contract": {
+      "type": "object", "additionalProperties": false,
+      "required": ["kind", "contract_id", "contract_version", "status", "contract_ref"],
+      "properties": {
+        "kind": { "enum": ["lifecycle-work-unit", "slice-implementation", "template-maintenance"] },
+        "contract_id": { "type": "string", "minLength": 1 },
+        "contract_version": { "type": "integer", "minimum": 1 },
+        "status": { "enum": ["issued", "stale", "blocked"] },
+        "contract_ref": { "type": "string", "minLength": 1 },
+        "lifecycle_ref": { "type": "string", "minLength": 1 },
+        "slice_contract_ref": { "type": "string", "minLength": 1 },
+        "maintenance_ref": { "type": "string", "minLength": 1 },
+        "artifact_refs": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "gate_refs": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "inputs": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+    "objective": { "type": "string", "minLength": 1 },
+    "allowed_write_paths": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "forbidden_actions": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "expected_outputs": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+    "expected_evidence_files": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "verification_commands": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+    "verification_results": {
+      "type": "array", "items": {
+        "type": "object", "additionalProperties": false,
+        "required": ["command", "exit_code", "executed_at", "evidence_ref"],
+        "properties": {
+          "command": { "type": "string", "minLength": 1 },
+          "exit_code": { "type": "integer", "minimum": 0 },
+          "duration_ms": { "type": "integer", "minimum": 0 },
+          "executed_at": { "type": "string", "minLength": 1 },
+          "evidence_ref": { "type": "string", "minLength": 1 },
+          "stdout_ref": { "type": "string", "minLength": 1 },
+          "stderr_ref": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "review_context": {
+      "type": "object", "additionalProperties": false, "required": ["implementation_actor_id"],
+      "properties": { "implementation_actor_id": { "type": "string", "minLength": 1 }, "implementation_task_id": { "type": "string", "minLength": 1 } }
+    },
+    "downstream_consumers": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+    "convergence": {
+      "type": "object", "additionalProperties": false, "required": ["parent_work_unit", "convergence_ref"],
+      "properties": {
+        "parent_work_unit": { "type": "string", "pattern": "^work-unit\\.[a-z0-9][a-z0-9-]*$" },
+        "convergence_ref": { "type": "string", "minLength": 1 },
+        "conflict_escalation": { "type": "string", "minLength": 1 }
+      }
+    },
+    "result": {
+      "type": "object", "additionalProperties": false,
+      "properties": {
+        "result_schema": { "const": "workflow-execution-result-v1" },
+        "work_unit": { "type": "string", "minLength": 1 },
+        "workflow_reference": { "type": "string", "minLength": 1 },
+        "result": { "enum": ["completed", "blocked", "needs-human", "failed"] },
+        "skill": { "type": "string", "minLength": 1 },
+        "changed_files": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "changed_artifacts": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "evidence_refs": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "deferred_seams": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "drift": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "violation": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "new_impacts": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "stale_candidates": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "next_route": { "type": ["string", "null"], "minLength": 1 },
+        "blocking_signals": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    }
+  },
+  "allOf": [
+    { "if": { "properties": { "contract": { "properties": { "kind": { "const": "lifecycle-work-unit" } } } } }, "then": { "required": ["stage_id"], "properties": { "contract": { "required": ["lifecycle_ref"] } } } },
+    { "if": { "properties": { "contract": { "properties": { "kind": { "const": "slice-implementation" } } } } }, "then": { "required": ["stage_id"], "properties": { "contract": { "required": ["slice_contract_ref"] } } } },
+    { "if": { "properties": { "contract": { "properties": { "kind": { "const": "template-maintenance" } } } } }, "then": { "properties": { "contract": { "required": ["maintenance_ref"] } } } },
+    { "if": { "properties": { "execution_state": { "const": "Reviewer" } } }, "then": { "required": ["review_context"] } }
+  ]
+}

package/template/docs/process/schemas/subagent-task-package.schema.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.dev/schemas/subagent-task-package.schema.json",
+  "title": "YSS Subagent Task Package (compatibility alias)",
+  "$ref": "digital-human-task-package.schema.json"
+}

package/template/docs/process/subagent-collaboration.md

@@ -6,8 +6,8 @@ Subagent 和其它运行时实例只接收边界清晰的任务包。主控数
 
 ## 任务包
 
-每个任务包必须写明数字人角色 ID、`runtime_id`、执行态、从 `docs/agents/digital-human-roles.yaml` 复制的 `core_skills` / `forbidden_skills`（可用 `taskPackageDefaults`）、输入资产、目标、允许写路径、禁止事项、验收标准、验证命令和汇合方式。禁止手写第二套技能包。
+凡主控向数字人角色或独立运行时正式派发生命周期工作单元，都必须使用 `docs/process/schemas/digital-human-task-package.schema.json` 定义的任务包，并写明 `task_id`、`work_unit_id`、`actor_id`、数字人角色 ID、`runtime_id`、执行态、工作流状态、从 `docs/agents/digital-human-roles.yaml` 复制的 `core_skills` / `forbidden_skills`（可用 `taskPackageDefaults`）、合同类型和版本、输入资产、目标、允许写路径、禁止事项、验收标准、验证命令及其实际退出码 / 执行时间 / 证据引用、下游消费者和汇合方式。`slice-implementation` 才额外绑定 Slice Implementation Contract；禁止手写第二套技能包；任务包由 `scripts/verify-digital-human-task-package` 校验，`scripts/verify-subagent-task-package` 仅为兼容入口。
 
 ## 汇合
 
-返回结果至少包括变更文件、证据文件、实际执行的命令、结果、延期 seam、drift / violation / new impacts 和建议下一路由。主控必须重新执行 fresh verification，并在集中 checkpoint 中保留阶段因果。会签写入 `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`（形状见 `docs/templates/approval-record-template.yaml`），不能用聊天表情代替。恢复前校验 `scripts/verify-approval-record`。
+返回结果必须符合 `workflow-execution-result-v1`，至少包括 `work_unit`、`workflow_reference`、`result`、`skill`、`changed_files` / `changed_artifacts`、`evidence_refs`、实际验证结果、`deferred_seams`、`drift`、`violation`、`new_impacts`、`stale_candidates`、`blocking_signals` 和 `next_route`。主控必须重新执行 fresh verification，并在集中 checkpoint 中保留阶段因果。会签写入 `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`（形状见 `docs/templates/approval-record-template.yaml`），不能用聊天表情代替。恢复前校验 `scripts/verify-approval-record`。

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

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

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