easy-coding-harness 0.9.1 → 0.10.0-beta.1

package/templates/shared-hooks/easy_coding_state.py

@@ -5,6 +5,7 @@ import json
 import os
 import re
 import secrets
+import shlex
 import subprocess
 import time
 import uuid
@@ -12,11 +13,20 @@ from datetime import datetime, timezone
 from pathlib import Path
 import sys
 
+from easy_dev_spec import (
+    EasyDevSpecError,
+    inspect_spec,
+    inspection_summary,
+    select_consumption_scopes,
+    select_tasks,
+)
+
 
 TERMINAL_STATUSES = {"COMPLETE", "CLOSED"}
 HELP_SUFFIX = (
     "Use `ec-workflow` to start or resume a task, "
-    "`ec-brainstorming` to brainstorm, or `ec-task-management` to manage tasks or session settings"
+    "`ec-brainstorming` to brainstorm, `ec-task-management` to manage tasks, "
+    "or `ec-config` to inspect or change modes"
 )
 READY_LINE = f"Ready · {HELP_SUFFIX}"
 WAITING_INIT_LINE = "Waiting init · Use `ec-init` to initialize"
@@ -70,6 +80,8 @@ STRICT_WORKFLOW_RISK_PATTERN = re.compile(
 )
 DEFAULT_APPROVAL_MODE = "guard"
 DEFAULT_WORKFLOW_MODE = "adaptive"
+DEFAULT_TDD_ENABLED = False
+DEFAULT_TDD_COVERAGE_THRESHOLD = 90
 CRITICAL_CONFIRM_TRANSITIONS = {
     ("ANALYSIS", "IMPLEMENT"),
     ("VERIFICATION", "MEMORY"),
@@ -87,7 +99,7 @@ DEFAULT_SHORT_TERM_KEEP = 5
 SESSION_STALE_THRESHOLD_HOURS = 30 * 24
 SESSION_COMPONENT_PATTERN = re.compile(r"^[A-Za-z0-9._-]+$")
 SESSION_AGENT_NAMESPACES = {"claude-code", "codex", "qoder", "unknown"}
-CODEX_AGENT_PATH_PATTERN = re.compile(r"^/root(?:/[a-z0-9._-]+)*$")
+CODEX_AGENT_PATH_PATTERN = re.compile(r"^/?root(?:/[a-z0-9._-]+)*$")
 LEGACY_STATE_LOCK_TIMEOUT_SECONDS = 5.0
 LEGACY_STATE_LOCK_STALE_SECONDS = 60.0
 LEGACY_STATE_LOCK_POLL_SECONDS = 0.02
@@ -157,7 +169,7 @@ def short_memory_id_sort_key(memory_id: str) -> tuple[int, str]:
 def normalize_agent_identity(agent: str | None) -> str:
     raw_agent = str(agent or "unknown").strip()
     normalized = raw_agent.lower()
-    # Codex 协作树中的 /root 路径表示 Codex 内部执行者，不是一个新的跨平台 Agent。
+    # Codex 可能把根执行者写成 root 或 /root；两者及其协作子路径都属于同一平台身份。
     if CODEX_AGENT_PATH_PATTERN.fullmatch(normalized):
         return "codex"
     if normalized in SESSION_AGENT_NAMESPACES:
@@ -302,16 +314,45 @@ def read_memory_config(root: Path) -> dict[str, int]:
     return config
 
 
-def read_project_behavior(root: Path) -> tuple[str, str]:
+def parse_tdd_threshold(value: object, source: str) -> int:
+    if isinstance(value, bool):
+        raise StateError(f"Invalid {source}: expected an integer from 1 to 100.")
+    try:
+        threshold = int(str(value))
+    except (TypeError, ValueError) as error:
+        raise StateError(f"Invalid {source}: expected an integer from 1 to 100.") from error
+    if threshold < 1 or threshold > 100:
+        raise StateError(f"Invalid {source}: expected an integer from 1 to 100.")
+    return threshold
+
+
+def parse_yaml_bool(value: str | None, source: str) -> bool:
+    if value is None:
+        return DEFAULT_TDD_ENABLED
+    normalized = value.lower()
+    if normalized in {"true", "yes", "on"}:
+        return True
+    if normalized in {"false", "no", "off"}:
+        return False
+    raise StateError(f"Invalid {source}: expected true or false.")
+
+
+def read_project_behavior(root: Path) -> tuple[str, str, bool, int]:
     path = root / ".easy-coding" / "config.yaml"
     try:
         lines = path.read_text(encoding="utf-8").splitlines()
     except OSError:
-        return DEFAULT_APPROVAL_MODE, DEFAULT_WORKFLOW_MODE
+        return (
+            DEFAULT_APPROVAL_MODE,
+            DEFAULT_WORKFLOW_MODE,
+            DEFAULT_TDD_ENABLED,
+            DEFAULT_TDD_COVERAGE_THRESHOLD,
+        )
 
     in_behavior = False
     behavior_indent = 0
     behavior: dict[str, str] = {}
+    schema_version = 0
     for raw_line in lines:
         without_comment = raw_line.split("#", 1)[0].rstrip()
         stripped = without_comment.strip()
@@ -324,6 +365,12 @@ def read_project_behavior(root: Path) -> tuple[str, str]:
             continue
         if in_behavior and indent <= behavior_indent:
             in_behavior = False
+        if not in_behavior and indent == 0 and stripped.startswith("version:"):
+            try:
+                schema_version = int(stripped.split(":", 1)[1].strip().strip("'\""))
+            except ValueError:
+                schema_version = 0
+            continue
         if not in_behavior or ":" not in stripped:
             continue
         key, value = stripped.split(":", 1)
@@ -351,16 +398,27 @@ def read_project_behavior(root: Path) -> tuple[str, str]:
             "Invalid behavior.workflow_mode in .easy-coding/config.yaml: "
             "expected adaptive, fast, standard, or strict."
         )
-    return approval_mode, workflow_mode
+    if schema_version >= 4:
+        tdd_enabled = parse_yaml_bool(behavior.get("tdd_enabled"), "behavior.tdd_enabled")
+        tdd_threshold = parse_tdd_threshold(
+            behavior.get("tdd_coverage_threshold", DEFAULT_TDD_COVERAGE_THRESHOLD),
+            "behavior.tdd_coverage_threshold",
+        )
+    else:
+        tdd_enabled = DEFAULT_TDD_ENABLED
+        tdd_threshold = DEFAULT_TDD_COVERAGE_THRESHOLD
+    return approval_mode, workflow_mode, tdd_enabled, tdd_threshold
 
 
 def resolve_behavior(
     root: Path, session: dict
-) -> tuple[str, str | None, str, str, str | None, str]:
-    project_approval, project_workflow = read_project_behavior(root)
+) -> tuple[str, str | None, str, str, str | None, str, bool, bool | None, bool, int, int | None, int]:
+    project_approval, project_workflow, project_tdd, project_threshold = read_project_behavior(root)
     legacy = session.get("confirm_mode")
     session_approval = session.get("approval_mode")
     session_workflow = session.get("workflow_mode")
+    session_tdd = session.get("tdd_enabled")
+    session_threshold = session.get("tdd_coverage_threshold")
     if session_approval is None:
         if legacy == "lite":
             session_approval = "guard"
