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

package/templates/shared-hooks/easy_coding_state.py

@@ -66,6 +66,7 @@ ALWAYS_AUTO_TRANSITIONS = {
 }
 READ_ONLY_COMPLETION_TRANSITION = ("IMPLEMENT", "COMPLETE")
 NO_CODE_TASK_TYPES = {"analysis", "doc", "report"}
+TDD_INIT_TASK_TYPE = "tdd-init"
 APPROVAL_MODES = {"approve", "guard", "confirm", "auto"}
 CONFIGURED_WORKFLOW_MODES = {"adaptive", "fast", "standard", "strict"}
 WORKFLOW_MODES = {"fast", "standard", "strict"}
@@ -82,6 +83,14 @@ DEFAULT_APPROVAL_MODE = "guard"
 DEFAULT_WORKFLOW_MODE = "adaptive"
 DEFAULT_TDD_ENABLED = False
 DEFAULT_TDD_COVERAGE_THRESHOLD = 90
+TDD_READINESS_SCHEMA = "easy-coding/tdd-readiness-v1"
+TDD_READINESS_SCOPE = "changed-production-lines"
+TDD_READINESS_PATH = Path(".easy-coding/tdd/readiness.json")
+TDD_BASE_VARIABLE = "EASY_CODING_TDD_BASE_SHA"
+TDD_THRESHOLD_VARIABLE = "EASY_CODING_TDD_THRESHOLD"
+COVERAGE_TOOL_PATH = ".easy-coding/tools/easy_coding_java_coverage.py"
+JAVA_BUILD_FILE_NAMES = {"pom.xml", "build.gradle", "build.gradle.kts"}
+GITLAB_CI_ENTRY_FILES = {".gitlab-ci.yml", ".gitlab-ci.yaml"}
 CRITICAL_CONFIRM_TRANSITIONS = {
     ("ANALYSIS", "IMPLEMENT"),
     ("VERIFICATION", "MEMORY"),
@@ -399,7 +408,11 @@ def read_project_behavior(root: Path) -> tuple[str, str, bool, int]:
             "expected adaptive, fast, standard, or strict."
         )
     if schema_version >= 4:
