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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "easy-coding-harness",
-  "version": "0.10.0-beta.1",
+  "version": "0.10.0-beta.2",
   "description": "CLI scaffold for installing Easy Coding harness files into agent-native directories.",
   "repository": {
     "type": "git",

package/templates/common/bundled-skills/ec-init/SKILL.md

@@ -85,9 +85,11 @@ initialization standard. Check each item:
   and non-empty?
 - **Project profile**: `project.yaml` exists with `mode` and `test` fields (ec-init owns it;
   `config.yaml` is CLI-owned — not ec-init's concern)?
-- **TDD runtime contract**: CLI-owned `config.yaml` has schema 4 TDD defaults and
-  `.easy-coding/tools/easy_coding_java_coverage.py` exists? Missing fields or tool mean
-  `easy-coding upgrade` is required; ec-init must not repair them directly.
+- **TDD runtime contract**: CLI-owned `config.yaml` has schema 5 TDD defaults and both
+  `.easy-coding/tools/easy_coding_java_coverage.py` and
+  `.easy-coding/tools/easy_coding_tdd_readiness.py` exist? Missing fields or tools mean
+  `easy-coding upgrade` is required; ec-init must not repair them directly. Project-specific
+  JaCoCo/GitLab readiness remains owned by `ec-tdd-init`, not `ec-init`.
 - **Platform hook config freshness**: for each installed platform in `.easy-coding/config.yaml`,
   read the platform hook config and verify managed Easy Coding hook commands use the portable
   relative hook launcher bound to this project root's `project.id`. If `project.id` is missing,

package/templates/common/bundled-skills/ec-meta/references/platform-files/README.md

@@ -14,7 +14,7 @@ What lives in each platform directory and how the three platforms differ.
 | Sub-agent defs | `.claude/agents/*.md` | `.codex/agents/*.toml` | `.qoder/agents/*.md` |
 | CN variant | — | — | `.qodercn/` |
 
-Each skill is installed as `{skills-dir}/ec-{name}/SKILL.md`. The 14 skills are
+Each skill is installed as `{skills-dir}/ec-{name}/SKILL.md`. The 15 skills are
 platform-agnostic — one template, resolved per platform at write time. The agent's native
 discovery surfaces them under `/ec-` or `$ec-`.
 

package/templates/common/skills/ec-analysis/SKILL.md

@@ -96,8 +96,14 @@ Code tasks require `test-strategy.md`; explicit `doc`, `analysis`, and `report`
 ## Optional Java TDD analysis
 
 Read `effective_tdd_enabled` and `effective_tdd_coverage_threshold` from the state snapshot.
+For a `type=tdd-init` task, treat frozen TDD as off even if the project/session requests it. That
+task is the sole exception allowed to inspect and plan build/CI coverage infrastructure while TDD
+is off. Its scope is infrastructure only: never plan historical business-test backfill or a
+repository-wide coverage target, and explicitly record `coverage scope: changed production lines`.
+
 When TDD is disabled, stop here: do not inspect GitLab CI or JaCoCo, do not add TDD fields or
-extra tests, and do not strengthen the selected Workflow Mode's ordinary acceptance depth.
+extra tests, and do not strengthen the selected Workflow Mode's ordinary acceptance depth. This
+zero-cost rule applies to ordinary tasks, not the explicit `tdd-init` infrastructure task above.
 
 When TDD is enabled for a Java code task, make `test-strategy.md` record:
 
@@ -110,6 +116,8 @@ When TDD is enabled for a Java code task, make `test-strategy.md` record:
 - `.gitlab-ci.yml` and included configuration, the TEST-stage job, JUnit/JaCoCo artifacts, and an
   equivalent changed-line gate. Reuse a gate only when its threshold is at least the configured
   value; otherwise include the CI change in the confirmed implementation scope.
+- current `tdd_readiness_status=ready`; if missing or drifted, stop before IMPLEMENT and route to
+  `ec-tdd-init`. Never plan to initialize CI inside an already-enabled TDD feature task.
 
 The state API mechanically freezes current Git `HEAD` per repository into `task.tdd_baselines`
 when ANALYSIS advances to IMPLEMENT. Plan both local and GitLab commands with that exact SHA and

package/templates/common/skills/ec-config/SKILL.md

@@ -18,7 +18,15 @@ Call `snapshot` and show project, session, effective, and frozen task values for
 
 Use the returned fields directly, including `project_tdd_enabled`, `session_tdd_enabled`,
 `effective_tdd_enabled`, their threshold counterparts, `task_tdd_enabled`, and the task's
-per-repository `task_tdd_baselines` frozen state.
+per-repository `task_tdd_baselines` frozen state. When `tdd_readiness_status=not_checked` because
+TDD is off, explicitly run the read-only readiness command below before showing readiness:
+
+```bash
+python3 .easy-coding/tools/easy_coding_tdd_readiness.py --cwd . check
+```
+
+This explicit configuration-panel check is the only disabled-mode readiness scan; ordinary hooks
+must not inspect build or CI files while TDD is off.
 
 Explain precedence as `session override > project config > defaults`. Defaults are Approval
 `guard`, Workflow `adaptive`, TDD disabled, and TDD changed-line coverage threshold 90%. An active
@@ -29,6 +37,7 @@ changes affect future tasks and ANALYSIS only.
 
 Use `easy-coding config` for project settings. The CLI confirms one atomic update of Approval,
 Workflow, TDD, and (when enabled) the threshold. The threshold must be an integer from 1 to 100.
+Enabling TDD is rejected atomically unless `ec-tdd-init` readiness is currently `ready`.
 
 ## Session configuration
 
@@ -52,3 +61,8 @@ Turning TDD off must preserve the existing Fast/Standard/Strict test depth exact
 CI, request JaCoCo, add TDD artifacts, run coverage commands, or strengthen acceptance criteria.
 When TDD is on, explain that it applies only to Java code tasks and activates RED/GREEN/REFACTOR,
 TDD review, local changed-line JaCoCo coverage, and GitLab TEST-stage gate planning.
+
+Before any project/session enable action, require `tdd_readiness_status=ready`. If it is not ready,
+offer only `ec-tdd-init` or cancellation; never offer or persist "enable now, initialize later".
+Readiness means infrastructure can measure future changed production lines. It does not certify
+repository-wide coverage and does not require tests for unchanged historical code.

package/templates/common/skills/ec-tdd-init/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: ec-tdd-init
+description: Initialize or refresh Java changed-line TDD coverage infrastructure before TDD can be enabled.
+---
+
+# ec-tdd-init — Java changed-line gate initialization
+
+Communicate in the user's language. This skill owns TDD infrastructure readiness, not historical
+test-debt cleanup. It must never bulk-generate tests for existing business code, require
+repository-wide coverage, or modify production behavior merely to raise coverage.
+
+## Non-circular ordering
+
+The only legal order is:
+
+```text
+TDD off -> initialize infrastructure -> readiness ready -> user explicitly enables TDD
+```
+
+Run this skill as a dedicated code task with `type=tdd-init`. The state API always freezes that
+task with `tdd_enabled=false`, even when a legacy project/session setting or a suspended task has
+TDD enabled. Never offer "enable now and initialize later". Never enable TDD automatically after
+initialization.
+
+## Read-only preflight
+
+First run:
+
+```bash
+python3 .easy-coding/tools/easy_coding_tdd_readiness.py --cwd . check
+```
+
+If it returns `ready`, report the recorded build/CI contract and stop without creating a task.
+The user may then use `ec-config` or `easy-coding config` to enable TDD.
+
+If it returns `needs_init`, inspect only the infrastructure needed to form a confirmed plan:
+
+- Maven/Gradle files and the existing JUnit runner;
+- JaCoCo XML generation configuration;
+- `.gitlab-ci.yml` and its repository-local include chain;
+- TEST-stage job, JUnit/JaCoCo artifacts, and invocation of
+  `.easy-coding/tools/easy_coding_java_coverage.py` with task-supplied baseline/threshold values.
+
+Do not measure current whole-project coverage. A project with no historical business tests may
+still become ready when the test runner, JaCoCo reporting, and parameterized changed-line gate
+are functional.
+
+## Initialization task
+
+After the user confirms the exact infrastructure scope, create one task and route it through the
+ordinary workflow:
+
+```bash
+{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py create-task \
+  --task-id <safe-unique-id> --type tdd-init \
+  --title "Initialize Java changed-line TDD infrastructure" \
+  --agent <agent-id> --session-file <P>
+```
+
+ANALYSIS may plan build files, GitLab CI files, common scripts, and the readiness receipt. It must
+state `historical coverage required: no` and `coverage scope: changed production lines since each
+future task baseline`. IMPLEMENT changes infrastructure only. It must not add tests whose sole
+purpose is to cover unchanged production code.
+
+The reusable GitLab job must consume a baseline SHA and threshold supplied for the future task;
+do not hardcode the initialization commit or the default 90% threshold. The same Python coverage
+tool must be used locally and remotely.
+
+## Readiness receipt and verification
+
+At the end of IMPLEMENT, after the infrastructure files are stable, record their fingerprints.
+The receipt is part of the implementation and must exist before REVIEW so review/verification
+fingerprints do not change after review. The recorder automatically includes the harness-managed
+`.easy-coding/tools/easy_coding_java_coverage.py` fingerprint:
+
+```bash
+python3 .easy-coding/tools/easy_coding_tdd_readiness.py --cwd . record \
+  --build-file <pom.xml-or-build.gradle> [--build-file <included-build-file>]... \
+  --ci-file .gitlab-ci.yml [--ci-file <repository-local-include>]... \
+  --coverage-report <jacoco-xml-pattern> [--coverage-report <pattern>]... \
+  --gate-command "python3 .easy-coding/tools/easy_coding_java_coverage.py check --base \$EASY_CODING_TDD_BASE_SHA --threshold \$EASY_CODING_TDD_THRESHOLD" \
+  --agent <agent-id>
+```
+
+REVIEW includes the receipt and its declared infrastructure boundary. VERIFICATION runs the
+frozen Workflow Mode's applicable build/test/CI syntax checks, then performs only the read-only
+readiness check:
+
+```bash
+python3 .easy-coding/tools/easy_coding_tdd_readiness.py --cwd . check
+```
+
+The `VERIFICATION -> MEMORY` gate requires the final check to return `ready`. If any recorded
+build or CI file changes after the receipt was created, readiness becomes `needs_init`; return to
+IMPLEMENT, refresh the receipt, and repeat REVIEW before verifying again. Rerun this skill when
+the same drift occurs after task completion.
+
+After completion, tell the user that TDD remains off and provide the explicit project/session
+enable route. Do not treat readiness as consent to enable it.

package/templates/common/skills/ec-verification/SKILL.md

@@ -26,7 +26,9 @@ Read-only tasks never enter this stage. Obtain fresh fingerprints before running
 - `strict`: run the project's full applicable lint, typecheck, test, and build gates.
 
 These rules remain unchanged when frozen TDD is off: do not discover JaCoCo reports, run the
-coverage tool, inspect GitLab, or add a coverage record.
+coverage tool, inspect GitLab, or add a coverage record. The explicit `type=tdd-init` task is an
+infrastructure exception: run its planned build/CI syntax checks and readiness tool, but do not
+measure repository-wide coverage or append TDD coverage evidence for unchanged production code.
 
 When frozen TDD is on, first run the planned Java unit command and generate JaCoCo XML, then run
 the same deterministic gate intended for GitLab:
@@ -102,6 +104,12 @@ appended only after the remote job succeeds and must also include:
 Both records must preserve the same task-frozen baseline and threshold. A local-only result,
 pending/failed pipeline, missing job identity, or synthetic remote pass cannot satisfy MEMORY.
 
+For `type=tdd-init`, the infrastructure receipt must already have been recorded during IMPLEMENT
+and reviewed with the rest of the implementation. Run only `easy_coding_tdd_readiness.py check`
+here. If it reports drift, return to IMPLEMENT to refresh the receipt and repeat REVIEW; never
+rewrite it inside VERIFICATION. The state gate requires `ready` before MEMORY. This does not
+enable TDD; report the explicit `ec-config`/`easy-coding config` next step.
+
 - Every must-test item has an executed check.
 - Bug fixes include a regression test when project infrastructure exists.
 - Present changed scope, commands, results, and unverified items.

package/templates/common/skills/ec-workflow/SKILL.md

@@ -39,8 +39,11 @@ selection and reasons, allows the user to change it within the risk floor, and f
 ANALYSIS -> IMPLEMENT is applied.
 
 TDD resolves with the same session-over-project precedence and freezes its enabled flag and
-threshold on ANALYSIS -> IMPLEMENT. When off, it must add no CI scan, artifacts, commands,
-coverage work, or stronger acceptance. Use `ec-config` for all mode configuration.
+threshold on ANALYSIS -> IMPLEMENT. It may be enabled only after `ec-tdd-init` readiness passes;
+there is no enabled-but-pending-initialization state. A dedicated `tdd-init` task always freezes
+TDD off so it can create or repair the required infrastructure without circular gating. When off,
+ordinary tasks add no CI scan, artifacts, commands, coverage work, or stronger acceptance. Use
+`ec-config` for all mode configuration.
 
 `confirm` and `auto` do not hide the proposal: show it in the plan. Confirm waits for that one
 plan decision; Auto continues immediately. Both remove later waiting, not quality gates.
@@ -87,7 +90,10 @@ plan decision; Auto continues immediately. Both remove later waiting, not qualit
 
    When multiple selected tasks depend on the same target, disambiguate creation evidence with
    `<source-task-id>-><dependency-task-id>=<evidence>`.
-4. Match the user's intent against `current_task` and the active task list before resuming.
+4. When the user explicitly invokes `ec-tdd-init`, let that skill own preflight and create a
+   `type=tdd-init` code task only after scope confirmation. Do not reinterpret it as an ordinary
+   TDD-enabled feature task and do not require readiness before creating it.
+5. Match the user's intent against `current_task` and the active task list before resuming.
    If the user names or clearly matches another task, confirm the switch and call
    `claim-task --task-id <id> --agent <agent-id> --session-file <P>`. Do not execute task A
    under task B's request.
@@ -99,10 +105,10 @@ plan decision; Auto continues immediately. Both remove later waiting, not qualit
      to the requested deliverable. Feature, bugfix, refactor, performance, and workflow changes
      are code tasks. Use `doc`, `analysis`, or `report` only when the user explicitly requested
      a no-code deliverable; never downgrade a code request to the read-only completion path.
-5. Resume the matched/current task, then load only state-relevant assets. Do not read five full
+6. Resume the matched/current task, then load only state-relevant assets. Do not read five full
    memories at every startup; ANALYSIS searches memory metadata and opens relevant entries on
    demand.
-6. If another Agent last owned the task, summarize the stored handoff before continuing.
+7. If another Agent last owned the task, summarize the stored handoff before continuing.
 
 ## Stage dispatch
 

package/templates/main-constraint/AGENTS.md.tpl

@@ -33,7 +33,7 @@ Trigger Easy Coding skills with your platform prefix — Codex: `$ec-*`, Qoder:
 - `ec-brainstorming` — design exploration before building (hard design gate)
 - `ec-analysis` `ec-implementing` `ec-reviewing` `ec-verification` — workflow stages
 - `ec-memory` — short/long memory archive
-- `ec-task-management` — task lifecycle panel · `ec-config` — Approval/Workflow/TDD settings · `ec-task-close` — interrupt a task
+- `ec-task-management` — task lifecycle panel · `ec-config` — Approval/Workflow/TDD settings · `ec-tdd-init` — Java changed-line gate initialization · `ec-task-close` — interrupt a task
 - `ec-no-harness` — bypass only Easy Coding for the current session
 - `ec-git` — git discipline · `ec-meta` — understand/customize the harness
 
@@ -49,9 +49,12 @@ First run `ec-init`; daily work goes through `ec-workflow`.
   evidence gates.
 - TDD is session override > project `behavior.tdd_enabled` > `false`; its changed-line threshold
   is session override > project `behavior.tdd_coverage_threshold` > `90`. ANALYSIS -> IMPLEMENT
-  freezes both. Disabled TDD adds no CI scan, JaCoCo work, commands, artifacts, or stronger gates.
-  Enabled TDD applies only to Java code tasks and requires lifecycle, review, local coverage, and
-  GitLab TEST-stage gate evidence.
+  freezes both. TDD may be enabled only after `ec-tdd-init` records valid infrastructure readiness;
+  there is no enable-now/init-later state. The dedicated `tdd-init` task always freezes TDD off and
+  initializes only changed-line coverage infrastructure, never historical business-test coverage.
+  Disabled TDD adds no CI scan, JaCoCo work, commands, artifacts, or stronger gates. Enabled TDD
+  applies only to Java code tasks and requires lifecycle, review, local coverage, and GitLab
+  TEST-stage evidence for production lines changed since the task baseline.
 - Confirmation-required edges use `pending_transition`; automatic edges use the restricted
   `auto-transition` API. A read-only task creates no test-strategy.md, never enters REVIEW,
   VERIFICATION, or MEMORY, and writes no task memory.

package/templates/main-constraint/CLAUDE.md.tpl

@@ -31,7 +31,7 @@ platform prefixes such as `/` or `$`. If no status line is injected, do not inve
 - `/ec-brainstorming` — design exploration before building (hard design gate)
 - `/ec-analysis` `/ec-implementing` `/ec-reviewing` `/ec-verification` — workflow stages
 - `/ec-memory` — short/long memory archive
-- `/ec-task-management` — task lifecycle panel · `/ec-config` — Approval/Workflow/TDD settings · `/ec-task-close` — interrupt a task
+- `/ec-task-management` — task lifecycle panel · `/ec-config` — Approval/Workflow/TDD settings · `/ec-tdd-init` — Java changed-line gate initialization · `/ec-task-close` — interrupt a task
 - `/ec-no-harness` — bypass only Easy Coding for the current session
 - `/ec-git` — git discipline · `/ec-meta` — understand/customize the harness
 
@@ -47,9 +47,12 @@ First run `/ec-init`; daily work goes through `/ec-workflow`.
   evidence gates.
 - TDD is session override > project `behavior.tdd_enabled` > `false`; its changed-line threshold
   is session override > project `behavior.tdd_coverage_threshold` > `90`. ANALYSIS -> IMPLEMENT
-  freezes both. Disabled TDD adds no CI scan, JaCoCo work, commands, artifacts, or stronger gates.
-  Enabled TDD applies only to Java code tasks and requires lifecycle, review, local coverage, and
-  GitLab TEST-stage gate evidence.
+  freezes both. TDD may be enabled only after `ec-tdd-init` records valid infrastructure readiness;
+  there is no enable-now/init-later state. The dedicated `tdd-init` task always freezes TDD off and
+  initializes only changed-line coverage infrastructure, never historical business-test coverage.
+  Disabled TDD adds no CI scan, JaCoCo work, commands, artifacts, or stronger gates. Enabled TDD
+  applies only to Java code tasks and requires lifecycle, review, local coverage, and GitLab
+  TEST-stage evidence for production lines changed since the task baseline.
 - Confirmation-required edges use `pending_transition`; automatic edges use the restricted
   `auto-transition` API. A read-only task creates no test-strategy.md, never enters REVIEW,
   VERIFICATION, or MEMORY, and writes no task memory.

package/templates/runtime/tools/easy_coding_tdd_readiness.py

@@ -0,0 +1,306 @@
+#!/usr/bin/env python3
+"""Record and verify Easy Coding Java TDD infrastructure readiness.
+
+This tool validates infrastructure only. It never measures repository-wide coverage and never
+creates business tests. Coverage acceptance remains scoped to production lines changed after a
+task's frozen baseline.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import shlex
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+SCHEMA = "easy-coding/tdd-readiness-v1"
+COVERAGE_SCOPE = "changed-production-lines"
+RECEIPT = 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"}
+
+
+class ReadinessError(RuntimeError):
+    pass
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def project_file(root: Path, value: str) -> tuple[str, Path]:
+    candidate = Path(value)
+    if candidate.is_absolute():
+        resolved = candidate.resolve()
+    else:
+        resolved = (root / candidate).resolve()
+    try:
+        relative = resolved.relative_to(root.resolve()).as_posix()
+    except ValueError as error:
+        raise ReadinessError(f"Path escapes project root: {value}") from error
+    if not resolved.is_file():
+        raise ReadinessError(f"Required file is missing: {relative}")
+    return relative, resolved
+
+
+def file_record(root: Path, value: str) -> dict[str, str]:
+    relative, resolved = project_file(root, value)
+    return {"path": relative, "sha256": sha256(resolved)}
+
+
+def safe_report_pattern(value: str) -> bool:
+    candidate = Path(value)
+    return bool(value.strip()) and not candidate.is_absolute() and ".." not in candidate.parts
+
+
+def required_gate_variables(command: str) -> bool:
+    try:
+        tokens = shlex.split(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 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 required_gate_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.I) is None:
+        reasons.append("CI files do not declare a TEST-stage job")
+    return reasons
+
+
+def parse_records(root: Path, value: object, field: str, reasons: list[str]) -> list[str]:
+    if not isinstance(value, list) or not value:
+        reasons.append(f"{field} must contain at least one file")
+        return []
+    contents: list[str] = []
+    for item in value:
+        if not isinstance(item, dict):
+            reasons.append(f"{field} contains an invalid record")
+            continue
+        file_name = item.get("path")
+        expected = item.get("sha256")
+        if not isinstance(file_name, str) or not isinstance(expected, str):
+            reasons.append(f"{field} contains an invalid path or SHA-256")
+            continue
+        try:
+            _, resolved = project_file(root, file_name)
+            if sha256(resolved) != expected:
+                reasons.append(f"readiness file changed: {file_name}")
+            contents.append(resolved.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError, ReadinessError) as error:
+            reasons.append(str(error))
+    return contents
+
+
+def inspect(root: Path) -> dict[str, object]:
+    receipt = root / RECEIPT
+    if not receipt.is_file():
+        return {
+            "status": "needs_init",
+            "coverage_scope": COVERAGE_SCOPE,
+            "reasons": ["TDD readiness receipt is missing"],
+            "receipt": RECEIPT.as_posix(),
+        }
+    try:
+        manifest = json.loads(receipt.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return {
+            "status": "needs_init",
+            "coverage_scope": COVERAGE_SCOPE,
+            "reasons": ["TDD readiness receipt is invalid"],
+            "receipt": RECEIPT.as_posix(),
+        }
+
+    reasons: list[str] = []
+    if not isinstance(manifest, dict):
+        reasons.append("TDD readiness receipt must be a JSON object")
+        manifest = {}
+    if manifest.get("schema") != SCHEMA:
+        reasons.append("unsupported readiness schema")
+    if manifest.get("provider") != "gitlab":
+        reasons.append("readiness provider must be gitlab")
+    if manifest.get("coverage_scope") != COVERAGE_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")
+    patterns = manifest.get("coverage_report_patterns")
+    if not isinstance(patterns, list) or not patterns or not all(
+        isinstance(item, str) and safe_report_pattern(item) for item in patterns
+    ):
+        reasons.append(
+            "coverage_report_patterns must contain safe project-relative report patterns"
+        )
+    gate = manifest.get("changed_line_gate_command")
+    if not isinstance(gate, str) or COVERAGE_TOOL_PATH not in gate:
+        reasons.append("changed-line coverage gate command is missing")
+    elif not required_gate_variables(gate):
+        reasons.append(
+            "changed-line coverage gate must use the task baseline and threshold variables"
+        )
+
+    manifest_build_files = manifest.get("build_files")
+    manifest_ci_files = manifest.get("ci_files")
+    manifest_tool_files = manifest.get("tool_files")
+    build_contents = parse_records(root, manifest_build_files, "build_files", reasons)
+    ci_contents = parse_records(root, manifest_ci_files, "ci_files", reasons)
+    parse_records(root, manifest_tool_files, "tool_files", reasons)
+    build_paths = {
+        Path(item.get("path", "")).name
+        for item in manifest_build_files
+        if isinstance(item, dict) and isinstance(item.get("path"), str)
+    } if isinstance(manifest_build_files, list) else set()
+    ci_paths = {
+        item.get("path", "").replace("\\", "/")
+        for item in manifest_ci_files
+        if isinstance(item, dict) and isinstance(item.get("path"), str)
+    } 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 = {
+        item.get("path", "").replace("\\", "/")
+        for item in manifest_tool_files
+        if isinstance(item, dict) and isinstance(item.get("path"), str)
+    } 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 build_contents):
+        reasons.append("build files do not configure JaCoCo")
+    reasons.extend(ci_contract_reasons(ci_contents))
+
+    return {
+        "status": "ready" if not reasons else "needs_init",
+        "coverage_scope": COVERAGE_SCOPE,
+        "reasons": list(dict.fromkeys(reasons)),
+        "receipt": RECEIPT.as_posix(),
+    }
+
+
+def record(args: argparse.Namespace, root: Path) -> dict[str, object]:
+    if not args.build_file:
+        raise ReadinessError("At least one --build-file is required.")
+    if not args.ci_file:
+        raise ReadinessError("At least one --ci-file is required.")
+    if not args.coverage_report:
+        raise ReadinessError("At least one --coverage-report is required.")
+    if not all(safe_report_pattern(value) for value in args.coverage_report):
+        raise ReadinessError("--coverage-report values must be safe project-relative patterns.")
+    if COVERAGE_TOOL_PATH not in args.gate_command:
+        raise ReadinessError(f"--gate-command must invoke {COVERAGE_TOOL_PATH}.")
+    if not required_gate_variables(args.gate_command):
+        raise ReadinessError(
+            "--gate-command must use $EASY_CODING_TDD_BASE_SHA and "
+            "$EASY_CODING_TDD_THRESHOLD."
+        )
+
+    build_records = [file_record(root, value) for value in args.build_file]
+    ci_records = [file_record(root, value) for value in args.ci_file]
+    tool_records = [file_record(root, COVERAGE_TOOL_PATH)]
+    if not any(Path(item["path"]).name in JAVA_BUILD_FILE_NAMES for item in build_records):
+        raise ReadinessError("--build-file must include pom.xml, build.gradle, or build.gradle.kts.")
+    if not any(item["path"] in GITLAB_CI_ENTRY_FILES for item in ci_records):
+        raise ReadinessError(
+            "--ci-file must include the project-root .gitlab-ci.yml or .gitlab-ci.yaml."
+        )
+    build_contents = [
+        (root / record_item["path"]).read_text(encoding="utf-8")
+        for record_item in build_records
+    ]
+    ci_contents = [
+        (root / record_item["path"]).read_text(encoding="utf-8") for record_item in ci_records
+    ]
+    if not any("jacoco" in content.lower() for content in build_contents):
+        raise ReadinessError("Build files must configure JaCoCo before readiness can be recorded.")
+    ci_reasons = ci_contract_reasons(ci_contents)
+    if ci_reasons:
+        raise ReadinessError("; ".join(ci_reasons))
+
+    manifest = {
+        "schema": SCHEMA,
+        "provider": "gitlab",
+        "coverage_scope": COVERAGE_SCOPE,
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "generated_by": args.agent,
+        "build_files": build_records,
+        "ci_files": ci_records,
+        "tool_files": tool_records,
+        "coverage_report_patterns": args.coverage_report,
+        "changed_line_gate_command": args.gate_command,
+        "historical_coverage_required": False,
+    }
+    receipt = root / RECEIPT
+    receipt.parent.mkdir(parents=True, exist_ok=True)
+    temporary = receipt.with_suffix(f".tmp-{os.getpid()}")
+    temporary.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    temporary.replace(receipt)
+    result = inspect(root)
+    if result["status"] != "ready":
+        raise ReadinessError("Recorded readiness receipt did not pass validation.")
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Easy Coding Java TDD readiness tool")
+    parser.add_argument("--cwd", default=".")
+    subcommands = parser.add_subparsers(dest="command", required=True)
+    subcommands.add_parser("check")
+    record_parser = subcommands.add_parser("record")
+    record_parser.add_argument("--build-file", action="append", default=[])
+    record_parser.add_argument("--ci-file", action="append", default=[])
+    record_parser.add_argument("--coverage-report", action="append", default=[])
+    record_parser.add_argument("--gate-command", required=True)
+    record_parser.add_argument("--agent", required=True)
+    args = parser.parse_args()
+    root = Path(args.cwd).resolve()
+    try:
+        result = inspect(root) if args.command == "check" else record(args, root)
+    except (OSError, UnicodeError, ReadinessError) as error:
+        print(json.dumps({"status": "needs_init", "reasons": [str(error)]}, ensure_ascii=False))
+        return 2
+    print(json.dumps(result, ensure_ascii=False))
+    return 0 if result["status"] == "ready" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())