@hunter-harness/workflow-harness 0.2.69 → 0.2.70

package/harness/bundles/general/claude-code/scripts/harness_gate.py

@@ -151,6 +151,11 @@ SOFT_GATE_SITES = frozenset({
 })
 GATE_WARNINGS_REL = Path("evidence") / "gate-warnings.ndjson"
 
+# Lifecycle order used to scope C9 scenario coverage by scenario ownerPhase.
+# A scenario owned by a later phase is deferred, not missing, at an earlier
+# phase close. Must stay a superset-ordering of hpf.VALID_OWNER_PHASES.
+SCENARIO_OWNER_PHASE_ORDER = ("plan", "run", "test", "review", "submit")
+
 
 def gate_severity_mode(project: Path, change_dir: Path | None = None) -> str:
     """Resolve gate severity mode: env > change gate-policy > project config.
@@ -367,7 +372,11 @@ def evaluate_projection_gate(
 def resolve_execution_root(main_project: Path, raw: str | None) -> Path:
     candidate = Path(raw).expanduser().resolve() if raw else main_project.resolve()
     if not candidate.is_dir():
-        raise ValueError(f"execution root not found: {candidate}")
+        raise ValueError(
+            f"execution root not found: {candidate} — --project takes a "
+            "filesystem path to the execution root (use '.' when running from "
+            "it), not the project name"
+        )
     top = _git_text(candidate, "rev-parse", "--show-toplevel")
     if not top:
         raise ValueError(f"execution root is not a git worktree: {candidate}")
@@ -1957,12 +1966,78 @@ def _sync_after_phase_close(project: Path, change_dir: Path) -> dict[str, Any]:
         }
 
 
-def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
+def _scenario_owner_phase_rank(owner_phase: str | None) -> int | None:
+    """Rank a scenario ownerPhase against the lifecycle order, None when unknown."""
+    if not owner_phase:
+        return None
+    normalized = str(owner_phase).strip().lower()
+    if normalized not in hpf.VALID_OWNER_PHASES:
+        return None
+    try:
+        return SCENARIO_OWNER_PHASE_ORDER.index(normalized)
+    except ValueError:
+        return None
+
+
+def _partition_scenarios_by_owner_phase(
+    scenarios: list[Any],
+    required_ids: set[str],
+    phase: str | None,
+) -> tuple[set[str], list[str]]:
+    """Split required scenarios into (due now, deferred to a later phase).
+
+    A scenario is deferred only when it declares an `ownerPhase` that ranks
+    strictly after the phase being closed. Scenarios without a usable
+    `ownerPhase` (legacy/v1 manifests) stay due, preserving old behaviour.
+    """
+    closing_rank = _scenario_owner_phase_rank(phase)
+    if closing_rank is None:
+        return set(required_ids), []
+    due: set[str] = set()
+    deferred: set[str] = set()
+    for scenario in scenarios:
+        if not isinstance(scenario, dict):
+            continue
+        scenario_id = str(scenario.get("id") or "").strip()
+        if scenario_id not in required_ids:
+            continue
+        owner_rank = _scenario_owner_phase_rank(scenario.get("ownerPhase"))
+        if owner_rank is not None and owner_rank > closing_rank:
+            deferred.add(scenario_id)
+        else:
+            due.add(scenario_id)
+    # IDs present in required_ids but absent from the scan stay due (defensive).
+    due |= required_ids - due - deferred
+    # A duplicated ID declaring two ownerPhases must fail closed: if any
+    # occurrence is due now, the scenario is due now.
+    deferred -= due
+    return due, sorted(deferred)
+
+
+def _deferred_hint(deferred_ids: list[str], phase: str | None) -> str:
+    """Append a note so callers never mistake a deferred scenario for a blocker."""
+    if not deferred_ids:
+        return ""
+    return (
+        f"（另有 {len(deferred_ids)} 个场景按 ownerPhase 移交后续阶段，"
+        f"未计入 {phase or '本'} 阶段要求: " + ", ".join(deferred_ids) + "）"
+    )
+
+
+def _validate_scenario_coverage(
+    change_dir: Path, phase: str | None = None
+) -> dict[str, Any]:
     """C9: validate all ledger-required scenarios are covered by ledger entries.
 
     Reads meta/scenario-manifest.json and evidence/verification-ledger.json.
     Returns ok=True when a legacy manifest is missing or all required scenarios
     are covered. A present but empty manifest is always invalid.