-        tdd_enabled = parse_yaml_bool(behavior.get("tdd_enabled"), "behavior.tdd_enabled")
+        tdd_enabled = (
+            parse_yaml_bool(behavior.get("tdd_enabled"), "behavior.tdd_enabled")
+            if schema_version >= 5
+            else DEFAULT_TDD_ENABLED
+        )
         tdd_threshold = parse_tdd_threshold(
             behavior.get("tdd_coverage_threshold", DEFAULT_TDD_COVERAGE_THRESHOLD),
             "behavior.tdd_coverage_threshold",
@@ -410,6 +423,175 @@ def read_project_behavior(root: Path) -> tuple[str, str, bool, int]:
     return approval_mode, workflow_mode, tdd_enabled, tdd_threshold
 
 
+def safe_tdd_report_pattern(value: object) -> bool:
+    if not is_non_empty_string(value):
+        return False
+    candidate = Path(str(value))
+    return not candidate.is_absolute() and ".." not in candidate.parts
+
+
+def tdd_gate_uses_task_variables(command: object) -> bool:
+    if not is_non_empty_string(command):
+        return False
+    try:
+        tokens = shlex.split(str(command))
+    except ValueError:
+        return False
+    options: dict[str, str] = {}
+    for index, token in enumerate(tokens[:-1]):
+        if token in {"--base", "--threshold"}:
+            options[token] = tokens[index + 1]
+    return options.get("--base") in {
+        f"${TDD_BASE_VARIABLE}",
+        "$" + "{" + TDD_BASE_VARIABLE + "}",
+    } and options.get("--threshold") in {
+        f"${TDD_THRESHOLD_VARIABLE}",
+        "$" + "{" + TDD_THRESHOLD_VARIABLE + "}",
+    }
+
+
+def tdd_ci_contract_reasons(contents: list[str]) -> list[str]:
+    combined = "\n".join(
+        re.sub(r"\s+#.*$", "", re.sub(r"^\s*#.*$", "", line))
+        for line in "\n".join(contents).splitlines()
+    )
+    lowered = combined.lower()
+    reasons: list[str] = []
+    for marker in (
+        "jacoco",
+        "artifacts",
+        COVERAGE_TOOL_PATH,
+        TDD_BASE_VARIABLE,
+        TDD_THRESHOLD_VARIABLE,
+    ):
+        if marker.lower() not in lowered:
+            reasons.append(f"CI files do not contain required marker: {marker}")
+    if not tdd_gate_uses_task_variables(combined):
+        reasons.append(
+            "CI changed-line gate must use the task baseline and threshold variables"
+        )
+    if re.search(
+        r"(?:^|\n)\s*stage\s*:\s*['\"]?test['\"]?\s*(?:#.*)?(?:\n|$)",
+        combined,
+        re.IGNORECASE,
+    ) is None:
+        reasons.append("CI files do not declare a TEST-stage job")
+    return reasons
+
+
+def tdd_readiness(root: Path) -> dict[str, object]:
+    receipt = root / TDD_READINESS_PATH
+    if not receipt.is_file():
+        return {"status": "needs_init", "reasons": ["TDD readiness receipt is missing"]}
+    try:
+        manifest = json.loads(receipt.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return {"status": "needs_init", "reasons": ["TDD readiness receipt is invalid"]}
+    if not isinstance(manifest, dict):
+        return {
+            "status": "needs_init",
+            "reasons": ["TDD readiness receipt must be a JSON object"],
+        }
+
+    reasons: list[str] = []
+    if manifest.get("schema") != TDD_READINESS_SCHEMA:
+        reasons.append("unsupported readiness schema")
+    if manifest.get("provider") != "gitlab":
+        reasons.append("readiness provider must be gitlab")
+    if manifest.get("coverage_scope") != TDD_READINESS_SCOPE:
+        reasons.append("coverage scope must be changed-production-lines")
+    if manifest.get("historical_coverage_required") is not False:
+        reasons.append("historical coverage must remain disabled")
+    reports = manifest.get("coverage_report_patterns")
+    if not isinstance(reports, list) or not reports or not all(
+        safe_tdd_report_pattern(item) for item in reports
+    ):
+        reasons.append(
+            "coverage_report_patterns must contain safe project-relative report patterns"
+        )
+    gate = manifest.get("changed_line_gate_command")
+    if not is_non_empty_string(gate) or COVERAGE_TOOL_PATH not in str(gate):
+        reasons.append("changed-line coverage gate command is missing")
+    elif not tdd_gate_uses_task_variables(gate):
+        reasons.append(
+            "changed-line coverage gate must use the task baseline and threshold variables"
+        )
+
+    contents: dict[str, list[str]] = {
+        "build_files": [],
+        "ci_files": [],
+        "tool_files": [],
+    }
+    for field in contents:
+        records = manifest.get(field)
+        if not isinstance(records, list) or not records:
+            reasons.append(f"{field} must contain at least one file")
+            continue
+        for record in records:
+            if not isinstance(record, dict):
+                reasons.append(f"{field} contains an invalid record")
+                continue
+            file_name = record.get("path")
+            expected = record.get("sha256")
+            if not is_non_empty_string(file_name) or not re.fullmatch(
+                r"[a-f0-9]{64}", str(expected or "")
+            ):
+                reasons.append(f"{field} contains an invalid path or SHA-256")
+                continue
+            candidate = Path(str(file_name))
+            if candidate.is_absolute():
+                reasons.append(f"readiness file must be project-relative: {file_name}")
+                continue
+            resolved = (root / candidate).resolve()
+            try:
+                resolved.relative_to(root.resolve())
+                payload = resolved.read_bytes()
+                contents[field].append(payload.decode("utf-8"))
+                if hashlib.sha256(payload).hexdigest() != expected:
+                    reasons.append(f"readiness file changed: {file_name}")
+            except (OSError, UnicodeError, ValueError):
+                reasons.append(f"readiness file is missing or unreadable: {file_name}")
+
+    manifest_build_files = manifest.get("build_files")
+    manifest_ci_files = manifest.get("ci_files")
+    manifest_tool_files = manifest.get("tool_files")
+    build_paths = {
+        Path(str(item.get("path", ""))).name
+        for item in manifest_build_files
+        if isinstance(item, dict) and is_non_empty_string(item.get("path"))
+    } if isinstance(manifest_build_files, list) else set()
+    ci_paths = {
+        str(item.get("path", "")).replace("\\", "/")
+        for item in manifest_ci_files
+        if isinstance(item, dict) and is_non_empty_string(item.get("path"))
+    } if isinstance(manifest_ci_files, list) else set()
+    if not build_paths.intersection(JAVA_BUILD_FILE_NAMES):
+        reasons.append("build_files must include a Maven or Gradle Java build file")
+    if not ci_paths.intersection(GITLAB_CI_ENTRY_FILES):
+        reasons.append("ci_files must include the project-root GitLab CI entry file")
+    tool_paths = {
+        str(item.get("path", "")).replace("\\", "/")
+        for item in manifest_tool_files
+        if isinstance(item, dict) and is_non_empty_string(item.get("path"))
+    } if isinstance(manifest_tool_files, list) else set()
+    if COVERAGE_TOOL_PATH not in tool_paths:
+        reasons.append(f"tool_files must include {COVERAGE_TOOL_PATH}")
+    if not any("jacoco" in content.lower() for content in contents["build_files"]):
+        reasons.append("build files do not configure JaCoCo")
+    reasons.extend(tdd_ci_contract_reasons(contents["ci_files"]))
+    return {
+        "status": "ready" if not reasons else "needs_init",
+        "reasons": list(dict.fromkeys(reasons)),
+    }
+
+
+def require_tdd_readiness(root: Path) -> None:
+    readiness = tdd_readiness(root)
+    if readiness["status"] != "ready":
+        reasons = "; ".join(str(reason) for reason in readiness["reasons"])
+        raise StateError(f"TDD cannot be enabled before ec-tdd-init succeeds: {reasons}")
+
+
 def resolve_behavior(
     root: Path, session: dict
 ) -> tuple[str, str | None, str, str, str | None, str, bool, bool | None, bool, int, int | None, int]:
@@ -2344,6 +2526,13 @@ def validate_verification_readiness(root: Path, task_id: str, task: dict) -> Non
             and record.get("config_fingerprint") == fingerprints["config_fingerprint"]
             and is_non_empty_string(record.get("check"))
         ):
+            if (
+                task.get("tdd_enabled") is True
+                and record.get("check_type") == "coverage"
+                and record.get("coverage_scope") == "gitlab"
+            ):
+                # 远程 CI 只作为生成的自动化能力，历史 pending/failed 记录不再参与本地验收。
+                continue
             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 ''}"
