@hunter-harness/workflow-harness 0.2.9 → 0.2.10

package/harness/bundles/general/cursor/scripts/harness_paths.py

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""Harness path and identity resolution.
+
+Single owner for:
+- repository identity (stable across worktrees of one repo);
+- Change contract loading (``meta/change-context.json``);
+- dual-root layout resolution (static contract root vs dynamic state root);
+- path boundary assertions used by cleanup/integration code.
+
+Python 3.10+, stdlib only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8")
+
+LIFECYCLE_STATUSES = {"draft", "active", "superseded", "archived", "cancelled"}
+CHANGE_CONTEXT_REL = Path("meta") / "change-context.json"
+
+
+def _git_text(cwd: Path, *args: str) -> str | None:
+    proc = subprocess.run(
+        ["git", *args],
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+    if proc.returncode != 0:
+        return None
+    return proc.stdout.strip()
+
+
+def resolve_main_project_root(cwd: Path | None = None) -> Path:
+    """Locate the main project root from a worktree or the main checkout."""
+    start = (cwd or Path.cwd()).resolve()
+    common_raw = _git_text(start, "rev-parse", "--git-common-dir")
+    if not common_raw:
+        return start
+    common = Path(common_raw)
+    if not common.is_absolute():
+        common = (start / common).resolve()
+    if common.name == ".git":
+        return common.parent
+    return start
+
+
+def resolve_worktree_root(cwd: Path | None = None) -> Path:
+    """Top-level of the checkout containing ``cwd`` (worktree-aware)."""
+    start = (cwd or Path.cwd()).resolve()
+    top = _git_text(start, "rev-parse", "--show-toplevel")
+    if not top:
+        return start
+    return Path(top).resolve()
+
+
+def _git_common_dir(cwd: Path) -> Path | None:
+    raw = _git_text(cwd, "rev-parse", "--git-common-dir")
+    if not raw:
+        return None
+    common = Path(raw)
+    if not common.is_absolute():
+        common = (cwd / common).resolve()
+    return common
+
+
+def _root_commit(cwd: Path) -> str | None:
+    raw = _git_text(cwd, "rev-list", "--max-parents=0", "HEAD")
+    if not raw:
+        return None
+    return raw.splitlines()[0].strip()
+
+
+def _normalize_remote(url: str) -> str:
+    """Normalize a git remote URL to ``host/path`` lowercase form."""
+    text = url.strip()
+    text = re.sub(r"^git@", "", text)
+    text = text.replace(":", "/", 1) if "://" not in text else text
+    text = re.sub(r"^[a-zA-Z]+://", "", text)
+    text = re.sub(r"^[^/@]+@", "", text)  # strip userinfo
+    text = text.lower()
+    if text.endswith(".git"):
+        text = text[: -len(".git")]
+    return text.rstrip("/")
+
+
+def _primary_remote_url(cwd: Path) -> str | None:
+    url = _git_text(cwd, "config", "--get", "remote.origin.url")
+    if url:
+        return url
+    remotes = _git_text(cwd, "remote")
+    if not remotes:
+        return None
+    first = remotes.splitlines()[0].strip()
+    return _git_text(cwd, "config", "--get", f"remote.{first}.url")
+
+
+def repository_identity(cwd: Path) -> str:
+    """Stable repository identity.
+
+    Preferred: normalized primary remote identity + root commit.
+    Fallback (no remote): resolved git common-dir identity + root commit.
+    The identity never embeds a worktree absolute path, so linked worktrees of
+    one repository share the same id (RET-09).
+    """
+    cwd = Path(cwd).resolve()
+    root_commit = _root_commit(cwd) or "no-root-commit"
+    remote = _primary_remote_url(cwd)
+    if remote:
+        basis = f"remote:{_normalize_remote(remote)}\n{root_commit}"
+    else:
+        common = _git_common_dir(cwd)
+        basis = f"local:{common}\n{root_commit}"
+    return "sha256:" + hashlib.sha256(basis.encode("utf-8")).hexdigest()
+
+
+def load_change_contract(contract_dir: Path) -> dict[str, Any]:
+    """Load and validate ``meta/change-context.json`` from a contract dir."""
+    contract_dir = Path(contract_dir)
+    context_path = contract_dir / CHANGE_CONTEXT_REL
+    if not context_path.is_file():
+        raise FileNotFoundError(f"change context not found: {context_path}")
+    data = json.loads(context_path.read_text(encoding="utf-8-sig"))
+    if not isinstance(data, dict):
+        raise ValueError(f"change context must be an object: {context_path}")
+    lifecycle = data.get("lifecycle")
+    if isinstance(lifecycle, dict):
+        status = lifecycle.get("status")
+        if status is not None and status not in LIFECYCLE_STATUSES:
+            raise ValueError(
+                f"invalid lifecycle.status {status!r}; expected one of "
+                f"{sorted(LIFECYCLE_STATUSES)}"
+            )
+    return data
+
+
+def contract_layout_kind(contract: dict[str, Any]) -> str:
+    """``split-v1`` when the contract declares a separate runtime root."""
+    ownership = contract.get("stateOwnership")
+    if isinstance(ownership, dict) and ownership.get("runtimeRoot"):
+        return "split-v1"
+    return "legacy-colocated"
+
+
+def _resolve_runtime_root(main_root: Path, change_name: str, runtime_root: Any) -> Path:
+    raw = Path(str(runtime_root or ""))
+    if not str(runtime_root or "").strip() or raw.is_absolute():
+        raise ValueError("stateOwnership.runtimeRoot must be a project-relative path")
+    state_parent = (main_root / ".harness" / "state" / "changes").resolve()
+    resolved = (main_root / raw).resolve()
+    assert_path_within(resolved, state_parent)
+    expected = (state_parent / change_name).resolve()
+    if resolved != expected:
+        raise ValueError(
+            "stateOwnership.runtimeRoot must equal "
+            f".harness/state/changes/{change_name}"
+        )
+    return resolved
+
+
+def resolve_change_layout(
+    cwd_hint: Path, change_id_or_dir: str | Path
+) -> dict[str, Any]:
+    """Resolve the static/dynamic roots for a change.
+
+    ``cwd_hint`` is any directory inside the checkout (main or linked
+    worktree); state always anchors at the main project root. Resolution is
+    read-only: legacy files are never moved here.
+    """
+    hint = Path(cwd_hint).resolve()
+    main_root = resolve_main_project_root(hint)
+    worktree_root = resolve_worktree_root(hint)
+
+    if isinstance(change_id_or_dir, Path):
+        contract_dir = change_id_or_dir.resolve()
+        change_name = contract_dir.name
+        if not contract_dir.is_dir():
+            raise FileNotFoundError(f"change contract dir not found: {contract_dir}")
+    else:
+        change_name = str(change_id_or_dir)
+        contract_dir = (main_root / ".harness" / "changes" / change_name).resolve()
+        if not contract_dir.is_dir():
+            raise FileNotFoundError(f"change not found: {change_name}")
+
+    contract: dict[str, Any] = {}
+    if (contract_dir / CHANGE_CONTEXT_REL).is_file():
+        contract = load_change_contract(contract_dir)
+
+    layout_kind = contract_layout_kind(contract)
+    if layout_kind == "split-v1":
+        runtime_rel = contract["stateOwnership"]["runtimeRoot"]
+        state_root = _resolve_runtime_root(main_root, change_name, runtime_rel)
+    else:
+        state_root = contract_dir
+
+    return {
+        "schemaVersion": 1,
+        "changeName": change_name,
+        "repositoryId": repository_identity(main_root),
+        "projectRoot": str(main_root),
+        "worktreeRoot": str(worktree_root),
+        "contractRoot": str(contract_dir),
+        "stateRoot": str(state_root),
+        "layout": layout_kind,
+    }
+
+
+def resolve_state_dir_for_contract(
+    contract_dir: Path, cwd: Path | None = None
+) -> Path:
+    """Return the dynamic-state root for a change contract dir.
+
+    split-v1 contracts resolve to ``.harness/state/changes/<id>`` under the
+    main project root. Legacy contracts, missing/invalid context files and
+    non-standard locations return the contract dir unchanged, so colocated
+    readers observe zero behaviour change.
+    """
+    contract_dir = Path(contract_dir).resolve()
+    try:
+        contract = load_change_contract(contract_dir)
+    except (FileNotFoundError, ValueError, json.JSONDecodeError, OSError):
+        return contract_dir
+    if contract_layout_kind(contract) != "split-v1":
+        return contract_dir
+    main_root = resolve_main_project_root(cwd or contract_dir)
+    expected = (main_root / ".harness" / "changes" / contract_dir.name).resolve()
+    if contract_dir != expected:
+        return contract_dir
+    return _resolve_runtime_root(
+        main_root, contract_dir.name, contract["stateOwnership"]["runtimeRoot"]
+    )
+
+
+def assert_path_within(
+    path: Path, allowed_root: Path, *, allow_root: bool = False
+) -> Path:
+    """Resolve ``path`` and require it to stay inside ``allowed_root``.
+
+    Rejects empty paths, parents, sibling-prefix attacks and symlink escapes.
+    Returns the resolved path on success.
+    """
+    raw = str(path)
+    if not raw or not raw.strip():
+        raise ValueError("empty path is not allowed")
+    root = Path(allowed_root).resolve()
+    resolved = Path(path).resolve()
+    if resolved == root:
+        if allow_root:
+            return resolved
+        raise ValueError(f"path is the allowed root itself: {resolved}")
+    if not resolved.is_relative_to(root):
+        raise ValueError(f"path escapes allowed root: {resolved} not within {root}")
+    return resolved
+
+
+def cmd_resolve_layout(args: argparse.Namespace) -> int:
+    layout = resolve_change_layout(Path.cwd(), args.change)
+    sys.stdout.write(json.dumps(layout, ensure_ascii=False, indent=2) + "\n")
+    return 0
+
+
+def cmd_repository_id(args: argparse.Namespace) -> int:
+    identity = repository_identity(Path.cwd())
+    if args.json:
+        sys.stdout.write(
+            json.dumps({"ok": True, "repositoryId": identity}, ensure_ascii=False)
+            + "\n"
+        )
+    else:
+        sys.stdout.write(identity + "\n")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="harness_paths.py")
+    sub = parser.add_subparsers(dest="command_name", required=True)
+
+    p_layout = sub.add_parser("resolve-layout")
+    p_layout.add_argument("--change", required=True)
+    p_layout.set_defaults(func=cmd_resolve_layout)
+
+    p_id = sub.add_parser("repository-id")
+    p_id.add_argument("--json", action="store_true")
+    p_id.set_defaults(func=cmd_repository_id)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/harness/bundles/general/cursor/scripts/harness_profile.py