+
+    Phase scoping: when `phase` is given, only scenarios whose `ownerPhase`
+    is due by that phase are required to carry passing receipts. Scenarios
+    owned by a later phase (e.g. `ownerPhase=test` at `run` close) are
+    reported under `deferred` instead of blocking the close — this matches the
+    documented hand-off rule in harness-run/SKILL.md ("ownerPhase=test 按计划移交").
     """
     manifest_path = change_dir / "meta" / "scenario-manifest.json"
     if not manifest_path.is_file():
@@ -2010,6 +2085,9 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
     }
     if not required_ids:
         return {"ok": True, "code": "NO_LEDGER_REQUIRED_SCENARIOS"}
+    due_ids, deferred_ids = _partition_scenarios_by_owner_phase(
+        scenarios, required_ids, phase
+    )
     raw_schema_version = (
         manifest.get("schemaVersion") if isinstance(manifest, dict) else None
     )
@@ -2043,6 +2121,18 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
                 "missingMappings": missing_mappings,
             }
 
+    if not due_ids:
+        # Every required scenario is owned by a later phase — nothing is due
+        # at this close. Report the hand-off instead of blocking.
+        return {
+            "ok": True,
+            "code": "SCENARIO_COVERAGE_DEFERRED",
+            "covered": [],
+            "deferred": deferred_ids,
+            "ownerPhaseScope": phase,
+            "schemaVersion": schema_version,
+        }
+
     try:
         ledger, ledger_path = hl.load_ledger(change_dir)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
@@ -2050,14 +2140,16 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
             "ok": False,
             "code": "SCENARIO_COVERAGE_FAILED",
             "message": f"ledger unreadable: {exc}",
-            "missing": sorted(required_ids),
+            "missing": sorted(due_ids),
+            "deferred": deferred_ids,
         }
     if ledger is None or ledger_path is None:
         return {
             "ok": False,
             "code": "SCENARIO_COVERAGE_FAILED",
             "message": "ledger missing; cannot verify required scenario coverage",
-            "missing": sorted(required_ids),
+            "missing": sorted(due_ids),
+            "deferred": deferred_ids,
         }
     if schema_version >= 2:
         coverage_sets: dict[str, set[str]] = {
@@ -2137,8 +2229,8 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
                         )
 
         passed = coverage_sets["passed"]
-        missing = sorted(required_ids - bound)
-        unexecuted = sorted(required_ids - passed)
+        missing = sorted(due_ids - bound)
+        unexecuted = sorted(due_ids - passed)
         detail = {
             key: sorted(values & required_ids)
             for key, values in coverage_sets.items()
@@ -2147,6 +2239,8 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
             {
                 "missing": missing,
                 "unexecuted": unexecuted,
+                "deferred": deferred_ids,
+                "ownerPhaseScope": phase,
                 "attempts": {
                     scenario_id: sorted(values)
                     for scenario_id, values in sorted(attempts.items())
@@ -2162,6 +2256,7 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
                 "message": (
                     "required scenarios without exact passed execution receipts: "
                     + ", ".join(unexecuted)
+                    + _deferred_hint(deferred_ids, phase)
                 ),
                 **detail,
             }
@@ -2180,7 +2275,7 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
                 ids = entry.get("scenarioIds")
                 if isinstance(ids, list):
                     covered.update(str(i) for i in ids)
-    missing = sorted(required_ids - covered)
+    missing = sorted(due_ids - covered)
     if missing:
         return {
             "ok": False,
@@ -2188,13 +2283,18 @@ def _validate_scenario_coverage(change_dir: Path) -> dict[str, Any]:
             "message": (
                 "ledger-required scenarios without ledger entry: "
                 + ", ".join(missing)
+                + _deferred_hint(deferred_ids, phase)
             ),
             "missing": missing,
+            "deferred": deferred_ids,
+            "ownerPhaseScope": phase,
         }
     return {
         "ok": True,
         "code": "SCENARIO_COVERAGE_OK",
         "covered": sorted(covered & required_ids),
+        "deferred": deferred_ids,
+        "ownerPhaseScope": phase,
     }
 
 
@@ -2888,9 +2988,11 @@ def cmd_close(args: argparse.Namespace) -> int:
                 },
             )
 
-    # C9: scenario coverage check — all P0 scenarios must have a ledger entry.
+    # C9: scenario coverage check — every P0/ledger scenario *due by this phase*
+    # must have a ledger entry. Scenarios with a later ownerPhase are deferred,
+    # not missing (see _validate_scenario_coverage).
     if args.phase in {"run", "test"}:
-        coverage = _validate_scenario_coverage(change_dir)
+        coverage = _validate_scenario_coverage(change_dir, args.phase)
         if not coverage.get("ok"):
             if gate_soft_allowed(severity_mode, args.phase, "scenario-coverage"):
                 gate_warnings.append(record_gate_warning(
@@ -3284,7 +3386,14 @@ def build_parser() -> argparse.ArgumentParser:
     p_begin = sub.add_parser("begin", parents=[shared])
     p_begin.add_argument("--phase", required=True)
     p_begin.add_argument("--change", default=None)
-    p_begin.add_argument("--project", default=None)
+    p_begin.add_argument(
+        "--project",
+        default=None,
+        help=(
+            "execution root PATH (worktree) for this phase; defaults to the "
+            "change's main project. Takes a path, not a project name."
+        ),
+    )
     p_begin.add_argument("--skills-root", default=None)
     p_begin.add_argument("--run-id", default=None)
     p_begin.add_argument("--ttl-seconds", type=int, default=3600)
@@ -3298,7 +3407,14 @@ def build_parser() -> argparse.ArgumentParser:
     p_close = sub.add_parser("close", parents=[shared])
     p_close.add_argument("--phase", required=True)
     p_close.add_argument("--change", default=None)
-    p_close.add_argument("--project", default=None)
+    p_close.add_argument(
+        "--project",
+        default=None,
+        help=(
+            "execution root PATH (worktree) for this phase; defaults to the "
+            "change's main project. Takes a path, not a project name."
+        ),
+    )
     p_close.add_argument("--status", required=True)
     p_close.add_argument("--run-id", default=None)
     p_close.add_argument("--task", type=int, default=None)

package/harness/bundles/general/claude-code/scripts/harness_ledger.py

@@ -1614,6 +1614,35 @@ def _scenario_receipt_error(code: str, message: str) -> dict[str, Any]:
     return {"ok": False, "code": code, "error": message}
 
 
+def _resolve_receipt_path(
+    raw: str, change_dir: Path
+) -> tuple[Path | None, list[Path]]:
+    """Resolve --scenario-receipt-file against CWD *and* the change dir.
+
+    Skills write receipts under ``<change-dir>/runtime/``, so a bare
+    ``runtime/scenario-receipt-*.json`` is the natural thing to pass. Resolving
+    only against the CWD made that fail with a bare ENOENT. Return the first
+    existing candidate plus every path tried, so the error can name them.
+    """
+    candidate = Path(raw).expanduser()
+    if candidate.is_absolute():
+        resolved = candidate.resolve()
+        return (resolved if resolved.is_file() else None), [resolved]
+    candidates = [
+        (Path.cwd() / candidate).resolve(),
+        (change_dir / candidate).resolve(),
+    ]
+    # De-duplicate while preserving order (CWD == change_dir is common).
+    unique: list[Path] = []
+    for item in candidates:
+        if item not in unique:
+            unique.append(item)
+    for item in unique:
+        if item.is_file():
+            return item, unique
+    return None, unique
+
+
 def _canonical_string_list(
     receipt: dict[str, Any],
     field: str,
@@ -2786,17 +2815,37 @@ def cmd_record(args: argparse.Namespace) -> int:
                 if manifest_schema >= 2 and not _nonempty_str(receipt_file):
                     return emit_error(
                         "scenario-manifest schemaVersion 2 requires "
-                        "--scenario-receipt-file",
+                        "--scenario-receipt-file; generate a skeleton with: "
+                        "harness_ledger.py scenario-receipt-template "
+                        f"--change-dir {change_dir} --scenario-ids "
+                        f"{','.join(ids)} --runner <name> --out "
+                        "runtime/scenario-receipt-<verification>.json",
                         as_json=as_json,
                         error_code="SCENARIO_RECEIPT_REQUIRED",
+                        extra={"template": "scenario-receipt-template"},
                     )
                 if _nonempty_str(receipt_file):
+                    resolved_receipt, receipt_candidates = _resolve_receipt_path(
+                        str(receipt_file), change_dir
+                    )
+                    if resolved_receipt is None:
+                        return emit_error(
+                            "scenario receipt not found; tried: "
+                            + ", ".join(str(c) for c in receipt_candidates),
+                            as_json=as_json,
+                            error_code="SCENARIO_RECEIPT_NOT_FOUND",
+                            extra={
+                                "triedPaths": [str(c) for c in receipt_candidates],
+                                "hint": (
+                                    "--scenario-receipt-file accepts an absolute "
+                                    "path, a CWD-relative path, or a path relative "
+                                    "to --change-dir"
+                                ),
+                            },
+                        )
                     try:
                         receipt_payload = json.loads(
-                            Path(str(receipt_file))
-                            .expanduser()
-                            .resolve()
-                            .read_text(encoding="utf-8-sig")
+                            resolved_receipt.read_text(encoding="utf-8-sig")
                         )
                     except (OSError, json.JSONDecodeError) as exc:
                         return emit_error(
@@ -2953,6 +3002,160 @@ def cmd_record(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_scenario_receipt_template(args: argparse.Namespace) -> int:
+    """Emit a schema-v2 receipt skeleton built from the scenario manifest.
+
+    Without this, agents had to read harness_ledger.py source to learn the
+    receipt shape. The skeleton is already valid for `record`; the caller only
+    has to correct `status` for any test that did not pass.
+    """
+    as_json = bool(args.json)
+    change_dir = resolve_path(args.change_dir)
+    ids = [s.strip() for s in str(args.scenario_ids).split(",") if s.strip()]
+    if not ids:
+        return emit_error(
+            "--scenario-ids must list at least one scenario ID",
+            as_json=as_json,
+            error_code="SCENARIO_IDS_REQUIRED",
+        )
+    if len(ids) != len(set(ids)):
+        return emit_error(
+            "scenario IDs must be unique",
+            as_json=as_json,
+            error_code="SCENARIO_ID_DUPLICATE",
+        )
+    manifest_path = change_dir / "meta" / "scenario-manifest.json"
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8-sig"))
+    except FileNotFoundError:
+        return emit_error(
+            f"scenario manifest does not exist: {manifest_path}",
+            as_json=as_json,
+            error_code="SCENARIO_MANIFEST_MISSING",
+        )
+    except (OSError, json.JSONDecodeError) as exc:
+        return emit_error(
+            f"scenario manifest unreadable: {exc}",
+            as_json=as_json,
+            error_code="SCENARIO_MANIFEST_INVALID",
+        )
+    scenarios = manifest.get("scenarios") if isinstance(manifest, dict) else None
+    if not isinstance(scenarios, list):
+        return emit_error(
+            "scenario-manifest.json must contain a scenarios array",
+            as_json=as_json,
+            error_code="SCENARIO_MANIFEST_INVALID",
+        )
+    by_id = {
+        str(item.get("id") or "").strip(): item
+        for item in scenarios
+        if isinstance(item, dict) and _nonempty_str(item.get("id"))
+    }
+    unknown = sorted(set(ids) - set(by_id))
+    if unknown:
+        return emit_error(
+            "scenario IDs are not declared in scenario-manifest.json: "
+            + ", ".join(unknown),
+            as_json=as_json,
+            error_code="SCENARIO_ID_UNKNOWN",
+        )
+    status = str(args.status).strip().upper()
+    if status not in {"PASSED", "FAILED", "SKIPPED"}:
+        return emit_error(
+            "--status must be one of PASSED|FAILED|SKIPPED",
+            as_json=as_json,
+            error_code="SCENARIO_RECEIPT_INVALID",
+        )
+    attempt = int(args.attempt)
+    if attempt < 1:
+        return emit_error(
+            "--attempt must be a positive integer",
+            as_json=as_json,
+            error_code="SCENARIO_RECEIPT_INVALID",
+        )
+
+    identities: list[tuple[str, str, str]] = []
+    incomplete: list[str] = []
+    for scenario_id in ids:
+        scenario = by_id[scenario_id]
+        if any(
+            not _nonempty_str(scenario.get(field))
+            for field in ("executableTestId", "testFile", "testTitle")
+        ):
+            incomplete.append(scenario_id)
+            continue
+        identities.append(
+            (
+                str(scenario["executableTestId"]).strip(),
+                str(scenario["testFile"]).strip(),
+                str(scenario["testTitle"]).strip(),
+            )
+        )
+    if incomplete:
+        return emit_error(
+            "scenarios are missing executableTestId/testFile/testTitle in the "
+            "manifest: " + ", ".join(incomplete),
+            as_json=as_json,
+            error_code="SCENARIO_MANIFEST_INVALID",
+            extra={"incomplete": incomplete},
+        )
+
+    runner: dict[str, Any] = {"name": str(args.runner).strip()}
+    if _nonempty_str(getattr(args, "runner_version", None)):
+        runner["version"] = str(args.runner_version).strip()
+    receipt = {
+        "schemaVersion": 1,
+        "runner": runner,
+        "attempt": attempt,
+        "declared": [test_id for test_id, _, _ in identities],
+        "selected": [test_id for test_id, _, _ in identities],
+        "collected": [
+            {"testId": test_id, "file": file, "title": title}
+            for test_id, file, title in identities
+        ],
+        "executed": [
+            {
+                "testId": test_id,
+                "file": file,
+                "title": title,
+                "attempt": attempt,
+                "status": status,
+            }
+            for test_id, file, title in identities
+        ],
+    }
+    body = json.dumps(receipt, ensure_ascii=False, indent=2) + "\n"
+
+    out_raw = getattr(args, "out", None)
+    if not _nonempty_str(out_raw):
+        sys.stdout.write(body)
+        return 0
+    out_path = Path(str(out_raw)).expanduser()
+    if not out_path.is_absolute():
+        out_path = change_dir / out_path
+    out_path = out_path.resolve()
+    try:
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(body, encoding="utf-8", newline="\n")
+    except OSError as exc:
+        return emit_error(
+            f"cannot write scenario receipt: {exc}",
+            as_json=as_json,
+            error_code="SCENARIO_RECEIPT_WRITE_FAILED",
+        )
+    payload = {
+        "ok": True,
+        "action": "scenario-receipt-template",
+        "path": str(out_path),
+        "scenarioIds": ids,
+    }
+    if as_json:
+        sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")
+    else:
+        sys.stdout.write(f"{out_path}\n")
+    return 0
+
+
 def cmd_diff_hash(args: argparse.Namespace) -> int:
     as_json = bool(args.json)
     repo_raw = getattr(args, "repo", None)
@@ -3234,6 +3437,42 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p_diff.set_defaults(func=cmd_diff_hash)
 
+    p_receipt = sub.add_parser(
+        "scenario-receipt-template",
+        parents=[shared_json],
+        help=(
+            "emit a schema-v2 scenario execution receipt skeleton "
+            "pre-filled from meta/scenario-manifest.json"
+        ),
+    )
+    p_receipt.add_argument("--change-dir", required=True)
+    p_receipt.add_argument(
+        "--scenario-ids",
+        required=True,
+        help="comma-separated scenario IDs to include (must exist in the manifest)",
+    )
+    p_receipt.add_argument(
+        "--runner",
+        required=True,
+        help="test runner name recorded in the receipt (e.g. vitest / maven-surefire)",
+    )
+    p_receipt.add_argument("--runner-version", default=None)
+    p_receipt.add_argument("--attempt", type=int, default=1)
+    p_receipt.add_argument(
+        "--status",
+        default="PASSED",
+        help="per-test status written into executed[] (default: PASSED)",
+    )
+    p_receipt.add_argument(
+        "--out",
+        default=None,
+        help=(
+            "write the skeleton to this path instead of stdout; relative paths "
+            "resolve against --change-dir (same rule as --scenario-receipt-file)"
+        ),
+    )
+    p_receipt.set_defaults(func=cmd_scenario_receipt_template)
+
     return parser