@@ -2411,6 +2600,13 @@ 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 str(task.get("type") or "").strip().lower() == TDD_INIT_TASK_TYPE:
+        readiness = tdd_readiness(root)
+        if readiness["status"] != "ready":
+            raise StateError(
+                "TDD initialization cannot advance to MEMORY until readiness passes: "
+                + "; ".join(str(reason) for reason in readiness["reasons"])
+            )
     if task.get("tdd_enabled") is not True and any(
         record.get("check_type") == "coverage" for record in latest_by_check.values()
     ):
@@ -2418,6 +2614,13 @@ def validate_verification_readiness(root: Path, task_id: str, task: dict) -> Non
             "Coverage verification evidence is not allowed when the frozen TDD mode is off."
         )
     if task.get("tdd_enabled") is True:
+        require_tdd_readiness(root)
+        test_records = [
+            record
+            for record in latest_by_check.values()
+            if record.get("check_type") == "test"
+            and record.get("applicable") is not False
+        ]
         coverage_records = [
             record
             for record in latest_by_check.values()
@@ -2428,6 +2631,17 @@ def validate_verification_readiness(root: Path, task_id: str, task: dict) -> Non
                 "TDD verification requires changed-production-line JaCoCo coverage evidence."
             )
         if is_spec_task:
+            tested_source_tasks = {
+                str(record.get("source_task_id") or "") for record in test_records
+            }
+            missing_test_tasks = sorted(
+                set(task_repositories) - tested_source_tasks
+            )
+            if missing_test_tasks:
+                raise StateError(
+                    "TDD Canonical verification requires local unit-test evidence for every selected source task: "
+                    + ", ".join(missing_test_tasks)
+                )
             covered_source_tasks = {
                 str(record.get("source_task_id") or "") for record in coverage_records
             }
@@ -2439,19 +2653,16 @@ def validate_verification_readiness(root: Path, task_id: str, task: dict) -> Non
                     "TDD Canonical verification requires separate coverage evidence for every selected source task: "
                     + ", ".join(missing_coverage_tasks)
                 )
-        coverage_scopes_by_owner: dict[str, set[str]] = {}
+        elif not test_records:
+            raise StateError(
+                "TDD verification requires passed local unit-test evidence."
+            )
         for record in coverage_records:
             scope = str(record.get("coverage_scope") or "")
-            if scope not in {"local", "gitlab"}:
+            if scope != "local":
                 raise StateError(
-                    "TDD coverage evidence must identify coverage_scope as local or gitlab."
+                    "TDD coverage evidence must identify coverage_scope as local."
                 )