@@ -379,6 +437,12 @@ def resolve_behavior(
         raise StateError(
             "Invalid session workflow_mode: expected adaptive, fast, standard, or strict."
         )
+    if session_tdd is not None and not isinstance(session_tdd, bool):
+        raise StateError("Invalid session tdd_enabled: expected true or false.")
+    if session_threshold is not None:
+        session_threshold = parse_tdd_threshold(
+            session_threshold, "session tdd_coverage_threshold"
+        )
     return (
         project_approval,
         str(session_approval) if session_approval else None,
@@ -386,6 +450,12 @@ def resolve_behavior(
         project_workflow,
         str(session_workflow) if session_workflow else None,
         str(session_workflow or project_workflow),
+        project_tdd,
+        session_tdd,
+        session_tdd if session_tdd is not None else project_tdd,
+        project_threshold,
+        session_threshold,
+        session_threshold if session_threshold is not None else project_threshold,
     )
 
 
@@ -1071,6 +1141,337 @@ def is_read_only_execution_plan(plan: object) -> bool:
     )
 
 
+def stored_spec_path(root: Path, task: dict) -> Path:
+    source = task.get("spec_source")
+    if not isinstance(source, dict) or not is_non_empty_string(source.get("path")):
+        raise StateError("Spec-backed task is missing spec_source.path.")
+    raw_path = Path(str(source["path"]))
+    path = raw_path if raw_path.is_absolute() else root / raw_path
+    resolved = path.resolve()
+    try:
+        resolved.relative_to(root.resolve())
+    except ValueError as exc:
+        raise StateError("Spec-backed task source path must remain inside the project root.") from exc
+    return resolved
+
+
+def inspect_task_spec(root: Path, task: dict) -> tuple[dict, dict]:
+    source = task.get("spec_source")
+    selected = task.get("selected_spec_tasks")
+    repo_paths = task.get("repo_paths")
+    if not isinstance(source, dict) or not is_string_list(selected, allow_empty=False):
+        raise StateError("Spec-backed task source and selected task metadata are incomplete.")
+    try:
+        inspection = inspect_spec(
+            stored_spec_path(root, task),
+            root,
+            repo_paths if isinstance(repo_paths, dict) else {},
+            selected,
+        )
+        satisfied = {
+            f"{record.get('source_task_id')}->{record.get('task_id')}": str(record.get("evidence"))
+            for record in task.get("spec_dependency_evidence", [])
+            if isinstance(record, dict)
+            and record.get("status") == "satisfied"
+            and is_non_empty_string(record.get("task_id"))
+            and is_non_empty_string(record.get("evidence"))
+        }
+        selection = select_tasks(inspection, selected, satisfied)
+    except EasyDevSpecError as exc:
+        raise StateError(f"Canonical Spec validation failed: {exc}") from exc
+    stored_dependencies = task.get("spec_dependency_evidence")
+    if not isinstance(stored_dependencies, list):
+        raise StateError("Spec-backed task dependency metadata is incomplete.")
+    expected_by_edge = {
+        (record.get("source_task_id"), record.get("task_id")): record
+        for record in selection["dependency_records"]
+    }
+    stored_by_edge = {
+        (record.get("source_task_id"), record.get("task_id")): record
+        for record in stored_dependencies
+        if isinstance(record, dict)
+    }
+    if (
+        len(stored_by_edge) != len(stored_dependencies)
+        or set(stored_by_edge) != set(expected_by_edge)
+    ):
+        raise StateError("Canonical Spec dependency metadata no longer matches source selection.")
+    for edge, expected in expected_by_edge.items():
+        stored = stored_by_edge[edge]
+        for field in ("dependency_type", "required_evidence", "status"):
+            if stored.get(field) != expected.get(field):
+                raise StateError(
+                    "Canonical Spec dependency metadata no longer matches source selection."
+                )
+        if stored.get("evidence") != expected.get("evidence"):
+            raise StateError(
+                "Canonical Spec dependency evidence no longer matches its recorded status."
+            )
+    if source.get("schema") != inspection.get("schema"):
+        raise StateError("Canonical Spec schema no longer matches task.json.")
+    if source.get("spec_id") != inspection.get("spec_id"):
+        raise StateError("Canonical Spec ID no longer matches task.json.")
+    if source.get("revision") != inspection.get("revision"):
+        raise StateError("Canonical Spec revision no longer matches task.json.")
+    if source.get("sha256") != inspection.get("source_sha256"):
+        raise StateError("Canonical Spec SHA-256 changed after task creation.")
+    selected_repo_ids = set(selection["selected_repo_ids"])
+    stored_bindings = task.get("spec_repositories")
+    if not isinstance(stored_bindings, list):
+        raise StateError("Spec-backed task repository metadata is incomplete.")
+    stored_by_repo = {
+        str(binding.get("repo_id")): binding
+        for binding in stored_bindings
+        if isinstance(binding, dict) and is_non_empty_string(binding.get("repo_id"))
+    }
+    current_by_repo = {
+        str(binding.get("repo_id")): binding
+        for binding in inspection.get("repository_bindings", [])
+        if isinstance(binding, dict)
+        and str(binding.get("repo_id")) in selected_repo_ids
+    }
+    if (
+        len(stored_by_repo) != len(stored_bindings)
+        or set(stored_by_repo) != selected_repo_ids
+        or set(current_by_repo) != selected_repo_ids
+    ):
+        raise StateError("Canonical Spec repository bindings no longer match task.json.")
+    for repo_id in selected_repo_ids:
+        stored = stored_by_repo[repo_id]
+        current = current_by_repo[repo_id]
+        for field in ("repo_id", "name", "path", "baseline_commit"):
+            if stored.get(field) != current.get(field):
+                raise StateError("Canonical Spec repository bindings no longer match task.json.")
+    return inspection, selection
+
+
+def is_valid_spec_execution_plan(root: Path, task: dict, plan: object) -> bool:
+    if not isinstance(plan, dict):
+        return False
+    try:
+        inspection, selection = inspect_task_spec(root, task)
+    except StateError:
+        return False
+    selected_ids = set(selection["selected_task_ids"])
+    task_by_id = {item["task_id"]: item for item in selection["selected_tasks"]}
+    change_by_id = {
+        str(change["change_id"]): change for change in selection["selected_changes"]
+    }
+    step_by_id = {
+        str(step["step_id"]): step for step in selection["selected_steps"]
+    }
+    test_by_id = {
+        str(test["test_id"]): test for test in selection["selected_tests"]
+    }
+    changes_by_task: dict[str, list[dict]] = {task_id: [] for task_id in selected_ids}
+    tests_by_task: dict[str, list[dict]] = {task_id: [] for task_id in selected_ids}
+    for change in selection["selected_changes"]:
+        changes_by_task[str(change["task_id"])].append(change)
+    for test in selection["selected_tests"]:
+        tests_by_task[str(test["task_id"])].append(test)
+
+    units = [unit for unit in plan.get("units", []) if isinstance(unit, dict)]
+    units_by_task: dict[str, list[dict]] = {task_id: [] for task_id in selected_ids}
+    covered_steps: dict[str, list[str]] = {task_id: [] for task_id in selected_ids}
+    covered_files: dict[str, set[str]] = {task_id: set() for task_id in selected_ids}
+    covered_symbols: dict[str, set[str]] = {task_id: set() for task_id in selected_ids}
+    covered_commands: dict[str, set[str]] = {task_id: set() for task_id in selected_ids}
+    unit_by_id = {str(unit["id"]): unit for unit in units}
+    unit_id_by_step: dict[str, str] = {}
+    for unit in units:
+        source_task_id = unit.get("source_task_id")
+        if source_task_id not in selected_ids:
+            return False
+        source_task_id = str(source_task_id)
+        source_task = task_by_id[source_task_id]
+        if unit.get("repo_id") != source_task.get("repo_id"):
+            return False
+        for field in ("source_step_ids", "symbols", "test_commands"):
+            if not is_string_list(unit.get(field), allow_empty=False):
+                return False
+        allowed_steps = set(source_task.get("step_ids", []))
+        if not set(unit["source_step_ids"]).issubset(allowed_steps):
+            return False
+        source_steps = [step_by_id.get(str(step_id)) for step_id in unit["source_step_ids"]]
+        if any(
+            step is None or step.get("task_id") != source_task_id
+            for step in source_steps
+        ):
+            return False
+        step_change_ids = {
+            str(change_id)
+            for step in source_steps
+            if isinstance(step, dict)
+            for change_id in step.get("change_ids", [])
+        }
+        step_test_ids = {
+            str(test_id)
+            for step in source_steps
+            if isinstance(step, dict)
+            for test_id in step.get("test_ids", [])
+        }
+        step_files = {
+            str(change_by_id[change_id]["path"])
+            for change_id in step_change_ids
+            if change_id in change_by_id
+        }
+        step_symbols = {
+            str(symbol)
+            for change_id in step_change_ids
+            if change_id in change_by_id
+            for symbol in change_by_id[change_id].get("symbols", [])
+        }
+        step_commands = {
+            str(test_by_id[test_id]["command"])
+            for test_id in step_test_ids
+            if test_id in test_by_id
+        }
+        # Unit 必须保存它声明的 source steps 的完整文件、符号和源测试映射；附加本地命令可保留。
+        if (
+            not step_change_ids.issubset(change_by_id)
+            or not step_test_ids.issubset(test_by_id)
+            or set(unit.get("files", [])) != step_files
+            or set(unit["symbols"]) != step_symbols
+            or not set(unit["test_commands"]).issuperset(step_commands)
+        ):
+            return False
+        for step_id in unit["source_step_ids"]:
+            normalized_step_id = str(step_id)
+            if normalized_step_id in unit_id_by_step:
+                return False
+            unit_id_by_step[normalized_step_id] = str(unit["id"])
+        units_by_task[source_task_id].append(unit)
+        covered_steps[source_task_id].extend(unit["source_step_ids"])
+        covered_files[source_task_id].update(unit.get("files", []))
+        covered_symbols[source_task_id].update(unit["symbols"])
+        covered_commands[source_task_id].update(unit["test_commands"])
+
+    for source_task_id, source_task in task_by_id.items():
+        if not units_by_task[source_task_id]:
+            return False
+        steps = covered_steps[source_task_id]
+        if len(steps) != len(set(steps)) or set(steps) != set(source_task.get("step_ids", [])):
+            return False
+        if covered_files[source_task_id] != {
+            str(change["path"]) for change in changes_by_task[source_task_id]
+        }:
+            return False
+        if covered_symbols[source_task_id] != {
+            str(symbol)
+            for change in changes_by_task[source_task_id]
+            for symbol in change.get("symbols", [])
+        }:
+            return False
+        if not covered_commands[source_task_id].issuperset({
+            str(test["command"]) for test in tests_by_task[source_task_id]
+        }):
+            return False
+
+    # 同一 source task 内的 Step DAG 也必须投影到 Unit DAG；合并在同一 Unit 的步骤无需自依赖。
+    for step_id, step in step_by_id.items():
+        owner_unit_id = unit_id_by_step.get(step_id)
+        if owner_unit_id is None:
+            return False
+        owner_unit = unit_by_id[owner_unit_id]
+        for dependency_step_id in step.get("depends_on_step_ids", []):
+            dependency_unit_id = unit_id_by_step.get(str(dependency_step_id))
+            if dependency_unit_id is None:
+                return False
+            if (
+                dependency_unit_id != owner_unit_id
+                and dependency_unit_id not in owner_unit.get("depends_on", [])
+            ):
+                return False
+
+    # hard 依赖必须投影为 Unit DAG，不能只保存在说明文字中。
+    unit_ids_by_task = {
+        source_task_id: {str(unit["id"]) for unit in source_units}
+        for source_task_id, source_units in units_by_task.items()
+    }
+    for edge in inspection.get("dependency_edges", []):
+        source_task_id = str(edge.get("source_task_id") or "")
+        dependency_task_id = str(edge.get("task_id") or "")
+        if (
+            edge.get("dependency_type") != "hard"
+            or source_task_id not in selected_ids
+            or dependency_task_id not in selected_ids
+        ):
+            continue
+        dependency_ids = unit_ids_by_task[dependency_task_id]
+        depended_on_within_dependency = {
+            dependency
+            for unit in units_by_task[dependency_task_id]
+            for dependency in unit.get("depends_on", [])
+            if dependency in dependency_ids
+        }
+        dependency_terminals = dependency_ids - depended_on_within_dependency
+        source_units = units_by_task[source_task_id]
+        source_ids = unit_ids_by_task[source_task_id]
+        source_roots = [
+            unit
+            for unit in source_units
+            if not set(unit.get("depends_on", [])).intersection(source_ids)
+        ]
+        if not dependency_terminals or any(
+            not dependency_terminals.issubset(set(unit.get("depends_on", [])))
+            for unit in source_roots
+        ):
+            return False
+    return True
+
+
+def contains_spec_marker(content: str, marker: str) -> bool:
+    boundary_characters = (
+        r"A-Za-z0-9_/" + ("." if "/" in marker or "." in marker else "") + "-"
+    )
+    return (
+        re.search(
+            rf"(?<![{boundary_characters}]){re.escape(marker)}(?![{boundary_characters}])",
+            content,
+        )
+        is not None
+    )
+
+
+def missing_spec_test_strategy_markers(
+    selection: dict, plan: dict, content: str
+) -> list[str]:
+    unit_ids_by_step = {
+        str(step_id): str(unit["id"])
+        for unit in plan.get("units", [])
+        if isinstance(unit, dict)
+        for step_id in unit.get("source_step_ids", [])
+    }
+    owner_units_by_test: dict[str, set[str]] = {}
+    for step in selection.get("selected_steps", []):
+        if not isinstance(step, dict):
+            continue
+        owner_unit_id = unit_ids_by_step.get(str(step.get("step_id") or ""))
+        if not owner_unit_id:
+            continue
+        for test_id in step.get("test_ids", []):
+            owner_units_by_test.setdefault(str(test_id), set()).add(owner_unit_id)
+
+    missing: list[str] = []
+    for test in selection.get("selected_tests", []):
+        if not isinstance(test, dict):
+            continue
+        test_id = str(test.get("test_id") or "")
+        markers = {
+            test_id,
+            str(test.get("task_id") or ""),
+            str(test.get("file") or ""),
+            str(test.get("command") or ""),
+            *owner_units_by_test.get(test_id, set()),
+        }
+        missing.extend(
+            marker
+            for marker in sorted(markers)
+            if marker and not contains_spec_marker(content, marker)
+        )
+    return list(dict.fromkeys(missing))
+
+
 def read_project_schema_version(root: Path) -> int:
     path = root / ".easy-coding" / "config.yaml"
     try:
@@ -1105,10 +1506,15 @@ def has_valid_execution_plan(root: Path, task_id: str) -> bool:
     task_type = str(task.get("type") or "").strip().lower() if task else ""
     if task_type in NO_CODE_TASK_TYPES:
         return is_read_only_execution_plan(latest_plan)
-    return is_valid_execution_plan(
+    valid = is_valid_execution_plan(
         latest_plan,
         require_unit_contracts=read_project_schema_version(root) >= 3,
     )
+    if not valid:
+        return False
+    if task and isinstance(task.get("spec_source"), dict):
+        return is_valid_spec_execution_plan(root, task, latest_plan)
+    return True
 
 
 def execution_records(root: Path, task_id: str) -> list[dict]:
@@ -1131,10 +1537,10 @@ def execution_records(root: Path, task_id: str) -> list[dict]:
 def latest_execution_plan(root: Path, task_id: str) -> dict | None:
     latest: dict | None = None
     for record in execution_records(root, task_id):
-        if record.get("type") == "plan" and is_valid_execution_plan(
-            record, allow_empty_files=True
-        ):
+        if record.get("type") == "plan":
             latest = record
+    if latest is None or not is_valid_execution_plan(latest, allow_empty_files=True):
+        return None
     return latest
 
 
@@ -1188,6 +1594,44 @@ def minimize_repository_scopes(repository: Path, scopes: set[Path]) -> list[Path
 def task_repository_scopes(
     root: Path, task: dict | None, plan: dict
 ) -> list[tuple[Path, list[Path]]]:
+    if task and isinstance(task.get("spec_source"), dict):
+        repo_paths = task.get("repo_paths")
+        if not isinstance(repo_paths, dict):
+            raise StateError("Spec-backed task is missing repo_paths.")
+        repositories: dict[Path, set[Path]] = {}
+        for unit in plan.get("units", []):
+            if not isinstance(unit, dict) or not is_non_empty_string(unit.get("repo_id")):
+                raise StateError("Spec-backed execution unit is missing repo_id.")
+            repo_id = str(unit["repo_id"])
+            raw_repo_path = repo_paths.get(repo_id)
+            if not is_non_empty_string(raw_repo_path):
+                raise StateError(f"Spec repository path is missing: {repo_id}")
+            candidate = Path(str(raw_repo_path))
+            repository_path = (candidate if candidate.is_absolute() else root / candidate).resolve()
+            repository = git_repository_root(repository_path)
+            if repository is None or repository.resolve() != repository_path:
+                raise StateError(f"Spec repository binding is not a Git root: {repo_id}")
+            scopes = repositories.setdefault(repository, set())
+            scopes.add(repository)
+            for file_name in unit.get("files", []):
+                if not is_non_empty_string(file_name):
+                    raise StateError(f"Spec execution unit has an invalid file path: {repo_id}")
+                relative_path = Path(str(file_name))
+                if relative_path.is_absolute() or ".." in relative_path.parts:
+                    raise StateError(f"Spec execution unit path escapes repository {repo_id}: {file_name}")
+                resolved_file = (repository / relative_path).resolve()
+                if not is_path_within(resolved_file, repository):
+                    raise StateError(f"Spec execution unit path escapes repository {repo_id}: {file_name}")
+                file_repository = git_repository_root(resolved_file)
+                if file_repository is None or file_repository.resolve() != repository:
+                    raise StateError(
+                        f"Spec execution unit path belongs to another Git repository: {repo_id}:{file_name}"
+                    )
+        return [
+            (repository, [repository])
+            for repository in sorted(repositories, key=lambda item: item.as_posix())
+        ]
+
     scope_candidates = [root]
     if task:
         repo_paths = task.get("repo_paths")
@@ -1242,6 +1686,77 @@ def task_repository_roots(root: Path, task: dict | None, plan: dict) -> list[Pat
     ]
 
 
+def tdd_repositories(root: Path, task: dict, plan: dict) -> dict[str, Path]:
+    if isinstance(task.get("spec_source"), dict):
+        repo_paths = task.get("repo_paths")
+        if not isinstance(repo_paths, dict):
+            raise StateError("TDD Canonical task is missing repository bindings.")
+        repositories: dict[str, Path] = {}
+        for unit in plan.get("units", []):
+            if not isinstance(unit, dict) or not is_non_empty_string(unit.get("repo_id")):
+                raise StateError("TDD Canonical unit is missing repo_id.")
+            repo_id = str(unit["repo_id"])
+            raw_path = repo_paths.get(repo_id)
+            if not is_non_empty_string(raw_path):
+                raise StateError(f"TDD repository path is missing: {repo_id}")
+            candidate = Path(str(raw_path))
+            resolved = (candidate if candidate.is_absolute() else root / candidate).resolve()
+            repository = git_repository_root(resolved)
+            if repository is None or repository.resolve() != resolved:
+                raise StateError(f"TDD repository binding is not a Git root: {repo_id}")
+            repositories[repo_id] = repository
+        return repositories
+
+    repositories = task_repository_roots(root, task, plan)
+    if len(repositories) != 1:
+        raise StateError(
+            "Non-Canonical TDD requires exactly one Git repository; use a Canonical Spec for multi-repository work."
+        )
+    return {"project": repositories[0]}
+
+
+def git_head_sha(repository: Path) -> str:
+    result = run_git(repository, "rev-parse", "--verify", "HEAD")
+    sha = result.stdout.decode("ascii", errors="ignore").strip() if result else ""
+    if (
+        result is None
+        or result.returncode != 0
+        or re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", sha) is None
+    ):
+        raise StateError(f"Cannot freeze TDD Git baseline for {repository.name}.")
+    return sha
+
+
+def tdd_baseline_marker_reasons(
+    dev_spec_content: str, strategy_content: str, baselines: dict[str, str]
+) -> list[str]:
+    reasons: list[str] = []
+    canonical = set(baselines) != {"project"}
+    for repo_id, baseline in sorted(baselines.items()):
+        for artifact_name, content in (
+            ("dev-spec.md", dev_spec_content),
+            ("test-strategy.md", strategy_content),
+        ):
+            if baseline not in content:
+                reasons.append(
+                    f"{artifact_name} must record the immutable TDD baseline SHA for {repo_id}: {baseline}"
+                )
+            if canonical and repo_id not in content:
+                reasons.append(
+                    f"{artifact_name} must map the TDD baseline to repository {repo_id}"
+                )
+    return reasons
+
+
+def contains_tdd_threshold(content: str, threshold: int) -> bool:
+    return re.search(
+        rf"(?<!\d){threshold}\s*%|--threshold(?:\s+|=){threshold}(?!\d)|"
+        rf"tdd_coverage_threshold\s*[:=]\s*{threshold}(?!\d)",
+        content,
+        re.IGNORECASE,
+    ) is not None
+
+
 def repository_scope_pathspecs(repository: Path, scopes: list[Path]) -> list[str]:
     return [
         f":(literal){scope.relative_to(repository).as_posix()}"
@@ -1455,6 +1970,18 @@ def implementation_fingerprint(root: Path, task_id: str) -> str:
     digest.update(b"workflow-mode\0")
     digest.update(workflow_mode.encode("utf-8"))
     digest.update(b"\0")
+    if task and task.get("tdd_enabled") is True:
+        digest.update(b"tdd\0enabled\0")
+        digest.update(str(task.get("tdd_coverage_threshold") or "").encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(
+            json.dumps(
+                task.get("tdd_baselines") or {},
+                sort_keys=True,
+                separators=(",", ":"),
+            ).encode("utf-8")
+        )
+        digest.update(b"\0")
     digest.update(b"execution-plan\0")
     digest.update(
         json.dumps(
@@ -1465,28 +1992,51 @@ def implementation_fingerprint(root: Path, task_id: str) -> str:
         ).encode("utf-8")
     )
     digest.update(b"\0")
+    if task and isinstance(task.get("spec_source"), dict):
+        digest.update(b"canonical-spec\0")
+        digest.update(
+            json.dumps(
+                {
+                    "source": task.get("spec_source"),
+                    "selected_tasks": task.get("selected_spec_tasks"),
+                },
+                ensure_ascii=False,
+                sort_keys=True,
+                separators=(",", ":"),
+            ).encode("utf-8")
+        )
+        digest.update(b"\0")
     update_git_worktree_fingerprint(digest, root, task, plan)
-    file_names = sorted(
-        {
-            str(file_name)
-            for unit in plan.get("units", [])
-            if isinstance(unit, dict)
-            for file_name in unit.get("files", [])
-            if is_non_empty_string(file_name)
-        }
-    )
-    for file_name in file_names:
+    repo_paths = task.get("repo_paths") if task else None
+    file_entries: set[tuple[str, str | None]] = {
+        (str(file_name), str(unit.get("repo_id")) if unit.get("repo_id") else None)
+        for unit in plan.get("units", [])
+        if isinstance(unit, dict)
+        for file_name in unit.get("files", [])
+        if is_non_empty_string(file_name)
+    }
+    for file_name, repo_id in sorted(file_entries, key=lambda item: (item[0], item[1] or "")):
         candidate = Path(file_name)
         was_absolute = candidate.is_absolute()
+        base = root
+        if (
+            task
+            and isinstance(task.get("spec_source"), dict)
+            and isinstance(repo_paths, dict)
+            and repo_id
+            and is_non_empty_string(repo_paths.get(repo_id))
+        ):
+            raw_base = Path(str(repo_paths[repo_id]))
+            base = raw_base if raw_base.is_absolute() else root / raw_base
         if not was_absolute:
-            candidate = root / candidate
+            candidate = base / candidate
         resolved = candidate.resolve()
         if not was_absolute:
             try:
-                resolved.relative_to(root.resolve())
+                resolved.relative_to(base.resolve())
             except ValueError as error:
-                raise StateError(f"Execution plan file escapes project root: {file_name}") from error
-        digest.update(file_name.encode("utf-8"))
+                raise StateError(f"Execution plan file escapes repository: {file_name}") from error
+        digest.update(f"{repo_id or ''}:{file_name}".encode("utf-8"))
         digest.update(b"\0")
         try:
             digest.update(resolved.read_bytes())
@@ -1496,25 +2046,167 @@ def implementation_fingerprint(root: Path, task_id: str) -> str:
     return digest.hexdigest()
 
 
-def behavior_config_fingerprint(root: Path) -> str:
+def config_without_frozen_tdd_settings(payload: bytes) -> bytes:
+    """任务冻结 TDD 契约后，从证据指纹中排除仅影响未来任务的实时 TDD 配置。"""
+    try:
+        lines = payload.decode("utf-8").splitlines(keepends=True)
+    except UnicodeDecodeError:
+        return payload
+    filtered: list[str] = []
+    in_behavior = False
+    behavior_indent = 0
+    behavior_key_indent: int | None = None
+    for line in lines:
+        clean = line.split("#", 1)[0].rstrip()
+        stripped = clean.strip()
+        indent = len(clean) - len(clean.lstrip(" "))
+        if stripped == "behavior:":
+            in_behavior = True
+            behavior_indent = indent
+            behavior_key_indent = None
+            filtered.append(line)
+            continue
+        if in_behavior and stripped and indent <= behavior_indent:
+            in_behavior = False
+        if in_behavior and stripped:
+            if behavior_key_indent is None:
+                behavior_key_indent = indent
+            key = stripped.split(":", 1)[0]
+            if (
+                indent == behavior_key_indent
+                and key in {"tdd_enabled", "tdd_coverage_threshold"}
+            ):
+                continue
+        filtered.append(line)
+    return "".join(filtered).encode("utf-8")
+
+
+def behavior_config_fingerprint(root: Path, task: dict | None = None) -> str:
     path = root / ".easy-coding" / "config.yaml"
     digest = hashlib.sha256()
     try:
-        digest.update(path.read_bytes())
+        payload = path.read_bytes()
+        if task and isinstance(task.get("tdd_enabled"), bool):
+            payload = config_without_frozen_tdd_settings(payload)
+        digest.update(payload)
     except OSError:
         digest.update(b"<missing-config>")
     return digest.hexdigest()
 
 
 def evidence_fingerprints(root: Path, task_id: str) -> dict[str, str]:
+    task = load_task(root, task_id)
     return {
         "implementation_fingerprint": implementation_fingerprint(root, task_id),
-        "config_fingerprint": behavior_config_fingerprint(root),
+        "config_fingerprint": behavior_config_fingerprint(root, task),
+    }
+
+
+def command_option_value(command: str, option: str) -> str | None:
+    try:
+        tokens = shlex.split(command)
+    except ValueError:
+        return None
+    for index, token in enumerate(tokens):
+        if token == option and index + 1 < len(tokens):
+            return tokens[index + 1]
+        prefix = f"{option}="
+        if token.startswith(prefix):
+            return token[len(prefix) :]
+    return None
+
+
+def coverage_command_matches_frozen_contract(
+    command: object, baseline: str, threshold: int
+) -> bool:
+    if not is_non_empty_string(command):
+        return False
+    try:
+        tokens = shlex.split(str(command))
+    except ValueError:
+        return False
+    return (
+        any(Path(token).name == "easy_coding_java_coverage.py" for token in tokens)
+        and "check" in tokens
+        and command_option_value(str(command), "--base") == baseline
+        and command_option_value(str(command), "--threshold") == str(threshold)
+    )
+
+
+def validate_spec_implementation_results(root: Path, task_id: str, task: dict) -> None:
+    if not isinstance(task.get("spec_source"), dict):
+        return
+    plan = latest_execution_plan(root, task_id)
+    if plan is None or not is_valid_spec_execution_plan(root, task, plan):
+        raise StateError("Canonical Spec implementation has no valid source-traceable plan.")
+    unit_by_id = {
+        str(unit["id"]): unit for unit in plan.get("units", []) if isinstance(unit, dict)
     }
+    records = execution_records(root, task_id)
+    latest_plan_index = max(
+        (index for index, record in enumerate(records) if record.get("type") == "plan"),
+        default=-1,
+    )
+    lifecycle_by_unit: dict[str, list[dict]] = {unit_id: [] for unit_id in unit_by_id}
+    for record in records[latest_plan_index + 1 :]:
+        unit_id = str(record.get("unit_id") or "")
+        if record.get("type") in {"dispatch", "result"} and unit_id in unit_by_id:
+            lifecycle_by_unit[unit_id].append(record)
+    missing_dispatches = sorted(
+        unit_id
+        for unit_id, lifecycle in lifecycle_by_unit.items()
+        if not any(record.get("type") == "dispatch" for record in lifecycle)
+    )
+    if missing_dispatches:
+        raise StateError(
+            "Canonical Spec implementation is missing dispatch records for units: "
+            + ", ".join(missing_dispatches)
+        )
+    missing_results = sorted(
+        unit_id
+        for unit_id, lifecycle in lifecycle_by_unit.items()
+        if not lifecycle or lifecycle[-1].get("type") != "result"
+    )
+    if missing_results:
+        raise StateError(
+            "Canonical Spec implementation is missing result records for units: "
+            + ", ".join(missing_results)
+        )
+    for unit_id, unit in unit_by_id.items():
+        lifecycle = lifecycle_by_unit[unit_id]
+        if len(lifecycle) < 2 or lifecycle[-2].get("type") != "dispatch":
+            raise StateError(
+                f"Canonical Spec result {unit_id} has no matching preceding dispatch record."
+            )
+        dispatch = lifecycle[-2]
+        if (
+            dispatch.get("repo_id") != unit.get("repo_id")
+            or dispatch.get("source_task_id") != unit.get("source_task_id")
+        ):
+            raise StateError(
+                f"Canonical Spec dispatch {unit_id} must preserve repository/source-task ownership."
+            )
+        result = lifecycle[-1]
+        if (
+            result.get("repo_id") != unit.get("repo_id")
+            or result.get("source_task_id") != unit.get("source_task_id")
+            or result.get("status") != "completed"
+            or not isinstance(result.get("changed_files"), list)
+            or not set(result.get("changed_files", [])).issubset(set(unit.get("files", [])))
+            or not is_non_empty_string(result.get("summary"))
+            or result.get("issues") != []
+            or result.get("needs_attention") != []
+        ):
+            raise StateError(
+                f"Canonical Spec result {unit_id} must be completed without unresolved issues, "
+                "preserve repository/source-task ownership, and remain within the Unit file scope."
+            )
 
 
 def validate_review_readiness(root: Path, task_id: str, task: dict) -> None:
-    if task.get("workflow_mode_legacy") is True:
+    validate_spec_implementation_results(root, task_id, task)
+    is_spec_task = isinstance(task.get("spec_source"), dict)
+    if task.get("workflow_mode_legacy") is True and not is_spec_task:
         return
     expected = implementation_fingerprint(root, task_id)
     latest_by_dimension: dict[str, dict] = {}
@@ -1524,7 +2216,10 @@ def validate_review_readiness(root: Path, task_id: str, task: dict) -> None:
             and record.get("implementation_fingerprint") == expected
             and is_non_empty_string(record.get("dimension"))
         ):
-            latest_by_dimension[str(record["dimension"])] = record
+            dimension = str(record["dimension"])
+            source_task_id = str(record.get("source_task_id") or "")
+            record_key = f"{dimension}\0{source_task_id}" if is_spec_task else dimension
+            latest_by_dimension[record_key] = record
     if not latest_by_dimension:
         raise StateError(
             "REVIEW cannot advance to VERIFICATION without a review record for the current implementation fingerprint."
@@ -1543,6 +2238,42 @@ def validate_review_readiness(root: Path, task_id: str, task: dict) -> None:
                 "Each review finding must include a non-empty file and issue, a positive integer "
                 "line, and severity error, warning, or info."
             )
+    if is_spec_task:
+        plan = latest_execution_plan(root, task_id) or {}
+        task_repositories = {
+            str(unit.get("source_task_id")): str(unit.get("repo_id"))
+            for unit in plan.get("units", [])
+            if isinstance(unit, dict)
+            and is_non_empty_string(unit.get("source_task_id"))
+            and is_non_empty_string(unit.get("repo_id"))
+        }
+        reviewed_dimensions: dict[str, set[str]] = {
+            source_task_id: set() for source_task_id in task_repositories
+        }
+        for record in latest_by_dimension.values():
+            source_task_id = str(record.get("source_task_id") or "")
+            repo_id = str(record.get("repo_id") or "")
+            if source_task_id not in task_repositories or repo_id != task_repositories[source_task_id]:
+                raise StateError(
+                    "Canonical Spec review evidence must preserve repository/source-task ownership."
+                )
+            for finding in record["findings"]:
+                finding_path = Path(str(finding["file"]))
+                if finding_path.is_absolute() or ".." in finding_path.parts:
+                    raise StateError(
+                        "Canonical Spec review findings must use safe repository-relative paths."
+                    )
+            reviewed_dimensions[source_task_id].add(str(record["dimension"]))
+        missing_review_tasks = sorted(
+            source_task_id
+            for source_task_id, dimensions in reviewed_dimensions.items()
+            if not dimensions
+        )
+        if missing_review_tasks:
+            raise StateError(
+                "Canonical Spec review evidence does not cover selected source tasks: "
+                + ", ".join(missing_review_tasks)
+            )
     has_failed_dimension = False
     for record in latest_by_dimension.values():
         findings = record.get("findings")
@@ -1558,16 +2289,48 @@ def validate_review_readiness(root: Path, task_id: str, task: dict) -> None:
         raise StateError(
             "REVIEW cannot advance to VERIFICATION while a current review dimension is not passed or has error findings."
         )
-    if task.get("workflow_mode") == "strict" and len(latest_by_dimension) < 2:
-        raise StateError(
-            "Strict workflow requires at least two passed review dimensions for the current implementation fingerprint."
-        )
+    if task.get("tdd_enabled") is True:
+        if is_spec_task:
+            missing_tdd_reviews = sorted(
+                source_task_id
+                for source_task_id, dimensions in reviewed_dimensions.items()
+                if "tdd" not in {dimension.lower() for dimension in dimensions}
+            )
+            if missing_tdd_reviews:
+                raise StateError(
+                    "TDD tasks require a passed TDD review dimension for every selected source task: "
+                    + ", ".join(missing_tdd_reviews)
+                )
+        elif not any(
+            str(record.get("dimension") or "").lower() == "tdd"
+            for record in latest_by_dimension.values()
+        ):
+            raise StateError(
+                "TDD tasks require a passed TDD review dimension for test quality, boundaries, and mocking."
+            )
+    if task.get("workflow_mode") == "strict":
+        if is_spec_task:
+            missing_strict_dimensions = sorted(
+                source_task_id
+                for source_task_id, dimensions in reviewed_dimensions.items()
+                if len(dimensions) < 2
+            )
+            if missing_strict_dimensions:
+                raise StateError(
+                    "Strict Canonical Spec review requires at least two passed dimensions for "
+                    "every selected source task: " + ", ".join(missing_strict_dimensions)
+                )
+        elif len(latest_by_dimension) < 2:
+            raise StateError(
+                "Strict workflow requires at least two passed review dimensions for the current implementation fingerprint."
+            )
 
 
 def validate_verification_readiness(root: Path, task_id: str, task: dict) -> None:
     fingerprints = evidence_fingerprints(root, task_id)
+    is_spec_task = isinstance(task.get("spec_source"), dict)
     if (
-        task.get("workflow_mode_legacy") is not True
+        (task.get("workflow_mode_legacy") is not True or is_spec_task)
         and task.get("workflow_mode_legacy_review_bypass_fingerprint")
         != fingerprints["implementation_fingerprint"]
     ):
@@ -1582,6 +2345,10 @@ def validate_verification_readiness(root: Path, task_id: str, task: dict) -> Non
             and is_non_empty_string(record.get("check"))
         ):
             check = str(record["check"])
+            if task.get("tdd_enabled") is True and record.get("check_type") == "coverage":
+                check = f"{check}\0{record.get('coverage_scope') or ''}"
+            if is_spec_task:
+                check = f"{check}\0{record.get('source_task_id') or ''}"
             previous = latest_by_check.get(check)
             if (
                 record.get("applicable") is False
@@ -1594,11 +2361,11 @@ def validate_verification_readiness(root: Path, task_id: str, task: dict) -> Non
         raise StateError(
             "VERIFICATION cannot advance to MEMORY without verification evidence for the current implementation and config fingerprints."
         )
-    if task.get("workflow_mode_legacy") is not True:
+    if task.get("workflow_mode_legacy") is not True or is_spec_task:
         for record in latest_by_check.values():
             check_type = str(record.get("check_type") or "")
             if (
-                check_type not in STRICT_VERIFICATION_CHECK_TYPES
+                check_type not in STRICT_VERIFICATION_CHECK_TYPES | {"coverage"}
                 or not is_non_empty_string(record.get("timestamp"))
                 or (
                     record.get("applicable") is not False
@@ -1614,6 +2381,25 @@ def validate_verification_readiness(root: Path, task_id: str, task: dict) -> Non
                 raise StateError(
                     "Verification evidence marked not applicable must include a non-empty not_applicable_reason."
                 )
+    if is_spec_task:
+        plan = latest_execution_plan(root, task_id) or {}
+        task_repositories = {
+            str(unit.get("source_task_id")): str(unit.get("repo_id"))
+            for unit in plan.get("units", [])
+            if isinstance(unit, dict)
+            and is_non_empty_string(unit.get("source_task_id"))
+            and is_non_empty_string(unit.get("repo_id"))
+        }
+        for record in latest_by_check.values():
+            source_task_id = str(record.get("source_task_id") or "")
+            if (
+                source_task_id not in task_repositories
+                or record.get("repo_id") != task_repositories[source_task_id]
+            ):
+                raise StateError(
+                    "Canonical Spec verification evidence must preserve "
+                    "repository/source-task ownership."
+                )
     applicable_records = [
         record for record in latest_by_check.values() if record.get("applicable") is not False
     ]
@@ -1625,27 +2411,243 @@ def validate_verification_readiness(root: Path, task_id: str, task: dict) -> Non
         raise StateError(
             "VERIFICATION cannot advance to MEMORY while current verification evidence contains failures."
         )
-    if task.get("workflow_mode") == "strict":
-        latest_by_type: dict[str, dict] = {}
-        for record in latest_by_check.values():
-            check_type = str(record.get("check_type") or "")
-            if check_type in STRICT_VERIFICATION_CHECK_TYPES:
-                latest_by_type[check_type] = record
-        missing_types = sorted(STRICT_VERIFICATION_CHECK_TYPES - latest_by_type.keys())
-        if missing_types:
+    if task.get("tdd_enabled") is not True and any(
+        record.get("check_type") == "coverage" for record in latest_by_check.values()
+    ):
+        raise StateError(
+            "Coverage verification evidence is not allowed when the frozen TDD mode is off."
+        )
+    if task.get("tdd_enabled") is True:
+        coverage_records = [
+            record
+            for record in latest_by_check.values()
+            if record.get("check_type") == "coverage"
+        ]
+        if not coverage_records:
             raise StateError(
-                "Strict workflow requires current verification evidence for every check type: "
-                + ", ".join(missing_types)
-                + "."
+                "TDD verification requires changed-production-line JaCoCo coverage evidence."
             )
-        for check_type, record in latest_by_type.items():
-            if record.get("applicable") is False and not is_non_empty_string(
-                record.get("not_applicable_reason")
+        if is_spec_task:
+            covered_source_tasks = {
+                str(record.get("source_task_id") or "") for record in coverage_records
+            }
+            missing_coverage_tasks = sorted(
+                set(task_repositories) - covered_source_tasks
+            )
+            if missing_coverage_tasks:
+                raise StateError(
+                    "TDD Canonical verification requires separate coverage evidence for every selected source task: "
+                    + ", ".join(missing_coverage_tasks)
+                )
+        coverage_scopes_by_owner: dict[str, set[str]] = {}
+        for record in coverage_records:
+            scope = str(record.get("coverage_scope") or "")
+            if scope not in {"local", "gitlab"}:
+                raise StateError(
+                    "TDD coverage evidence must identify coverage_scope as local or gitlab."
+                )
+            owner = (
+                str(record.get("source_task_id") or "")
+                if is_spec_task
+                else "project"
+            )
+            coverage_scopes_by_owner.setdefault(owner, set()).add(scope)
+        expected_threshold = task.get("tdd_coverage_threshold")
+        expected_baselines = task.get("tdd_baselines")
+        if (
+            type(expected_threshold) is not int
+            or expected_threshold < 1
+            or expected_threshold > 100
+        ):
+            raise StateError("TDD task is missing a valid frozen coverage threshold.")
+        if not isinstance(expected_baselines, dict) or not expected_baselines:
+            raise StateError("TDD task is missing frozen Git baselines.")
+        for record in coverage_records:
+            coverage = record.get("coverage")
+            if not isinstance(coverage, dict):
+                raise StateError("TDD coverage evidence must include the coverage result object.")
+            if record.get("coverage_scope") == "gitlab":
+                ci = record.get("ci")
+                if (
+                    not isinstance(ci, dict)
+                    or ci.get("provider") != "gitlab"
+                    or ci.get("status") != "success"
+                    or not is_non_empty_string(ci.get("pipeline_url"))
+                    or not is_non_empty_string(ci.get("job_name"))
+                ):
+                    raise StateError(
+                        "GitLab coverage evidence requires a successful pipeline URL and job name."
+                    )
+            total = coverage.get("total_lines")
+            covered = coverage.get("covered_lines")
+            percentage = coverage.get("percentage")
+            threshold = coverage.get("threshold")
+            baseline_key = str(record.get("repo_id") or "") if is_spec_task else "project"
+            expected_baseline = expected_baselines.get(baseline_key)
+            if (
+                not is_non_empty_string(expected_baseline)
+                or coverage.get("baseline_sha") != expected_baseline
+                or re.fullmatch(
+                    r"[0-9a-f]{40}|[0-9a-f]{64}", str(coverage.get("baseline_sha") or "")
+                )
+                is None
+                or not isinstance(total, int)
+                or not isinstance(covered, int)
+                or not isinstance(percentage, (int, float))
+                or threshold != expected_threshold
+                or not isinstance(coverage.get("report_paths"), list)
+                or not coverage.get("report_paths")
+                or not all(
+                    is_non_empty_string(path) for path in coverage.get("report_paths", [])
+                )
+                or not re.fullmatch(
+                    r"[0-9a-f]{64}", str(coverage.get("report_sha256") or "")
+                )
+                or covered < 0
+                or total < 0
+                or covered > total
+                or percentage < 0
+                or percentage > 100
+                or not coverage_command_matches_frozen_contract(
+                    record.get("command"), str(expected_baseline), int(expected_threshold)
+                )
             ):
                 raise StateError(
-                    "Strict workflow requires a non-empty not_applicable_reason when "
-                    f"{check_type} is marked not applicable."
+                    "TDD coverage evidence must preserve the exact gate command, baseline, counts, percentage, frozen threshold, reports, and report fingerprint."
+                )
+            if total == 0:
+                if record.get("applicable") is not False or record.get("passed") is not True:
+                    raise StateError(
+                        "Coverage with no modified executable production Java lines must be explicit N/A."
+                    )
+            elif abs(percentage - round(covered * 100.0 / total, 2)) > 0.01:
+                raise StateError(
+                    "TDD coverage evidence percentage does not match covered/total counts."
+                )
+            elif (
+                record.get("applicable") is False
+                or record.get("passed") is not True
+                or percentage < threshold
+            ):
+                raise StateError(
+                    f"TDD changed-line coverage must meet the frozen {threshold}% threshold."
+                )
+        expected_coverage_owners = set(task_repositories) if is_spec_task else {"project"}
+        missing_scopes = [
+            f"{owner}:{scope}"
+            for owner in sorted(expected_coverage_owners)
+            for scope in ("local", "gitlab")
+            if scope not in coverage_scopes_by_owner.get(owner, set())
+        ]
+        if missing_scopes:
+            raise StateError(
+                "TDD verification requires both local and successful GitLab coverage gates: "
+                + ", ".join(missing_scopes)
+            )
+    if task.get("workflow_mode") == "strict":
+        if is_spec_task:
+            check_types_by_repository: dict[str, set[str]] = {
+                repo_id: set() for repo_id in set(task_repositories.values())
+            }
+            for record in latest_by_check.values():
+                repo_id = str(record.get("repo_id") or "")
+                check_type = str(record.get("check_type") or "")
+                if repo_id in check_types_by_repository and check_type in STRICT_VERIFICATION_CHECK_TYPES:
+                    check_types_by_repository[repo_id].add(check_type)
+            missing_by_repository = {
+                repo_id: sorted(STRICT_VERIFICATION_CHECK_TYPES - check_types)
+                for repo_id, check_types in check_types_by_repository.items()
+                if check_types != STRICT_VERIFICATION_CHECK_TYPES
+            }
+            if missing_by_repository:
+                raise StateError(
+                    "Strict Canonical Spec verification requires every repository to cover "
+                    "lint, typecheck, test, and build: "
+                    + "; ".join(
+                        f"{repo_id} missing {', '.join(check_types)}"
+                        for repo_id, check_types in sorted(missing_by_repository.items())
+                    )
                 )
+        else:
+            latest_by_type: dict[str, dict] = {}
+            for record in latest_by_check.values():
+                check_type = str(record.get("check_type") or "")
+                if check_type in STRICT_VERIFICATION_CHECK_TYPES:
+                    latest_by_type[check_type] = record
+            missing_types = sorted(STRICT_VERIFICATION_CHECK_TYPES - latest_by_type.keys())
+            if missing_types:
+                raise StateError(
+                    "Strict workflow requires current verification evidence for every check type: "
+                    + ", ".join(missing_types)
+                    + "."
+                )
+            for check_type, record in latest_by_type.items():
+                if record.get("applicable") is False and not is_non_empty_string(
+                    record.get("not_applicable_reason")
+                ):
+                    raise StateError(
+                        "Strict workflow requires a non-empty not_applicable_reason when "
+                        f"{check_type} is marked not applicable."
+                    )
+    if is_spec_task:
+        inspect_task_spec(root, task)
+        plan = latest_execution_plan(root, task_id)
+        required_test_commands = {
+            (
+                str(unit.get("source_task_id")),
+                str(unit.get("repo_id")),
+                str(command),
+            )
+            for unit in (plan or {}).get("units", [])
+            if isinstance(unit, dict)
+            for command in unit.get("test_commands", [])
+            if is_non_empty_string(command)
+        }
+        executed_commands = {
+            (
+                str(record.get("source_task_id")),
+                str(record.get("repo_id")),
+                str(record.get("command")),
+            )
+            for record in applicable_records
+            if is_non_empty_string(record.get("command"))
+        }
+        missing_commands = sorted(required_test_commands - executed_commands)
+        if missing_commands:
+            raise StateError(
+                "Canonical Spec verification is missing source test commands: "
+                + ", ".join(
+                    f"{source_task_id}@{repo_id}: {command}"
+                    for source_task_id, repo_id, command in missing_commands
+                )
+            )
+        covered_verification_tasks = {
+            str(record.get("source_task_id")) for record in applicable_records
+        }
+        missing_verification_tasks = sorted(
+            set(task_repositories) - covered_verification_tasks
+        )
+        if missing_verification_tasks:
+            raise StateError(
+                "Canonical Spec verification evidence does not cover selected source tasks: "
+                + ", ".join(missing_verification_tasks)
+            )
+        pending_integration = [
+            record
+            for record in task.get("spec_dependency_evidence", [])
+            if isinstance(record, dict)
+            and record.get("dependency_type") == "integration"
+            and record.get("status") != "satisfied"
+        ]
+        if pending_integration:
+            edges = ", ".join(
+                f"{record.get('source_task_id')}->{record.get('task_id')}"
+                for record in pending_integration
+            )
+            raise StateError(
+                "VERIFICATION cannot advance to MEMORY while Canonical Spec integration "
+                f"dependencies are pending: {edges}."
+            )
 
 
 def validate_read_only_completion(root: Path, task_id: str) -> None:
@@ -1812,7 +2814,9 @@ def validate_mandatory_dev_spec_sections(content: str) -> tuple[list[str], list[
     return missing, empty
 
 
-def validate_analysis_readiness(root: Path, task_id: str) -> None:
+def validate_analysis_readiness(
+    root: Path, task_id: str, session: dict | None = None
+) -> None:
     task_dir = task_json_path(root, task_id).parent
     task = load_task(root, task_id)
     task_type = str(task.get("type") or "").strip().lower() if task else ""
@@ -1821,6 +2825,9 @@ def validate_analysis_readiness(root: Path, task_id: str) -> None:
     skeleton = root / ".easy-coding" / "templates" / "dev-spec-skeleton.md"
     test_strategy = task_dir / "test-strategy.md"
     reasons: list[str] = []
+    behavior = resolve_behavior(root, session or default_session())
+    tdd_enabled = behavior[8]
+    tdd_threshold = behavior[11]
 
     dev_spec_content = ""
     if not dev_spec.exists():
@@ -1864,8 +2871,201 @@ def validate_analysis_readiness(root: Path, task_id: str) -> None:
             except OSError:
                 reasons.append("dev-spec skeleton template cannot be read")
 
-    if not has_valid_execution_plan(root, task_id):
+    plan_is_valid = has_valid_execution_plan(root, task_id)
+    if not plan_is_valid:
         reasons.append("execution.jsonl has no valid plan record")
+    if tdd_enabled and not is_read_only_task:
+        plan = latest_execution_plan(root, task_id) or {}
+        if re.search(
+            r"^###\s+TDD Mode\s*$", dev_spec_content, re.MULTILINE | re.IGNORECASE
+        ) is None:
+            reasons.append("dev-spec.md is missing the required TDD Mode section")
+        planned_files = [
+            str(file_name)
+            for unit in plan.get("units", [])
+            if isinstance(unit, dict)
+            for file_name in unit.get("files", [])
+        ]
+        if not any(file_name.endswith(".java") for file_name in planned_files):
+            reasons.append("TDD is enabled but the confirmed implementation scope has no Java source")
+        baselines: dict[str, str] = {}
+        if task:
+            try:
+                repositories = tdd_repositories(root, task, plan)
+                baselines = {
+                    repo_id: git_head_sha(repository)
+                    for repo_id, repository in repositories.items()
+                }
+            except StateError as error:
+                reasons.append(str(error))
+        try:
+            strategy_content = test_strategy.read_text(encoding="utf-8")
+        except OSError:
+            strategy_content = ""
+        required_tdd_markers = ["TDD", "JaCoCo", "baseline", "GitLab"]
+        missing_tdd_markers = [
+            marker for marker in required_tdd_markers if marker.lower() not in strategy_content.lower()
+        ]
+        if missing_tdd_markers:
+            reasons.append(
+                "TDD test strategy is missing: " + ", ".join(missing_tdd_markers)
+            )
+        if not contains_tdd_threshold(strategy_content, tdd_threshold):
+            reasons.append(
+                f"TDD test strategy must state the frozen {tdd_threshold}% coverage threshold"
+            )
+        if not contains_tdd_threshold(dev_spec_content, tdd_threshold):
+            reasons.append(
+                f"TDD dev spec must state the frozen {tdd_threshold}% coverage threshold"
+            )
+        if baselines:
+            reasons.extend(
+                tdd_baseline_marker_reasons(
+                    dev_spec_content, strategy_content, baselines
+                )
+            )
+    elif not is_read_only_task:
+        if re.search(
+            r"^###\s+TDD Mode\s*$", dev_spec_content, re.MULTILINE | re.IGNORECASE
+        ):
+            reasons.append("dev-spec.md must omit the TDD Mode section when TDD is disabled")
+        try:
+            strategy_content = test_strategy.read_text(encoding="utf-8")
+        except OSError:
+            strategy_content = ""
+        forbidden_tdd_markers = [
+            marker
+            for marker in (
+                "easy_coding_java_coverage.py",
+                "coverage_scope",
+                "task.tdd_baselines",
+                "RED -> GREEN -> REFACTOR",
+                "RED/GREEN/REFACTOR",
+            )
+            if marker.lower() in strategy_content.lower()
+        ]
+        if forbidden_tdd_markers:
+            reasons.append(
+                "test-strategy.md contains TDD-only planning while TDD is disabled: "
+                + ", ".join(forbidden_tdd_markers)
+            )
+    if task and isinstance(task.get("spec_source"), dict):
+        try:
+            inspection, selection = inspect_task_spec(root, task)
+            required_markers = [
+                str(task["spec_source"].get("path") or ""),
+                str(task["spec_source"].get("spec_id") or ""),
+                str(task["spec_source"].get("sha256") or ""),
+                *[str(task_id) for task_id in selection["selected_task_ids"]],
+                *[str(repo_id) for repo_id in selection["selected_repo_ids"]],
+                *[
+                    f"{repo_id}={inspection['baseline_status'].get(repo_id)}"
+                    for repo_id in selection["selected_repo_ids"]
+                ],
+            ]
+            missing_markers = [
+                marker
+                for marker in required_markers
+                if marker and not contains_spec_marker(dev_spec_content, marker)
+            ]
+            revision = task["spec_source"].get("revision")
+            if (
+                type(revision) is not int
+                or re.search(
+                    rf"\brevision\s*[:：=]\s*{revision}(?!\d)",
+                    dev_spec_content,
+                    re.IGNORECASE,
+                )
+                is None
+            ):
+                missing_markers.append(f"revision={revision}")
+            if missing_markers:
+                reasons.append(
+                    "dev-spec.md is missing Canonical Spec traceability markers: "
+                    + ", ".join(missing_markers)
+                )
+            selected_repo_ids = set(selection["selected_repo_ids"])
+            bindings = task.get("spec_repositories")
+            bound_repo_ids = {
+                str(binding.get("repo_id"))
+                for binding in bindings or []
+                if isinstance(binding, dict)
+            }
+            if bound_repo_ids != selected_repo_ids:
+                reasons.append("spec_repositories do not cover selected Canonical Spec tasks")
+            if inspection.get("unresolved_repositories"):
+                reasons.append(
+                    "Canonical Spec repository bindings are unresolved: "
+                    + ", ".join(inspection["unresolved_repositories"])
+                )
+            unavailable_repositories = [
+                repo_id
+                for repo_id in selection["selected_repo_ids"]
+                if inspection["baseline_status"].get(repo_id) == "baseline-unavailable"
+            ]
+            if unavailable_repositories:
+                reasons.append(
+                    "Canonical Spec baselines are unavailable: "
+                    + ", ".join(unavailable_repositories)
+                )
+            if plan_is_valid:
+                plan = latest_execution_plan(root, task_id)
+                if plan is None:
+                    reasons.append("Canonical Spec execution plan cannot be loaded")
+                else:
+                    task_repository_scopes(root, task, plan)
+                    derived_markers = [
+                        *[
+                            str(unit.get("id") or "")
+                            for unit in plan.get("units", [])
+                            if isinstance(unit, dict)
+                        ],
+                        *[
+                            str(step_id)
+                            for unit in plan.get("units", [])
+                            if isinstance(unit, dict)
+                            for step_id in unit.get("source_step_ids", [])
+                        ],
+                        *[
+                            f"{record.get('source_task_id')}->{record.get('task_id')}"
+                            for record in task.get("spec_dependency_evidence", [])
+                            if isinstance(record, dict)
+                            and record.get("dependency_type") == "integration"
+                            and record.get("status") == "pending"
+                        ],
+                        *[
+                            str(record.get("required_evidence") or "")
+                            for record in task.get("spec_dependency_evidence", [])
+                            if isinstance(record, dict)
+                            and record.get("dependency_type") == "integration"
+                            and record.get("status") == "pending"
+                        ],
+                    ]
+                    missing_derived_markers = [
+                        marker
+                        for marker in derived_markers
+                        if marker and not contains_spec_marker(dev_spec_content, marker)
+                    ]
+                    if missing_derived_markers:
+                        reasons.append(
+                            "dev-spec.md is missing Canonical Spec Unit/dependency markers: "
+                            + ", ".join(dict.fromkeys(missing_derived_markers))
+                        )
+                    if test_strategy.is_file():
+                        test_strategy_content = test_strategy.read_text(encoding="utf-8")
+                        if test_strategy_content.strip():
+                            missing_test_markers = missing_spec_test_strategy_markers(
+                                selection, plan, test_strategy_content
+                            )
+                            if missing_test_markers:
+                                reasons.append(
+                                    "test-strategy.md is missing Canonical Spec markers: "
+                                    + ", ".join(missing_test_markers)
+                                )
+        except StateError as exc:
+            reasons.append(str(exc))
+        except OSError:
+            reasons.append("test-strategy.md cannot be read")
     if is_read_only_task:
         if test_strategy.exists():
             reasons.append("read-only task must not create test-strategy.md")
@@ -1921,6 +3121,28 @@ def get_pending_init_version(root: Path) -> str | None:
     return None
 
 
+def spec_task_summary(task: dict | None) -> dict | None:
+    if not task or not isinstance(task.get("spec_source"), dict):
+        return None
+    dependencies = task.get("spec_dependency_evidence")
+    pending_dependencies = [
+        {
+            "source_task_id": record.get("source_task_id"),
+            "task_id": record.get("task_id"),
+            "dependency_type": record.get("dependency_type"),
+            "required_evidence": record.get("required_evidence"),
+        }
+        for record in dependencies or []
+        if isinstance(record, dict) and record.get("status") == "pending"
+    ]
+    return {
+        "source": task["spec_source"],
+        "selected_spec_tasks": task.get("selected_spec_tasks", []),
+        "repositories": task.get("spec_repositories", []),
+        "pending_dependencies": pending_dependencies,
+    }
+
+
 def transition_requires_confirmation(
     previous: str,
     current: str,
@@ -2012,6 +3234,12 @@ def snapshot_state(
         project_workflow_mode,
         session_workflow_mode,
         configured_workflow_mode,
+        project_tdd_enabled,
+        session_tdd_enabled,
+        effective_tdd_enabled,
+        project_tdd_coverage_threshold,
+        session_tdd_coverage_threshold,
+        effective_tdd_coverage_threshold,
     ) = resolve_behavior(root, resolved_session)
     concrete_workflow_mode = None
     if task:
@@ -2019,6 +3247,19 @@ def snapshot_state(
         proposal = task.get("workflow_mode_proposal")
         if concrete_workflow_mode is None and isinstance(proposal, dict):
             concrete_workflow_mode = proposal.get("selected_mode")
+    task_tdd_enabled = task.get("tdd_enabled") if task else None
+    task_tdd_coverage_threshold = task.get("tdd_coverage_threshold") if task else None
+    frozen_tdd = bool(
+        task
+        and status not in {"ANALYSIS", "INIT"}
+        and isinstance(task_tdd_enabled, bool)
+    )
+    displayed_tdd_enabled = task_tdd_enabled if frozen_tdd else effective_tdd_enabled
+    displayed_tdd_threshold = (
+        task_tdd_coverage_threshold
+        if frozen_tdd and isinstance(task_tdd_coverage_threshold, int)
+        else effective_tdd_coverage_threshold
+    )
 
     return {
         "session_file": display_path(root, session_path),
@@ -2039,6 +3280,18 @@ def snapshot_state(
         "session_workflow_mode": session_workflow_mode,
         "configured_workflow_mode": configured_workflow_mode,
         "concrete_workflow_mode": concrete_workflow_mode,
+        "project_tdd_enabled": project_tdd_enabled,
+        "session_tdd_enabled": session_tdd_enabled,
+        "effective_tdd_enabled": effective_tdd_enabled,
+        "project_tdd_coverage_threshold": project_tdd_coverage_threshold,
+        "session_tdd_coverage_threshold": session_tdd_coverage_threshold,
+        "effective_tdd_coverage_threshold": effective_tdd_coverage_threshold,
+        "task_tdd_enabled": task_tdd_enabled,
+        "task_tdd_coverage_threshold": task_tdd_coverage_threshold,
+        "task_tdd_baselines": task.get("tdd_baselines") if task else None,
+        "displayed_tdd_enabled": displayed_tdd_enabled,
+        "displayed_tdd_coverage_threshold": displayed_tdd_threshold,
+        "spec_summary": spec_task_summary(task),
         # Compatibility output aliases for pre-0.9 clients.
         "project_confirm_mode": project_approval_mode,
         "session_confirm_mode": session_approval_mode,
@@ -2057,6 +3310,8 @@ def build_status_line(
     approval = str(state["effective_approval_mode"]).capitalize()
     workflow = str(state["concrete_workflow_mode"] or state["configured_workflow_mode"]).capitalize()
     status_brand = f"> **Easy Coding** · **Approval: {approval}** · **Workflow: {workflow}**"
+    if state["displayed_tdd_enabled"] is True:
+        status_brand += " · **TDD**"
     task_id = state["current_task"]
     if task_id:
         status = str(state["status"])
@@ -2100,6 +3355,11 @@ def build_machine_breadcrumbs(
     ]
     if state.get("concrete_workflow_mode"):
         lines.append(f"[easy-coding:workflow-mode:{state['concrete_workflow_mode']}]")
+    if state.get("displayed_tdd_enabled") is True:
+        lines.append("[easy-coding:tdd:enabled]")
+        lines.append(
+            f"[easy-coding:tdd-coverage-threshold:{state['displayed_tdd_coverage_threshold']}]"
+        )
 
     if task_id:
         lines.append(f"[current-task:{task_id}]")
@@ -2245,6 +3505,7 @@ def list_tasks(root: Path, agent: str | None = None) -> list[dict]:
                 "action": action,
                 "previous_agent": last_agent if action == "takeover" else None,
                 "latest_handoff": latest_handoff_record(root, entry.name),
+                "spec_summary": spec_task_summary(task),
             }
         )
     return items
@@ -2406,6 +3667,43 @@ def clear_session_workflow_mode(
     return snapshot
 
 
+def set_session_tdd(
+    root: Path,
+    enabled: bool,
+    agent: str,
+    threshold: int | None = None,
+    session_file: str | Path | None = None,
+) -> dict:
+    session = ensure_session(root, session_file)
+    materialize_legacy_session_behavior(session)
+    session["tdd_enabled"] = enabled
+    if threshold is not None:
+        session["tdd_coverage_threshold"] = parse_tdd_threshold(
+            threshold, "session tdd_coverage_threshold"
+        )
+    session["last_agent"] = agent
+    write_session(root, session, session_file)
+    snapshot = snapshot_state(root, session_file, session)
+    snapshot["action"] = "set-tdd"
+    return snapshot
+
+
+def clear_session_tdd(
+    root: Path,
+    agent: str,
+    session_file: str | Path | None = None,
+) -> dict:
+    session = ensure_session(root, session_file)
+    materialize_legacy_session_behavior(session)
+    session.pop("tdd_enabled", None)
+    session.pop("tdd_coverage_threshold", None)
+    session["last_agent"] = agent
+    write_session(root, session, session_file)
+    snapshot = snapshot_state(root, session_file, session)
+    snapshot["action"] = "clear-tdd"
+    return snapshot
+
+
 def set_harness_disabled(
     root: Path,
     disabled: bool,
@@ -2507,6 +3805,7 @@ def create_task(
     agent: str,
     set_current: bool = True,
     session_file: str | Path | None = None,
+    task_fields: dict | None = None,
 ) -> dict:
     assert_safe_task_id(task_id)
     if set_current:
@@ -2529,12 +3828,137 @@ def create_task(
         "closed_reason": None,
         "repos": [],
     }
+    if task_fields:
+        task.update(task_fields)
     write_task(root, task_id, task)
     if set_current:
         return set_current_task(root, task_id, agent, session_file)
     return {"task_id": task_id, "task": task}
 
 
+def ensure_path_inside_root(root: Path, path: Path, label: str) -> Path:
+    resolved = path.resolve()
+    try:
+        resolved.relative_to(root.resolve())
+    except ValueError as exc:
+        raise StateError(f"{label} must be inside the Easy Coding project root.") from exc
+    return resolved
+
+
+def create_task_from_spec(
+    root: Path,
+    spec_path: str,
+    spec_task_ids: list[str],
+    task_id: str,
+    task_type: str,
+    title: str,
+    repo_paths: dict[str, str],
+    dependency_evidence: dict[str, str],
+    agent: str,
+    set_current: bool = True,
+    session_file: str | Path | None = None,
+) -> dict:
+    raw_spec_path = Path(spec_path)
+    resolved_spec_path = ensure_path_inside_root(
+        root,
+        raw_spec_path if raw_spec_path.is_absolute() else root / raw_spec_path,
+        "Canonical Spec path",
+    )
+    try:
+        inspection = inspect_spec(
+            resolved_spec_path,
+            root,
+            repo_paths,
+            spec_task_ids,
+        )
+        selection = select_tasks(inspection, spec_task_ids, dependency_evidence)
+    except EasyDevSpecError as exc:
+        raise StateError(f"Cannot create task from Canonical Spec: {exc}") from exc
+
+    selected_repo_ids = set(selection["selected_repo_ids"])
+    bindings = [
+        binding
+        for binding in inspection["repository_bindings"]
+        if binding.get("repo_id") in selected_repo_ids
+    ]
+    if len(bindings) != len(selected_repo_ids):
+        raise StateError("Canonical Spec repository bindings do not cover every selected task.")
+    stored_repo_paths = {
+        str(binding["repo_id"]): str(binding["path"])
+        for binding in bindings
+    }
+    source_path = resolved_spec_path.relative_to(root.resolve()).as_posix()
+    fields = {
+        "repos": list(selection["selected_repo_ids"]),
+        "repo_paths": stored_repo_paths,
+        "spec_source": {
+            "schema": inspection["schema"],
+            "spec_id": inspection["spec_id"],
+            "revision": inspection["revision"],
+            "path": source_path,
+            "sha256": inspection["source_sha256"],
+        },
+        "selected_spec_tasks": selection["selected_task_ids"],
+        "spec_repositories": bindings,
+        "spec_dependency_evidence": selection["dependency_records"],
+    }
+    return create_task(
+        root,
+        task_id,
+        task_type,
+        title,
+        agent,
+        set_current,
+        session_file,
+        fields,
+    )
+
+
+def satisfy_spec_dependency(
+    root: Path,
+    dependency_task_id: str,
+    evidence: str,
+    agent: str,
+    source_task_id: str | None = None,
+    task_id: str | None = None,
+    session_file: str | Path | None = None,
+) -> dict:
+    session, resolved_task_id, task = resolve_current_task(root, task_id, session_file)
+    if task.get("status") in TERMINAL_STATUSES or task.get("status") == "MEMORY":
+        raise StateError("Spec dependency evidence cannot change after MEMORY begins.")
+    if not is_non_empty_string(evidence):
+        raise StateError("Spec dependency evidence must be non-empty.")
+    inspect_task_spec(root, task)
+    records = task.get("spec_dependency_evidence")
+    if not isinstance(records, list):
+        raise StateError("Current task is not backed by Canonical Spec dependency metadata.")
+    matches = [
+        record
+        for record in records
+        if isinstance(record, dict)
+        and record.get("task_id") == dependency_task_id
+        and (source_task_id is None or record.get("source_task_id") == source_task_id)
+    ]
+    if not matches:
+        raise StateError("Canonical Spec dependency edge was not found.")
+    if source_task_id is None and len(matches) > 1:
+        raise StateError(
+            "Canonical Spec dependency is ambiguous; pass --source-task to identify the edge."
+        )
+    record = matches[0]
+    if record.get("dependency_type") == "contract":
+        raise StateError("Contract dependencies are satisfied by the frozen READY Spec.")
+    record["status"] = "satisfied"
+    record["evidence"] = evidence.strip()
+    record["satisfied_at"] = now_iso()
+    record["satisfied_by"] = agent
+    task["last_agent"] = agent
+    write_task(root, resolved_task_id, task)
+    snapshot = snapshot_state(root, session_file, session)
+    snapshot["action"] = "satisfy-spec-dependency"
+    return snapshot
+
+
 def append_stage_history(task: dict, stage: str, agent: str) -> None:
     history = task.setdefault("stage_history", [])
     history.append({"stage": stage, "agent": agent, "entered_at": now_iso()})
@@ -2710,6 +4134,39 @@ def freeze_workflow_mode(
     task["workflow_mode_confirmed_by"] = agent
 
 
+def freeze_tdd_mode(
+    root: Path, session: dict, task_id: str, task: dict, agent: str
+) -> None:
+    behavior = resolve_behavior(root, session)
+    task_type = str(task.get("type") or "").strip().lower()
+    task["tdd_enabled"] = behavior[8] if task_type not in NO_CODE_TASK_TYPES else False
+    task["tdd_coverage_threshold"] = behavior[11]
+    if task["tdd_enabled"] is True:
+        plan = latest_execution_plan(root, task_id)
+        if plan is None:
+            raise StateError("Cannot freeze TDD baseline without a valid execution plan.")
+        baselines = {
+            key: git_head_sha(repository)
+            for key, repository in tdd_repositories(root, task, plan).items()
+        }
+        task_dir = task_json_path(root, task_id).parent
+        try:
+            dev_spec_content = (task_dir / "dev-spec.md").read_text(encoding="utf-8")
+            strategy_content = (task_dir / "test-strategy.md").read_text(encoding="utf-8")
+        except OSError as error:
+            raise StateError("Cannot freeze TDD without readable analysis artifacts.") from error
+        marker_reasons = tdd_baseline_marker_reasons(
+            dev_spec_content, strategy_content, baselines
+        )
+        if marker_reasons:
+            raise StateError("; ".join(marker_reasons))
+        task["tdd_baselines"] = baselines
+    else:
+        task.pop("tdd_baselines", None)
+    task["tdd_confirmed_at"] = now_iso()
+    task["tdd_confirmed_by"] = agent
+
+
 def raise_workflow_mode(
     root: Path,
     mode: str,
@@ -2775,7 +4232,7 @@ def request_transition(
             "use auto-transition instead."
         )
     if previous == "ANALYSIS" and stage == "IMPLEMENT":
-        validate_analysis_readiness(root, resolved_task_id)
+        validate_analysis_readiness(root, resolved_task_id, session)
         if task.get("workflow_mode_legacy") is not True:
             validate_workflow_mode_proposal(
                 root,
@@ -2828,9 +4285,10 @@ def apply_transition(
     if violation:
         raise StateError(violation)
     if previous == "ANALYSIS" and stage == "IMPLEMENT":
-        validate_analysis_readiness(root, resolved_task_id)
+        validate_analysis_readiness(root, resolved_task_id, session)
         if task.get("workflow_mode_legacy") is not True:
             freeze_workflow_mode(root, session, resolved_task_id, task, agent)
+        freeze_tdd_mode(root, session, resolved_task_id, task, agent)
     if previous == "REVIEW" and stage == "VERIFICATION":
         validate_review_readiness(root, resolved_task_id, task)
     if previous == "VERIFICATION" and stage == "MEMORY":
@@ -3180,6 +4638,19 @@ def add_common_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--session-file", help="Session file path injected by the hook.")
 
 
+def parse_mapping_args(values: list[str], label: str) -> dict[str, str]:
+    mappings: dict[str, str] = {}
+    for value in values:
+        key, separator, mapped_value = value.partition("=")
+        if not separator or not key.strip() or not mapped_value.strip():
+            raise StateError(f"{label} must use KEY=VALUE syntax: {value!r}")
+        key = key.strip()
+        if key in mappings:
+            raise StateError(f"{label} contains a duplicate key: {key}")
+        mappings[key] = mapped_value.strip()
+    return mappings
+
+
 def main() -> int:
     configure_stdio()
     common = argparse.ArgumentParser(add_help=False)
@@ -3193,6 +4664,14 @@ def main() -> int:
     list_tasks_parser = subcommands.add_parser("list-tasks", parents=[common])
     list_tasks_parser.add_argument("--agent")
 
+    inspect_spec_parser = subcommands.add_parser("inspect-dev-spec", parents=[common])
+    inspect_spec_parser.add_argument("--spec", required=True)
+    inspect_spec_parser.add_argument("--repo-path", action="append", default=[])
+
+    select_spec_scope = subcommands.add_parser("select-dev-spec-scope", parents=[common])
+    select_spec_scope.add_argument("--spec", required=True)
+    select_spec_scope.add_argument("--spec-task", required=True, action="append")
+
     create = subcommands.add_parser("create-task", parents=[common])
     create.add_argument("--task-id", required=True)
     create.add_argument("--type", required=True)
@@ -3200,6 +4679,17 @@ def main() -> int:
     create.add_argument("--agent", required=True)
     create.add_argument("--no-set-current", action="store_true")
 
+    create_from_spec = subcommands.add_parser("create-task-from-spec", parents=[common])
+    create_from_spec.add_argument("--spec", required=True)
+    create_from_spec.add_argument("--spec-task", required=True, action="append")
+    create_from_spec.add_argument("--task-id", required=True)
+    create_from_spec.add_argument("--type", required=True)
+    create_from_spec.add_argument("--title", required=True)
+    create_from_spec.add_argument("--repo-path", required=True, action="append")
+    create_from_spec.add_argument("--dependency-evidence", action="append", default=[])
+    create_from_spec.add_argument("--agent", required=True)
+    create_from_spec.add_argument("--no-set-current", action="store_true")
+
     set_current = subcommands.add_parser("set-current", parents=[common])
     set_current.add_argument("--task-id", required=True)
     set_current.add_argument("--agent", required=True)
@@ -3223,6 +4713,14 @@ def main() -> int:
     clear_workflow_mode_parser = subcommands.add_parser("clear-workflow-mode", parents=[common])
     clear_workflow_mode_parser.add_argument("--agent", required=True)
 
+    set_tdd_parser = subcommands.add_parser("set-tdd", parents=[common])
+    set_tdd_parser.add_argument("--enabled", required=True, choices=["true", "false"])
+    set_tdd_parser.add_argument("--threshold", type=int)
+    set_tdd_parser.add_argument("--agent", required=True)
+
+    clear_tdd_parser = subcommands.add_parser("clear-tdd", parents=[common])
+    clear_tdd_parser.add_argument("--agent", required=True)
+
     # Compatibility aliases for pre-0.9 callers.
     set_confirm_mode_parser = subcommands.add_parser("set-confirm-mode", parents=[common])
     set_confirm_mode_parser.add_argument(
@@ -3339,6 +4837,13 @@ def main() -> int:
     repo_path.add_argument("--agent")
     repo_path.add_argument("--task-id")
 
+    satisfy_dependency = subcommands.add_parser("satisfy-spec-dependency", parents=[common])
+    satisfy_dependency.add_argument("--spec-task", required=True)
+    satisfy_dependency.add_argument("--source-task")
+    satisfy_dependency.add_argument("--evidence", required=True)
+    satisfy_dependency.add_argument("--agent", required=True)
+    satisfy_dependency.add_argument("--task-id")
+
     args = parser.parse_args()
     try:
         root = resolve_root(getattr(args, "cwd", None))
@@ -3353,7 +4858,12 @@ def main() -> int:
             raise StateError(
                 "project-init-complete requires --session-file from the current hook context."
             )
-        if session_file is None and command not in {"list-tasks", "memory-new-id"}:
+        if session_file is None and command not in {
+            "inspect-dev-spec",
+            "select-dev-spec-scope",
+            "list-tasks",
+            "memory-new-id",
+        }:
             if session_agent == "unknown":
                 raise StateError(
                     "Cannot resolve the logical session. Pass --session-file or --agent."
@@ -3361,6 +4871,26 @@ def main() -> int:
             _, session_file = ensure_hook_session(root, {}, session_agent)
         if command == "snapshot":
             emit(snapshot_state(root, session_file))
+        elif command == "inspect-dev-spec":
+            spec_path = Path(args.spec)
+            emit(
+                inspection_summary(
+                    inspect_spec(
+                        spec_path if spec_path.is_absolute() else root / spec_path,
+                        root,
+                        parse_mapping_args(args.repo_path, "--repo-path"),
+                    )
+                )
+            )
+        elif command == "select-dev-spec-scope":
+            spec_path = Path(args.spec)
+            emit(
+                select_consumption_scopes(
+                    spec_path if spec_path.is_absolute() else root / spec_path,
+                    root,
+                    args.spec_task,
+                )
+            )
         elif command == "list-tasks":
             emit({"tasks": list_tasks(root, visible_agent)})
         elif command == "create-task":
@@ -3380,6 +4910,30 @@ def main() -> int:
                     session_file,
                 )
             )
+        elif command == "create-task-from-spec":
+            emit(
+                attach_status_context(
+                    root,
+                    create_task_from_spec(
+                        root,
+                        args.spec,
+                        args.spec_task,
+                        args.task_id,
+                        args.type,
+                        args.title,
+                        parse_mapping_args(args.repo_path, "--repo-path"),
+                        parse_mapping_args(
+                            args.dependency_evidence,
+                            "--dependency-evidence",
+                        ),
+                        agent,
+                        not args.no_set_current,
+                        session_file,
+                    ),
+                    agent,
+                    session_file,
+                )
+            )
         elif command == "set-current":
             emit(
                 attach_status_context(
@@ -3452,6 +5006,30 @@ def main() -> int:
                     session_file,
                 )
             )
+        elif command == "set-tdd":
+            emit(
+                attach_status_context(
+                    root,
+                    set_session_tdd(
+                        root,
+                        args.enabled == "true",
+                        agent,
+                        args.threshold,
+                        session_file,
+                    ),
+                    agent,
+                    session_file,
+                )
+            )
+        elif command == "clear-tdd":
+            emit(
+                attach_status_context(
+                    root,
+                    clear_session_tdd(root, agent, session_file),
+                    agent,
+                    session_file,
+                )
+            )
         elif command == "propose-workflow-mode":
             emit(
                 attach_status_context(
@@ -3664,8 +5242,25 @@ def main() -> int:
                     session_file,
                 )
             )
+        elif command == "satisfy-spec-dependency":
+            emit(
+                attach_status_context(
+                    root,
+                    satisfy_spec_dependency(
+                        root,
+                        args.spec_task,
+                        args.evidence,
+                        agent,
+                        args.source_task,
+                        args.task_id,
+                        session_file,
+                    ),
+                    agent,
+                    session_file,
+                )
+            )
         return 0
-    except StateError as error:
+    except (StateError, EasyDevSpecError) as error:
         print(json.dumps({"error": str(error)}, ensure_ascii=False), file=sys.stderr)
         return 1