@@ -727,6 +727,23 @@ def build_parser() -> argparse.ArgumentParser:
     p_validate.add_argument("--project", required=True, type=Path)
     p_validate.add_argument("--json", action="store_true")
 
+    p_resolve = sub.add_parser(
+        "resolve", help="resolve command template by key (runtime placeholder substitution)"
+    )
+    p_resolve.add_argument("--project", required=True, type=Path)
+    p_resolve.add_argument("--key", required=True, help="command key in profile.commands")
+    p_resolve.add_argument(
+        "--test-classes",
+        default=None,
+        help="comma-separated test classes substituting {testClasses}",
+    )
+    p_resolve.add_argument(
+        "--modules",
+        default=None,
+        help="comma-separated modules substituting {modules}",
+    )
+    p_resolve.add_argument("--json", action="store_true")
+
     p_migrate = sub.add_parser("migrate", help="migrate v1 → v2")
     p_migrate.add_argument("--project", required=True, type=Path)
     p_migrate.add_argument("--apply", action="store_true", help="apply (default: dry-run)")
@@ -757,6 +774,34 @@ def main(argv: list[str] | None = None) -> int:
             payload = {"ok": not issues, "issues": issues}
         sys.stdout.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
         return 0 if payload["ok"] else 1
+    if args.command == "resolve":
+        project = args.project.resolve()
+        profile = load_profile(project)
+        if profile is None:
+            sys.stdout.write(
+                json.dumps({"ok": False, "error": "profile missing"}, ensure_ascii=False) + "\n"
+            )
+            return 1
+        test_classes = (
+            [item for item in args.test_classes.split(",") if item]
+            if args.test_classes
+            else None
+        )
+        modules = (
+            [item for item in args.modules.split(",") if item] if args.modules else None
+        )
+        try:
+            resolved = resolve_command(
+                profile, args.key, test_classes=test_classes, modules=modules
+            )
+        except KeyError as exc:
+            sys.stdout.write(
+                json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False) + "\n"
+            )
+            return 1
+        payload = {"ok": True, "key": args.key, **resolved}
+        sys.stdout.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+        return 0
     if args.command == "migrate":
         result = migrate(args.project, dry_run=not args.apply)
         sys.stdout.write(json.dumps(result, ensure_ascii=False, indent=2) + "\n")