-            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 (
@@ -2466,18 +2677,6 @@ def validate_verification_readiness(root: Path, task_id: str, task: dict) -> Non
             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")
@@ -2532,18 +2731,6 @@ def validate_verification_readiness(root: Path, task_id: str, task: dict) -> Non
                 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]] = {
@@ -2826,7 +3013,7 @@ def validate_analysis_readiness(
     test_strategy = task_dir / "test-strategy.md"
     reasons: list[str] = []
     behavior = resolve_behavior(root, session or default_session())
-    tdd_enabled = behavior[8]
+    tdd_enabled = behavior[8] if task_type != TDD_INIT_TASK_TYPE else False
     tdd_threshold = behavior[11]
 
     dev_spec_content = ""
@@ -2875,6 +3062,12 @@ def validate_analysis_readiness(
     if not plan_is_valid:
         reasons.append("execution.jsonl has no valid plan record")
     if tdd_enabled and not is_read_only_task:
+        readiness = tdd_readiness(root)
+        if readiness["status"] != "ready":
+            reasons.append(
+                "TDD infrastructure is not ready; run ec-tdd-init first: "
+                + "; ".join(str(reason) for reason in readiness["reasons"])
+            )
         plan = latest_execution_plan(root, task_id) or {}
         if re.search(
             r"^###\s+TDD Mode\s*$", dev_spec_content, re.MULTILINE | re.IGNORECASE
@@ -2902,7 +3095,13 @@ def validate_analysis_readiness(
             strategy_content = test_strategy.read_text(encoding="utf-8")
         except OSError:
             strategy_content = ""
-        required_tdd_markers = ["TDD", "JaCoCo", "baseline", "GitLab"]
+        required_tdd_markers = [
+            "TDD",
+            "JaCoCo",
+            "baseline",
+            "local_test_gate: required",
+            "remote_ci_acceptance: non-blocking",
+        ]
         missing_tdd_markers = [
             marker for marker in required_tdd_markers if marker.lower() not in strategy_content.lower()
         ]
@@ -2924,6 +3123,32 @@ def validate_analysis_readiness(
                     dev_spec_content, strategy_content, baselines
                 )
             )
+    elif task_type == TDD_INIT_TASK_TYPE:
+        try:
+            strategy_content = test_strategy.read_text(encoding="utf-8")
+        except OSError:
+            strategy_content = ""
+        required_init_markers = [
+            "JaCoCo",
+            "GitLab",
+            "changed production lines",
+            "historical coverage required: no",
+            "easy_coding_tdd_readiness.py",
+        ]
+        missing_init_markers = [
+            marker
+            for marker in required_init_markers
+            if marker.lower() not in strategy_content.lower()
+        ]
+        if missing_init_markers:
+            reasons.append(
+                "TDD initialization strategy is missing: "
+                + ", ".join(missing_init_markers)
+            )
+        if re.search(
+            r"^###\s+TDD Mode\s*$", dev_spec_content, re.MULTILINE | re.IGNORECASE
+        ):
+            reasons.append("tdd-init must keep TDD off and omit the TDD Mode section")
     elif not is_read_only_task:
         if re.search(
             r"^###\s+TDD Mode\s*$", dev_spec_content, re.MULTILINE | re.IGNORECASE
@@ -3254,12 +3479,25 @@ def snapshot_state(
         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
+    is_tdd_init = bool(
+        task and str(task.get("type") or "").strip().lower() == TDD_INIT_TASK_TYPE
+    )
+    displayed_tdd_enabled = (
+        False if is_tdd_init else 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
     )
+    should_check_readiness = bool(
+        effective_tdd_enabled or task_tdd_enabled is True or is_tdd_init
+    )
+    readiness = (
+        tdd_readiness(root)
+        if should_check_readiness
+        else {"status": "not_checked", "reasons": []}
+    )
 
     return {
         "session_file": display_path(root, session_path),
@@ -3291,6 +3529,8 @@ def snapshot_state(
         "task_tdd_baselines": task.get("tdd_baselines") if task else None,
         "displayed_tdd_enabled": displayed_tdd_enabled,
         "displayed_tdd_coverage_threshold": displayed_tdd_threshold,
+        "tdd_readiness_status": readiness["status"],
+        "tdd_readiness_reasons": readiness["reasons"],
         "spec_summary": spec_task_summary(task),
         # Compatibility output aliases for pre-0.9 clients.
         "project_confirm_mode": project_approval_mode,
@@ -3674,6 +3914,8 @@ def set_session_tdd(
     threshold: int | None = None,
     session_file: str | Path | None = None,
 ) -> dict:
+    if enabled:
+        require_tdd_readiness(root)
     session = ensure_session(root, session_file)
     materialize_legacy_session_behavior(session)
     session["tdd_enabled"] = enabled
@@ -4139,9 +4381,14 @@ def freeze_tdd_mode(
 ) -> 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_enabled"] = (
+        behavior[8]
+        if task_type not in NO_CODE_TASK_TYPES | {TDD_INIT_TASK_TYPE}
+        else False
+    )
     task["tdd_coverage_threshold"] = behavior[11]
     if task["tdd_enabled"] is True:
+        require_tdd_readiness(root)
         plan = latest_execution_plan(root, task_id)
         if plan is None:
             raise StateError("Cannot freeze TDD baseline without a valid execution plan.")