workflow-toolkit 1.0.1

package/.agents/skills/wtk-ship/remediation.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Pure remediation-stall normalization and transition helper.
+
+The executable JSON protocol reads one object from stdin and writes the next
+state to stdout. No repository, process, or remote authority is involved.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+DEFAULT_STALL_ATTEMPTS = 3
+_LOCATION = re.compile(
+    r"(?P<path>(?:(?:[A-Za-z]:)?[\\/]|(?<!\S))[^()\r\n]*?"
+    r"[^/\\\s:]+\.[^/\\\s:()]+)(?::\d+(?::\d+)?|\(\d+,\d+\):?)"
+)
+_PATH = re.compile(
+    r"(?P<path>(?:(?:[A-Za-z]:)?[\\/]|(?<!\S))[^()\r\n]*?"
+    r"[^/\\\s:]+\.[^/\\\s:()]+)(?=\s*(?:>|$))"
+)
+_TIMING = re.compile(r"\s*\(?\d+(?:\.\d+)?\s*(?:ms|s)\)?", re.IGNORECASE)
+_WHITESPACE = re.compile(r"\s+")
+
+
+def normalize_stall_attempts(value: Any) -> int:
+    """Return the strict bound: absent is 3, zero is unbounded."""
+    if value is None:
+        return DEFAULT_STALL_ATTEMPTS
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise ValueError("stall_attempts must be a non-negative integer")
+    return value
+
+
+def _normalize_test_name(value: Any) -> str:
+    if not isinstance(value, str):
+        raise ValueError("failing test names must be strings")
+    text = _TIMING.sub("", value.strip())
+
+    def strip_location(match: re.Match[str]) -> str:
+        path = match.group("path").replace("\\", "/").rsplit("/", 1)[-1]
+        return f"{path} >" if match.group(0).endswith(":") else path
+
+    text = _LOCATION.sub(strip_location, text)
+    text = _PATH.sub(strip_location, text)
+    return _WHITESPACE.sub(" ", text).strip()
+
+
+def normalize_failing_tests(names: Iterable[Any]) -> list[str]:
+    """Trim, de-time, de-path, deduplicate, and sort test identifiers."""
+    if isinstance(names, (str, bytes)):
+        raise ValueError("failing tests must be an array")
+    values = {_normalize_test_name(name) for name in names}
+    values.discard("")
+    return sorted(values, key=lambda value: (value.casefold(), value))
+
+
+def _normalize_fixes(fixes: Iterable[Any]) -> list[str]:
+    if isinstance(fixes, (str, bytes)):
+        raise ValueError("fixes_tried must be an array")
+    result: list[str] = []
+    seen: set[str] = set()
+    for fix in fixes:
+        if not isinstance(fix, str):
+            raise ValueError("fixes_tried must contain strings")
+        value = _WHITESPACE.sub(" ", fix.strip())
+        if value and value not in seen:
+            seen.add(value)
+            result.append(value)
+    return result
+
+
+def _previous_tests(previous: Mapping[str, Any]) -> tuple[bool, list[str]]:
+    attempt_count = int(previous.get("attempt_count", 0))
+    if attempt_count == 0:
+        return False, []
+    if "minimum_failing_tests" not in previous:
+        raise ValueError("previous state is missing minimum_failing_tests")
+    return True, normalize_failing_tests(previous["minimum_failing_tests"])
+
+
+def transition_remediation(
+    previous: Mapping[str, Any] | None,
+    failing_tests: Iterable[Any],
+    *,
+    stall_attempts: Any = None,
+    gate_available: bool = True,
+    fixes_tried: Iterable[Any] = (),
+) -> dict[str, Any]:
+    """Advance one post-cap remediation attempt without side effects."""
+    previous_state: Mapping[str, Any] = previous or {}
+    threshold = normalize_stall_attempts(stall_attempts)
+    current = normalize_failing_tests(failing_tests)
+    fixes = _normalize_fixes(previous_state.get("fixes_tried", []))
+    for fix in _normalize_fixes(fixes_tried):
+        if fix not in fixes:
+            fixes.append(fix)
+    attempt_count = int(previous_state.get("attempt_count", 0)) + 1
+    prior_stalls = int(previous_state.get("consecutive_stalls", 0))
+    had_baseline, prior_tests = _previous_tests(previous_state)
+    minimum_tests = prior_tests
+    minimum_count = len(minimum_tests)
+
+    state: dict[str, Any] = {
+        "stall_attempts": threshold,
+        "failing_tests": current,
+        "failing_signature": " | ".join(current),
+        "minimum_failing_tests": minimum_tests,
+        "attempt_count": attempt_count,
+        "consecutive_stalls": prior_stalls,
+        "minimum_failing_count": minimum_count,
+        "fixes_tried": fixes,
+        "halted": False,
+    }
+
+    if not gate_available:
+        state.update({"status": "halted", "reason": "scoped_gate_unavailable", "halted": True})
+        state["report"] = {
+            "reason": state["reason"],
+            "failing_signature": state["failing_signature"],
+            "attempt_count": state["attempt_count"],
+            "fixes_tried": state["fixes_tried"],
+        }
+        return state
+
+    if not had_baseline or set(current) < set(minimum_tests):
+        state.update({
+            "status": "progress",
+            "reason": "smaller_failing_set" if had_baseline else "initial_failure_set",
+            "consecutive_stalls": 0,
+            "minimum_failing_tests": current,
+            "minimum_failing_count": len(current),
+        })
+        return state
+
+    stalls = prior_stalls + 1
+    state.update({"status": "stalled", "reason": "failing_set_not_smaller", "consecutive_stalls": stalls})
+    if threshold and stalls >= threshold:
+        state.update({"status": "halted", "reason": "stall_threshold_reached", "halted": True})
+        state["report"] = {
+            "reason": state["reason"],
+            "failing_signature": state["failing_signature"],
+            "attempt_count": state["attempt_count"],
+            "fixes_tried": state["fixes_tried"],
+        }
+    return state
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+        result = transition_remediation(
+            payload.get("previous"),
+            payload.get("failing_tests", []),
+            stall_attempts=payload.get("stall_attempts"),
+            gate_available=payload.get("gate_available", True),
+            fixes_tried=payload.get("fixes_tried", []),
+        )
+    except (TypeError, ValueError, KeyError, json.JSONDecodeError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 2
+    print(json.dumps(result, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.agents/skills/wtk-ship/scripts/close_feature.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Close a verified Workflow Toolkit feature after explicit fact promotion.
+
+Promotion is semantic work performed by the agent and human, so this helper only
+checks the receipt and removes the transient feature directory. It never writes
+knowledge, decisions, product promises, or architecture documentation.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+SLUG = re.compile(r"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$")
+
+
+def feature_dir(root: Path, feature: str) -> Path:
+    if not SLUG.fullmatch(feature):
+        raise ValueError("feature must be a lowercase slug")
+    root = root.resolve()
+    specs = root / ".specs"
+    features = specs / "features"
+    target = features / feature
+    for parent in (specs, features):
+        if parent.is_symlink():
+            raise ValueError(f"cleanup path must not be a symlink: {parent.relative_to(root)}")
+        if not parent.is_dir():
+            raise ValueError(f"feature directory is missing: {features.relative_to(root)}")
+    if target.is_symlink():
+        raise ValueError(f"cleanup path must not be a symlink: {target.relative_to(root)}")
+    if target.parent != features or target == features or target.resolve().parent != features:
+        raise ValueError("feature path must remain under .specs/features")
+    return target
+
+
+def close_feature(root: Path, feature: str, *, promoted: bool = False) -> Path:
+    """Delete one verified feature directory after a recorded promotion."""
+    if not promoted:
+        raise ValueError("promotion receipt is required before cleanup")
+    root = root.resolve()
+    target = feature_dir(root, feature)
+    verification = target / "verification.md"
+    if not verification.is_file():
+        raise ValueError("verification.md is required before cleanup")
+    checks = target / "checks.md"
+    if not checks.is_file():
+        raise ValueError("checks.md is required before cleanup")
+    validator = root / ".agents" / "skills" / "wtk-lean" / "scripts" / "validate_verification.py"
+    result = subprocess.run(
+        [sys.executable, str(validator), str(target.resolve()), "--root", str(root)],
+        cwd=root,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise ValueError(result.stderr.strip() or result.stdout.strip() or "verification gate failed")
+    shutil.rmtree(target)
+    return target
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("feature")
+    parser.add_argument("--root", type=Path, default=Path.cwd())
+    parser.add_argument("--promoted", action="store_true", help="confirm durable facts were promoted")
+    args = parser.parse_args(argv)
+    try:
+        removed = close_feature(args.root, args.feature, promoted=args.promoted)
+    except (OSError, ValueError) as exc:
+        print(f"close_feature: {exc}", file=sys.stderr)
+        return 1
+    print(json.dumps({"feature": args.feature, "removed": str(removed.relative_to(args.root.resolve()))}))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.agents/skills/wtk-ship/scripts/review_convergence.py

@@ -0,0 +1,373 @@
+#!/usr/bin/env python3
+"""Persist immutable blocker fingerprints and append-only audit generations."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+import tempfile
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+_SKILLS_ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(_SKILLS_ROOT / "wtk-ship"))
+import remediation
+
+sys.path.insert(0, str(_SKILLS_ROOT / "wtk-config" / "scripts"))
+import workflow_config
+
+MAX_FAILURES = 3
+GENERATION_STATUSES = {"open", "halted", "closed"}
+REMEDIATION_FIELDS = (
+    "failing_tests", "failing_signature", "minimum_failing_tests", "minimum_failing_count",
+    "consecutive_stalls", "attempt_count", "fixes_tried",
+)
+
+
+def _normalize(value: str) -> str:
+    return re.sub(r"\s+", " ", value.strip().lower())
+
+
+def fingerprint(requirement: str, root_cause: str, failure_path: str) -> str:
+    material = "\0".join(_normalize(value) for value in (requirement, root_cause, failure_path))
+    return hashlib.sha256(material.encode("utf-8")).hexdigest()
+
+
+def state_path(root: Path, feature: str) -> Path:
+    if not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", feature):
+        raise ValueError("invalid feature")
+    resolved_root = Path(root).resolve()
+    feature_dir = (resolved_root / ".specs" / "features" / feature).resolve()
+    try:
+        feature_dir.relative_to(resolved_root)
+    except ValueError as exc:
+        raise ValueError("feature path escapes root") from exc
+    return feature_dir / "review-fingerprints.json"
+
+
+def _halt_event(generation: int, failures: int) -> dict[str, Any]:
+    return {"generation": generation, "failed_remediations": failures, "status": "halted"}
+
+
+def _generation(number: int, failures: int, status: str, **extra: Any) -> dict[str, Any]:
+    value: dict[str, Any] = {
+        "generation": number,
+        "failed_remediations": failures,
+        "status": status,
+        "failing_tests": [],
+        "failing_signature": "",
+        "minimum_failing_tests": [],
+        "minimum_failing_count": 0,
+        "consecutive_stalls": 0,
+        "attempt_count": 0,
+        "fixes_tried": [],
+    }
+    value.update(extra)
+    if status == "halted":
+        value.setdefault("halt_event", _halt_event(number, failures))
+    return value
+
+
+def _legacy_generation(entry: dict[str, Any]) -> dict[str, Any]:
+    failures = entry.get("failed_remediations")
+    status = entry.get("status")
+    if type(failures) is not int or failures < 0 or status not in GENERATION_STATUSES:
+        raise ValueError("invalid convergence entry")
+    if status == "halted" and failures < MAX_FAILURES:
+        raise ValueError("halted convergence entry has too few failures")
+    if status == "open" and failures >= MAX_FAILURES:
+        raise ValueError("open convergence entry has too many failures")
+    if status == "closed" and failures >= MAX_FAILURES:
+        raise ValueError("closed convergence entry has too many failures")
+    return _generation(1, failures, status)
+
+
+def _valid_authorization(reference: str) -> bool:
+    return bool(
+        reference and reference == reference.strip() and reference.startswith(".specs/")
+        and "#" in reference and ".." not in reference and "\\" not in reference
+        and not Path(reference).is_absolute()
+    )
+
+
+def _validate_generation(generation: Any, expected_number: int) -> dict[str, Any]:
+    if not isinstance(generation, dict) or generation.get("generation") != expected_number:
+        raise ValueError("non-contiguous audit generations")
+    failures = generation.get("failed_remediations")
+    status = generation.get("status")
+    if type(failures) is not int or failures < 0 or status not in GENERATION_STATUSES:
+        raise ValueError("invalid audit generation")
+    for field in REMEDIATION_FIELDS:
+        if field not in generation:
+            if field == "failing_tests":
+                generation[field] = []
+            elif field == "minimum_failing_tests":
+                generation[field] = list(generation.get("failing_tests", []))
+            elif field == "failing_signature":
+                generation[field] = ""
+            elif field == "fixes_tried":
+                generation[field] = []
+            else:
+                generation[field] = 0
+    if not isinstance(generation["failing_tests"], list) or any(not isinstance(value, str) for value in generation["failing_tests"]):
+        raise ValueError("invalid remediation failing tests")
+    if not isinstance(generation["minimum_failing_tests"], list) or any(not isinstance(value, str) for value in generation["minimum_failing_tests"]):
+        raise ValueError("invalid remediation minimum failing tests")
+    if not isinstance(generation["failing_signature"], str):
+        raise ValueError("invalid remediation failing signature")
+    for field in ("minimum_failing_count", "consecutive_stalls", "attempt_count"):
+        if type(generation[field]) is not int or generation[field] < 0:
+            raise ValueError("invalid remediation counters")
+    if not isinstance(generation["fixes_tried"], list) or any(not isinstance(value, str) for value in generation["fixes_tried"]):
+        raise ValueError("invalid remediation fixes")
+    halt_reason = generation.get("halt_reason")
+    if halt_reason is not None and halt_reason not in {"stall_threshold_reached", "scoped_gate_unavailable"}:
+        raise ValueError("invalid remediation halt reason")
+    if status == "halted":
+        if halt_reason == "stall_threshold_reached" and generation["consecutive_stalls"] < 1:
+            raise ValueError("halted audit generation has no recorded stall")
+        if failures < MAX_FAILURES and halt_reason not in {"stall_threshold_reached", "scoped_gate_unavailable"}:
+            raise ValueError("halted audit generation has no valid halt reason")
+        event = generation.get("halt_event")
+        if not isinstance(event, dict) or event != _halt_event(expected_number, failures):
+            raise ValueError("invalid halt event")
+    elif "halt_event" in generation or halt_reason is not None:
+        raise ValueError("halt event on non-halted generation")
+    if "authorization_ref" in generation and (
+        not isinstance(generation["authorization_ref"], str)
+        or not _valid_authorization(generation["authorization_ref"])
+    ):
+        raise ValueError("invalid authorization reference")
+    return generation
+
+
+def _normalize_entry(key: str, value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict) or value.get("fingerprint") != key:
+        raise ValueError("invalid convergence entry")
+    required = ("requirement", "root_cause", "failure_path")
+    if any(not isinstance(value.get(field), str) or not value[field].strip() for field in required):
+        raise ValueError("invalid convergence entry")
+    normalized = dict(value)
+    for field in required:
+        normalized[field] = _normalize(normalized[field])
+    generations = normalized.get("generations")
+    if generations is None:
+        generations = [_legacy_generation(normalized)]
+    elif not isinstance(generations, list) or not generations:
+        raise ValueError("invalid audit generations")
+    generations = [_validate_generation(item, index) for index, item in enumerate(generations, 1)]
+    current_generation = normalized.get("current_generation", len(generations))
+    if current_generation != len(generations):
+        raise ValueError("invalid current generation")
+    cumulative = sum(item["failed_remediations"] for item in generations)
+    if type(normalized.get("failed_remediations")) is not int or normalized.get("failed_remediations") != cumulative:
+        raise ValueError("inconsistent cumulative failures")
+    if normalized.get("status") != generations[-1]["status"]:
+        raise ValueError("inconsistent convergence status")
+    if any(item["status"] == "closed" for item in generations[:-1]):
+        raise ValueError("closed audit generation cannot be resumed")
+    normalized.update({"current_generation": current_generation, "generations": generations})
+    return normalized
+
+
+def _load(path: Path, feature: str) -> dict[str, Any]:
+    if not path.exists():
+        return {"version": 2, "feature": feature, "fingerprints": {}}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ValueError("invalid convergence state") from exc
+    if payload.get("version") not in {1, 2} or payload.get("feature") != feature or not isinstance(payload.get("fingerprints"), dict):
+        raise ValueError("invalid convergence state")
+    return {
+        "version": 2,
+        "feature": feature,
+        "fingerprints": {key: _normalize_entry(key, value) for key, value in payload["fingerprints"].items()},
+    }
+
+
+def _save(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle, sort_keys=True, separators=(",", ":"))
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    finally:
+        try:
+            os.unlink(temporary)
+        except FileNotFoundError:
+            pass
+
+
+def _entry_key(state: dict[str, Any], requirement: str, root_cause: str, failure_path: str, previous_fingerprint: str | None) -> str:
+    key = previous_fingerprint or fingerprint(requirement, root_cause, failure_path)
+    current = state["fingerprints"].get(key)
+    if previous_fingerprint is not None and current is None:
+        raise ValueError("unknown previous fingerprint")
+    if current is not None and _normalize(str(current.get("requirement", ""))) != _normalize(requirement):
+        raise ValueError("previous fingerprint requirement mismatch")
+    if previous_fingerprint is None and any(
+        item.get("status") == "halted" and item.get("requirement") == _normalize(requirement)
+        for item in state["fingerprints"].values()
+    ):
+        raise ValueError("halted fingerprint requires authorized resume")
+    return key
+
+
+def record_result(
+    root: Path, feature: str, requirement: str, root_cause: str, failure_path: str, *,
+    verifier_failed: bool, gate_passed: bool, previous_fingerprint: str | None = None,
+    independent: bool = False, evidence_ref: str | None = None,
+    failing_tests: list[Any] | tuple[Any, ...] = (),
+    fixes_tried: list[Any] | tuple[Any, ...] = (),
+    gate_available: bool = True,
+) -> dict[str, Any]:
+    path = state_path(root, feature)
+    state = _load(path, feature)
+    key = _entry_key(state, requirement, root_cause, failure_path, previous_fingerprint)
+    current = state["fingerprints"].get(key)
+    if current is None:
+        current = {
+            "fingerprint": key, "requirement": _normalize(requirement),
+            "root_cause": _normalize(root_cause), "failure_path": _normalize(failure_path),
+            "failed_remediations": 0, "status": "open", "current_generation": 1,
+            "generations": [_generation(1, 0, "open")],
+        }
+    else:
+        current = deepcopy(current)
+        if previous_fingerprint is not None and current["status"] == "halted":
+            if _normalize(root_cause) != current["root_cause"] or _normalize(failure_path) != current["failure_path"]:
+                raise ValueError("halted fingerprint identity cannot be reworded")
+        elif previous_fingerprint is not None:
+            current.update({"requirement": _normalize(requirement), "root_cause": _normalize(root_cause), "failure_path": _normalize(failure_path)})
+    generation = current["generations"][-1]
+    prior_status = current["status"]
+    remediation_attempt = verifier_failed or bool(failing_tests) or bool(fixes_tried) or not gate_available
+    if remediation_attempt and prior_status == "halted":
+        raise ValueError("halted fingerprint requires authorized resume")
+    transition: dict[str, Any] | None = None
+    if remediation_attempt:
+        transition = remediation.transition_remediation(
+            generation,
+            failing_tests,
+            stall_attempts=workflow_config.stall_attempts(root),
+            gate_available=gate_available,
+            fixes_tried=fixes_tried,
+        )
+        for field in REMEDIATION_FIELDS:
+            generation[field] = transition[field]
+        if transition["halted"]:
+            generation["status"] = "halted"
+            generation["halt_reason"] = transition["reason"]
+        elif verifier_failed:
+            generation["status"] = "open"
+            generation.pop("halt_event", None)
+            generation.pop("halt_reason", None)
+    if verifier_failed:
+        generation["failed_remediations"] += 1
+        if transition is None or not transition["halted"]:
+            generation["status"] = "open"
+            generation.pop("halt_event", None)
+            generation.pop("halt_reason", None)
+    if transition is not None and transition["halted"]:
+        generation["halt_event"] = _halt_event(generation["generation"], generation["failed_remediations"])
+    elif gate_passed and previous_fingerprint is not None and current["status"] == "open":
+        qualifies = independent and bool(evidence_ref) and _valid_authorization(evidence_ref)
+        if current["current_generation"] == 1 or qualifies:
+            if current["current_generation"] > 1:
+                generation["evidence_ref"] = evidence_ref
+            generation["status"] = "closed"
+            generation.pop("halt_event", None)
+    current["failed_remediations"] = sum(item["failed_remediations"] for item in current["generations"])
+    current["status"] = current["generations"][-1]["status"]
+    state["fingerprints"][key] = current
+    _save(path, state)
+    return deepcopy(current)
+
+
+def record_failure(
+    root: Path, feature: str, requirement: str, root_cause: str, failure_path: str, *,
+    gate_passed: bool = False, previous_fingerprint: str | None = None,
+    failing_tests: list[Any] | tuple[Any, ...] = (),
+    fixes_tried: list[Any] | tuple[Any, ...] = (),
+    gate_available: bool = True,
+) -> dict[str, Any]:
+    return record_result(
+        root, feature, requirement, root_cause, failure_path,
+        verifier_failed=True, gate_passed=gate_passed,
+        previous_fingerprint=previous_fingerprint, failing_tests=failing_tests,
+        fixes_tried=fixes_tried, gate_available=gate_available,
+    )
+
+
+def resume(root: Path, feature: str, resume_fingerprint: str, authorization_ref: str) -> dict[str, Any]:
+    """Append an authorized generation without mutating the halted history."""
+    path = state_path(root, feature)
+    state = _load(path, feature)
+    if not re.fullmatch(r"[0-9a-f]{64}", resume_fingerprint):
+        raise ValueError("invalid resume fingerprint")
+    if not _valid_authorization(authorization_ref):
+        raise ValueError("invalid authorization reference")
+    current = state["fingerprints"].get(resume_fingerprint)
+    if current is None:
+        raise ValueError("unknown resume fingerprint")
+    if current["status"] != "halted" or current["generations"][-1]["status"] != "halted":
+        raise ValueError("resume requires halted fingerprint")
+    updated = deepcopy(current)
+    generation = _generation(current["current_generation"] + 1, 0, "open", authorization_ref=authorization_ref)
+    updated["generations"].append(generation)
+    updated["current_generation"] = generation["generation"]
+    updated["status"] = "open"
+    updated["failed_remediations"] = sum(item["failed_remediations"] for item in updated["generations"])
+    state["fingerprints"][resume_fingerprint] = updated
+    _save(path, state)
+    return deepcopy(updated)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, default=Path.cwd())
+    parser.add_argument("--feature", required=True)
+    parser.add_argument("--requirement")
+    parser.add_argument("--root-cause")
+    parser.add_argument("--failure-path")
+    parser.add_argument("--previous-fingerprint")
+    parser.add_argument("--resume-fingerprint")
+    parser.add_argument("--authorization-ref")
+    parser.add_argument("--verifier-failed", action="store_true")
+    parser.add_argument("--gate-passed", action="store_true")
+    parser.add_argument("--independent", action="store_true")
+    parser.add_argument("--evidence-ref")
+    parser.add_argument("--failing-test", action="append", default=[])
+    parser.add_argument("--fix-tried", action="append", default=[])
+    parser.add_argument("--gate-unavailable", action="store_true")
+    args = parser.parse_args(argv)
+    if args.resume_fingerprint is not None:
+        if args.authorization_ref is None:
+            raise SystemExit("--authorization-ref is required with --resume-fingerprint")
+        result = resume(args.root, args.feature, args.resume_fingerprint, args.authorization_ref)
+    else:
+        if any(value is None for value in (args.requirement, args.root_cause, args.failure_path)):
+            raise SystemExit("--requirement, --root-cause, and --failure-path are required")
+        result = record_result(
+            args.root, args.feature, args.requirement, args.root_cause, args.failure_path,
+            verifier_failed=args.verifier_failed, gate_passed=args.gate_passed,
+            previous_fingerprint=args.previous_fingerprint, independent=args.independent,
+            evidence_ref=args.evidence_ref, failing_tests=args.failing_test,
+            fixes_tried=args.fix_tried, gate_available=not args.gate_unavailable,
+        )
+    print(json.dumps(result, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())