package/harness/bundles/general/cursor/scripts/harness_review.py

@@ -0,0 +1,326 @@
+#!/usr/bin/env python3
+"""Harness review findings / fixback dispositions sidecar.
+
+Structured source of truth for review output; Markdown reports are a human
+projection of these sidecars, never the counting source.
+
+Files (under the change state root):
+  reports/review/review-findings.json
+  reports/review/fixback-dispositions.json
+
+Python 3.10+, stdlib only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+import uuid
+from pathlib import Path
+from typing import Any
+
+SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+import harness_paths  # noqa: E402
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8")
+
+SEVERITIES = {"RED", "YELLOW", "OK"}
+DISPOSITIONS = {"OPEN", "FIXED", "ACCEPTED_RISK", "DEFERRED", "UNKNOWN"}
+FINDINGS_REL = Path("reports") / "review" / "review-findings.json"
+DISPOSITIONS_REL = Path("reports") / "review" / "fixback-dispositions.json"
+_REQUIRED_FINDING_FIELDS = ("dimension", "severity", "path", "line", "title")
+
+
+def _write_json_atomic(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    text = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.{uuid.uuid4().hex}.tmp")
+    try:
+        tmp.write_text(text, encoding="utf-8", newline="\n")
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def _read_json(path: Path) -> Any:
+    return json.loads(path.read_text(encoding="utf-8-sig"))
+
+
+def _state_dir(change_dir: Path) -> Path:
+    return Path(harness_paths.resolve_state_dir_for_contract(change_dir))
+
+
+def findings_path(change_dir: Path) -> Path:
+    return _state_dir(change_dir) / FINDINGS_REL
+
+
+def dispositions_path(change_dir: Path) -> Path:
+    return _state_dir(change_dir) / DISPOSITIONS_REL
+
+
+def _normalize_title(title: str) -> str:
+    return re.sub(r"\s+", " ", title.strip().lower())
+
+
+def stable_finding_id(
+    run_id: str, dimension: str, path: str, line: int, title: str
+) -> str:
+    """Stable finding identity (run + dimension + canonical path + line + title)."""
+    canonical_path = str(path).replace("\\", "/").strip("/").lower()
+    basis = (
+        f"{run_id}|{dimension.strip().lower()}|{canonical_path}|{int(line)}|"
+        f"{_normalize_title(title)}"
+    )
+    return "f-" + hashlib.sha256(basis.encode("utf-8")).hexdigest()[:16]
+
+
+def validate_findings(doc: Any) -> list[str]:
+    problems: list[str] = []
+    if not isinstance(doc, dict):
+        return ["findings document must be an object"]
+    if not isinstance(doc.get("runId"), str) or not doc["runId"].strip():
+        problems.append("runId is required")
+    findings = doc.get("findings")
+    if not isinstance(findings, list):
+        problems.append("findings must be a list")
+        return problems
+    for index, finding in enumerate(findings):
+        if not isinstance(finding, dict):
+            problems.append(f"findings[{index}] must be an object")
+            continue
+        for field in _REQUIRED_FINDING_FIELDS:
+            if field not in finding:
+                problems.append(f"findings[{index}].{field} is required")
+        severity = finding.get("severity")
+        if severity is not None and severity not in SEVERITIES:
+            problems.append(
+                f"findings[{index}].severity must be one of {sorted(SEVERITIES)}"
+            )
+        line = finding.get("line")
+        if line is not None and (not isinstance(line, int) or line < 0):
+            problems.append(f"findings[{index}].line must be a non-negative int")
+    return problems
+
+
+def write_findings(change_dir: Path, doc: dict[str, Any]) -> dict[str, Any]:
+    problems = validate_findings(doc)
+    if problems:
+        return {"ok": False, "code": "FINDINGS_INVALID", "problems": problems}
+    run_id = doc["runId"]
+    assigned: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for finding in doc["findings"]:
+        fid = stable_finding_id(
+            run_id,
+            finding["dimension"],
+            finding["path"],
+            finding["line"],
+            finding["title"],
+        )
+        suffix = 2
+        unique = fid
+        while unique in seen:
+            unique = f"{fid}-{suffix}"
+            suffix += 1
+        seen.add(unique)
+        entry = dict(finding)
+        entry["id"] = unique
+        assigned.append(entry)
+    payload = {
+        "schemaVersion": 1,
+        "runId": run_id,
+        "changeName": doc.get("changeName") or Path(change_dir).name,
+        "findings": assigned,
+    }
+    out = findings_path(change_dir)
+    _write_json_atomic(out, payload)
+    return {"ok": True, "code": "FINDINGS_WRITTEN", "path": str(out),
+            "count": len(assigned)}
+
+
+def _load_findings(change_dir: Path) -> dict[str, Any] | None:
+    path = findings_path(change_dir)
+    if not path.is_file():
+        return None
+    try:
+        data = _read_json(path)
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def validate_dispositions(
+    doc: Any, known_ids: set[str]
+) -> list[str]:
+    problems: list[str] = []
+    if not isinstance(doc, dict):
+        return ["dispositions document must be an object"]
+    dispositions = doc.get("dispositions")
+    if not isinstance(dispositions, list):
+        return ["dispositions must be a list"]
+    for index, item in enumerate(dispositions):
+        if not isinstance(item, dict):
+            problems.append(f"dispositions[{index}] must be an object")
+            continue
+        fid = item.get("findingId")
+        if not isinstance(fid, str) or not fid.strip():
+            problems.append(f"dispositions[{index}].findingId is required")
+        elif fid not in known_ids:
+            problems.append(f"dispositions[{index}].findingId unknown: {fid}")
+        value = item.get("disposition")
+        if value not in DISPOSITIONS:
+            problems.append(
+                f"dispositions[{index}].disposition must be one of "
+                f"{sorted(DISPOSITIONS)}"
+            )
+    return problems
+
+
+def write_dispositions(change_dir: Path, doc: dict[str, Any]) -> dict[str, Any]:
+    findings_doc = _load_findings(change_dir)
+    known_ids = {
+        f.get("id") for f in (findings_doc or {}).get("findings", [])
+        if isinstance(f, dict)
+    }
+    problems = validate_dispositions(doc, known_ids)
+    if problems:
+        return {"ok": False, "code": "DISPOSITIONS_INVALID", "problems": problems}
+    payload = {
+        "schemaVersion": 1,
+        "runId": doc.get("runId"),
+        "dispositions": doc["dispositions"],
+    }
+    out = dispositions_path(change_dir)
+    _write_json_atomic(out, payload)
+    return {"ok": True, "code": "DISPOSITIONS_WRITTEN", "path": str(out)}
+
+
+def status(change_dir: Path) -> dict[str, Any]:
+    findings_doc = _load_findings(change_dir)
+    if findings_doc is None:
+        return {
+            "ok": True,
+            "code": "NO_FINDINGS",
+            "counts": {"RED": 0, "YELLOW": 0, "OK": 0},
+            "dispositions": {},
+            "items": [],
+        }
+    dispositions_doc: dict[str, Any] = {}
+    dpath = dispositions_path(change_dir)
+    if dpath.is_file():
+        try:
+            loaded = _read_json(dpath)
+            if isinstance(loaded, dict):
+                dispositions_doc = loaded
+        except (OSError, json.JSONDecodeError):
+            dispositions_doc = {}
+    by_id = {
+        item.get("findingId"): item
+        for item in dispositions_doc.get("dispositions", [])
+        if isinstance(item, dict)
+    }
+    counts = {"RED": 0, "YELLOW": 0, "OK": 0}
+    disposition_counts: dict[str, int] = {}
+    items: list[dict[str, Any]] = []
+    for finding in findings_doc.get("findings", []):
+        severity = finding.get("severity")
+        if severity in counts:
+            counts[severity] += 1
+        entry = by_id.get(finding.get("id"))
+        disposition = entry.get("disposition") if entry else None
+        if disposition not in DISPOSITIONS:
+            disposition = "UNKNOWN"
+        disposition_counts[disposition] = disposition_counts.get(disposition, 0) + 1
+        items.append(
+            {
+                "id": finding.get("id"),
+                "severity": severity,
+                "path": finding.get("path"),
+                "line": finding.get("line"),
+                "title": finding.get("title"),
+                "disposition": disposition,
+            }
+        )
+    return {
+        "ok": True,
+        "code": "STATUS",
+        "runId": findings_doc.get("runId"),
+        "counts": counts,
+        "dispositions": disposition_counts,
+        "items": items,
+    }
+
+
+# ------------------------------------------------------------------- CLI
+
+
+def _emit(payload: Any, *, as_json: bool) -> int:
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+    return 0 if payload.get("ok") else 1
+
+
+def cmd_validate_findings(args: argparse.Namespace) -> int:
+    doc = _read_json(Path(args.input))
+    problems = validate_findings(doc)
+    payload = {"ok": not problems, "problems": problems}
+    return _emit(payload, as_json=True)
+
+
+def cmd_write_findings(args: argparse.Namespace) -> int:
+    doc = _read_json(Path(args.input))
+    return _emit(write_findings(Path(args.change_dir), doc), as_json=True)
+
+
+def cmd_write_dispositions(args: argparse.Namespace) -> int:
+    doc = _read_json(Path(args.input))
+    return _emit(write_dispositions(Path(args.change_dir), doc), as_json=True)
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    return _emit(status(Path(args.change_dir)), as_json=True)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="harness_review.py")
+    sub = parser.add_subparsers(dest="command_name", required=True)
+
+    p_validate = sub.add_parser("validate-findings")
+    p_validate.add_argument("--input", required=True)
+    p_validate.set_defaults(func=cmd_validate_findings)
+
+    p_findings = sub.add_parser("write-findings")
+    p_findings.add_argument("--change-dir", required=True)
+    p_findings.add_argument("--input", required=True)
+    p_findings.set_defaults(func=cmd_write_findings)
+
+    p_dispositions = sub.add_parser("write-dispositions")
+    p_dispositions.add_argument("--change-dir", required=True)
+    p_dispositions.add_argument("--input", required=True)
+    p_dispositions.set_defaults(func=cmd_write_dispositions)
+
+    p_status = sub.add_parser("status")
+    p_status.add_argument("--change-dir", required=True)
+    p_status.set_defaults(func=cmd_status)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())