sid-harness 0.3.0__py3-none-any.whl

sid_harness/policy/repo_policy.py

@@ -0,0 +1,626 @@
+"""SUB-57 — repo policy: the platform's own ship discipline, enforced locally.
+
+The harness edits the user's real tree (SUB-54). This module is where the
+platform's rules become visible to that loop and are enforced *before* the
+harness offers a mutating action — with the platform's own explanation, not a
+paraphrase:
+
+* **integration-only main checkout** — a source commit staged in the MAIN
+  worktree is refused (Gate 31 ``main_checkout_integration_only_gate.py``;
+  JB_DECISIONS 2026-07-18 integration-only-main-checkout). Source commits
+  happen in a session worktree.
+* **main moves only through the landing gate** — ``git push origin HEAD:main``
+  is refused (JB_DECISIONS 2026-09-08 main-requires-server-landing-gate); main
+  moves only through ``bash scripts/admin/push_main_checked.sh`` (reached via
+  ``ship_worktree.sh``).
+* **resolve its own worktree** — the operating worktree is resolved from the
+  repo, never the ambient cwd (LESSONS #22).
+* **the pre-push battery runs before a commit is offered** — and the battery is
+  the platform's own hook, discovered from the filesystem.
+
+Two invariants, both load-bearing:
+
+* **this policy module never ships** — it has no push and no commit; it returns
+  the sanctioned command for the operator to run. The explicit opt-in
+  ``sid run --git-write`` path (``git_write.py``) owns branch/commit/PR under
+  its own hard guards: never main/master, never forced, per-step approval.
+* the gate inventory is read from the **filesystem** (``scripts/gates/`` and
+  ``.git-hooks/pre-push``), never a hardcoded list, and the commit decision
+  delegates to the platform gate module itself — so the harness cannot weaken
+  or drift from a gate.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+
+from ..local_workspace import git_info
+
+_GIT_TIMEOUT = 30.0
+
+# The canonical gate that owns the integration-only-main decision. Named here
+# so the decision is *delegated* to it, never reimplemented; the file itself is
+# discovered on disk (see ``load_gate_module``).
+_MAIN_CHECKOUT_GATE = "main_checkout_integration_only_gate"
+
+_MAIN_REF = "refs/heads/main"
+
+# Gate scripts are referenced from the hook two ways: the tracked path
+# (``scripts/gates/x.py``) and the ``$GATES_DIR`` variable the hook defines.
+_WIRED_RE = re.compile(r"(?:scripts/gates/|\$\{?GATES_DIR\}?/)([A-Za-z0-9_]+)\.py")
+
+# ``git push`` targets that mean "main" — a colon refspec to main, a bare
+# ``origin main``, or a pre-push line whose remote ref is main.
+_MAIN_TARGET_RE = re.compile(r"(?::\s*(?:refs/heads/)?main\b)|(?:\borigin\s+main\b)")
+
+
+# --------------------------------------------------------------------------- #
+# Decisions
+# --------------------------------------------------------------------------- #
+@dataclass(frozen=True)
+class PolicyDecision:
+    """The result of a policy check, with the platform's own explanation."""
+
+    allowed: bool
+    code: str
+    explanation: str
+    remedy: str = ""
+    command: str | None = None
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "allowed": self.allowed,
+            "code": self.code,
+            "explanation": self.explanation,
+            "remedy": self.remedy,
+            "command": self.command,
+        }
+
+
+@dataclass(frozen=True)
+class WorktreeResolution:
+    """Where the harness may operate: its own worktree, never the ambient cwd."""
+
+    directory: Path
+    is_repo: bool
+    root: Path | None
+    main_root: Path | None
+    is_worktree: bool
+    is_main_checkout: bool
+    branch: str | None
+    head: str | None
+    session_worktrees: tuple[str, ...]
+    reason: str
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "directory": str(self.directory),
+            "is_repo": self.is_repo,
+            "root": str(self.root) if self.root else None,
+            "main_root": str(self.main_root) if self.main_root else None,
+            "is_worktree": self.is_worktree,
+            "is_main_checkout": self.is_main_checkout,
+            "branch": self.branch,
+            "head": self.head,
+            "session_worktrees": list(self.session_worktrees),
+            "reason": self.reason,
+        }
+
+
+@dataclass(frozen=True)
+class GateInventory:
+    """The gate battery, read from the filesystem — never a hardcoded list."""
+
+    repo_root: Path | None
+    gates_dir: Path | None
+    gate_files: tuple[str, ...]
+    hook_path: Path | None
+    wired_gates: tuple[str, ...]
+    missing_wired: tuple[str, ...]
+    unwired_gates: tuple[str, ...]
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "repo_root": str(self.repo_root) if self.repo_root else None,
+            "gates_dir": str(self.gates_dir) if self.gates_dir else None,
+            "gate_files": list(self.gate_files),
+            "hook_path": str(self.hook_path) if self.hook_path else None,
+            "wired_gates": list(self.wired_gates),
+            "missing_wired": list(self.missing_wired),
+            "unwired_gates": list(self.unwired_gates),
+        }
+
+
+# --------------------------------------------------------------------------- #
+# Repo / worktree resolution
+# --------------------------------------------------------------------------- #
+def _run_git(root: str | os.PathLike[str], args: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", "-C", str(root), *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        timeout=_GIT_TIMEOUT,
+    )
+
+
+def _norm(path: object) -> str:
+    return os.path.normcase(os.path.normpath(str(path or "")))
+
+
+def _worktree_entries(root: str | os.PathLike[str]) -> list[dict[str, str]]:
+    """Parse ``git worktree list --porcelain`` into ordered entries."""
+    proc = _run_git(root, ["worktree", "list", "--porcelain"])
+    if proc.returncode != 0:
+        return []
+    entries: list[dict[str, str]] = []
+    current: dict[str, str] | None = None
+    for line in proc.stdout.splitlines():
+        if line.startswith("worktree "):
+            current = {"path": line[len("worktree ") :].strip()}
+            entries.append(current)
+        elif line.startswith("branch ") and current is not None:
+            current["branch"] = line[len("branch ") :].strip()
+        elif line.startswith("detached") and current is not None:
+            current["detached"] = "1"
+    return entries
+
+
+def find_repo_root(directory: str | os.PathLike[str]) -> Path | None:
+    """The repository (or worktree) top level for ``directory``, else ``None``."""
+    info = git_info(directory)
+    return info.root if info.is_repo else None
+
+
+def main_worktree_root(directory: str | os.PathLike[str]) -> Path | None:
+    """The repo's MAIN worktree — the first entry of ``git worktree list``.
+
+    Same definition Gate 31 uses, resolved from an explicit directory (never
+    the ambient cwd).
+    """
+    root = find_repo_root(directory)
+    if root is None:
+        return None
+    entries = _worktree_entries(root)
+    if not entries:
+        return None
+    return Path(entries[0]["path"])
+
+
+def resolve_session_worktree(directory: str | os.PathLike[str]) -> WorktreeResolution:
+    """Resolve the worktree the harness should operate in (LESSONS #22).
+
+    A linked worktree resolves to itself. The MAIN checkout is
+    integration-only: it is reported as such (``is_main_checkout``) rather than
+    silently accepted as a place to commit source, and its sibling worktrees
+    are listed so the caller can pick one.
+    """
+    base = Path(directory).expanduser().resolve()
+    info = git_info(base)
+    if not info.is_repo or info.root is None:
+        return WorktreeResolution(
+            directory=base,
+            is_repo=False,
+            root=None,
+            main_root=None,
+            is_worktree=False,
+            is_main_checkout=False,
+            branch=None,
+            head=None,
+            session_worktrees=(),
+            reason="Not a git repository; no worktree policy applies.",
+        )
+
+    main_root = main_worktree_root(base)
+    is_main_checkout = main_root is not None and _norm(info.root) == _norm(main_root)
+
+    siblings: list[str] = []
+    for entry in _worktree_entries(info.root):
+        path = entry.get("path")
+        if path and _norm(path) != _norm(main_root):
+            siblings.append(path)
+
+    if is_main_checkout:
+        reason = (
+            "This is the MAIN checkout. It is integration-only: source commits "
+            "belong in a session worktree."
+        )
+    else:
+        reason = "This is a linked session worktree; source commits are allowed here."
+
+    return WorktreeResolution(
+        directory=base,
+        is_repo=True,
+        root=info.root,
+        main_root=main_root,
+        is_worktree=info.is_worktree,
+        is_main_checkout=is_main_checkout,
+        branch=info.branch,
+        head=info.head,
+        session_worktrees=tuple(siblings),
+        reason=reason,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Gate inventory — read from the filesystem
+# --------------------------------------------------------------------------- #
+def _wired_gate_names(hook_text: str) -> tuple[str, ...]:
+    names: list[str] = []
+    for match in _WIRED_RE.finditer(hook_text):
+        name = match.group(1)
+        if name not in names:
+            names.append(name)
+    return tuple(names)
+
+
+def gate_inventory(directory: str | os.PathLike[str]) -> GateInventory:
+    """Enumerate the gate battery from disk: ``scripts/gates/`` + the hook.
+
+    The hook (``.git-hooks/pre-push``) is the canonical ordering; its gate
+    references are parsed in order of first appearance. Nothing here is a
+    hardcoded list — add a gate file or wire it into the hook and it appears.
+    """
+    root = find_repo_root(directory)
+    if root is None:
+        return GateInventory(None, None, (), None, (), (), ())
+
+    gates_dir = root / "scripts" / "gates"
+    gate_files: tuple[str, ...] = ()
+    if gates_dir.is_dir():
+        gate_files = tuple(
+            sorted(p.stem for p in gates_dir.glob("*.py") if p.name != "__init__.py")
+        )
+
+    hook_candidate = root / ".git-hooks" / "pre-push"
+    hook_path = hook_candidate if hook_candidate.is_file() else None
+    wired: tuple[str, ...] = ()
+    if hook_path is not None:
+        try:
+            wired = _wired_gate_names(hook_path.read_text(encoding="utf-8", errors="replace"))
+        except OSError:  # pragma: no cover - defensive
+            wired = ()
+
+    missing_wired = tuple(name for name in wired if name not in gate_files)
+    unwired = tuple(name for name in gate_files if name not in wired)
+    return GateInventory(
+        repo_root=root,
+        gates_dir=gates_dir if gates_dir.is_dir() else None,
+        gate_files=gate_files,
+        hook_path=hook_path,
+        wired_gates=wired,
+        missing_wired=missing_wired,
+        unwired_gates=unwired,
+    )
+
+
+def load_gate_module(repo_root: str | os.PathLike[str], name: str) -> ModuleType | None:
+    """Load a platform gate module from ``scripts/gates/`` on disk.
+
+    Used so the harness's decisions ARE the gate's decisions — the check is not
+    reimplemented here, so it cannot drift from or weaken the gate.
+    """
+    path = Path(repo_root) / "scripts" / "gates" / f"{name}.py"
+    if not path.is_file():
+        return None
+    spec = importlib.util.spec_from_file_location(f"_jb_gate_{name}", path)
+    if spec is None or spec.loader is None:  # pragma: no cover - defensive
+        return None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+# --------------------------------------------------------------------------- #
+# Checks
+# --------------------------------------------------------------------------- #
+def check_source_commit(
+    directory: str | os.PathLike[str],
+    staged_paths: list[str] | tuple[str, ...],
+    message: str = "",
+    *,
+    env_override: bool = False,
+) -> PolicyDecision:
+    """Refuse a source commit staged in the MAIN checkout (Gate 31).
+
+    The decision is delegated to ``main_checkout_integration_only_gate`` read
+    from the filesystem; if that gate cannot be read, the check fails closed.
+    """
+    resolution = resolve_session_worktree(directory)
+    if not resolution.is_repo:
+        return PolicyDecision(
+            allowed=True,
+            code="not-a-repo",
+            explanation="Not a git repository; the main-checkout policy does not apply.",
+        )
+    if not resolution.is_main_checkout:
+        return PolicyDecision(
+            allowed=True,
+            code="session-worktree",
+            explanation=(
+                f"Source commits are allowed here: {resolution.root} is a session "
+                f"worktree (branch {resolution.branch or '(detached)'})."
+            ),
+        )
+
+    gate = load_gate_module(resolution.root, _MAIN_CHECKOUT_GATE)
+    if gate is None:
+        return PolicyDecision(
+            allowed=False,
+            code="gate-missing",
+            explanation=(
+                "Refusing: this is the MAIN checkout (integration-only) and the "
+                f"canonical gate {_MAIN_CHECKOUT_GATE}.py could not be read from "
+                "the filesystem. Failing closed rather than guessing the policy."
+            ),
+            remedy=(
+                "Restore scripts/gates/main_checkout_integration_only_gate.py, or "
+                "work in a session worktree: bash scripts/admin/session_worktree.sh"
+            ),
+        )
+
+    ok, blocked = gate.evaluate(
+        list(staged_paths), message, True, env_override
+    )
+    if ok:
+        return PolicyDecision(
+            allowed=True,
+            code="coordination-paths",
+            explanation=(
+                "All staged paths are on the coordination/telemetry allowlist; "
+                "this commit may land from the main checkout."
+            ),
+        )
+
+    listing = ", ".join(blocked[:15])
+    if len(blocked) > 15:
+        listing += f", ... and {len(blocked) - 15} more"
+    return PolicyDecision(
+        allowed=False,
+        code="main-checkout-source-commit",
+        explanation=(
+            "The main checkout is integration-only — source commits happen in a "
+            f"session worktree, not here. Staged paths outside the allowlist: {listing}"
+        ),
+        remedy=(
+            "Work in your session worktree (bash scripts/admin/session_worktree.sh "
+            "prints its path), commit there, then ship with "
+            "bash scripts/admin/ship_worktree.sh. Emergency override: "
+            "[override:commit:<reason>] in the subject, or JB_ALLOW_MAIN_COMMIT=1."
+        ),
+    )
+
+
+def preflight_write(
+    directory: str | os.PathLike[str],
+    paths: list[str] | tuple[str, ...],
+) -> PolicyDecision:
+    """Gate a harness write against the platform's main-checkout policy.
+
+    Only applies inside the platform repo — the one that ships the canonical
+    gate. Any other ``--dir`` is a plain project and no local ship policy
+    applies, so the harness is a general client, not a platform-only tool.
+
+    Inside the platform repo the decision is DELEGATED to
+    ``check_source_commit`` (Gate 31's own allowlist), so the harness cannot
+    drift from or weaken the gate.
+    """
+    resolution = resolve_session_worktree(directory)
+    if not resolution.is_repo or resolution.root is None:
+        return PolicyDecision(
+            allowed=True,
+            code="not-a-repo",
+            explanation="Not a git repository; the platform write policy does not apply.",
+        )
+    gate_path = resolution.root / "scripts" / "gates" / f"{_MAIN_CHECKOUT_GATE}.py"
+    if not gate_path.is_file():
+        return PolicyDecision(
+            allowed=True,
+            code="not-platform-repo",
+            explanation=(
+                "This directory is not the platform repo (no canonical gate on "
+                "disk); no local ship policy applies."
+            ),
+        )
+    return check_source_commit(directory, paths)
+
+
+def pushes_main(refspec: str) -> bool:
+    """True when ``refspec`` targets ``main``.
+
+    Accepts a raw command/refspec (``git push origin HEAD:main``), a bare
+    ``origin main``, or pre-push stdin lines (``<local> <sha> <remote-ref>``).
+    """
+    text = refspec or ""
+    for line in text.splitlines():
+        parts = line.split()
+        if len(parts) >= 3 and parts[2] in (_MAIN_REF, "main"):
+            return True
+    return bool(_MAIN_TARGET_RE.search(text))
+
+
+def check_push(directory: str | os.PathLike[str], refspec: str) -> PolicyDecision:
+    """Refuse ``git push origin HEAD:main`` — main moves only via the landing gate.
+
+    This check exists so a loop that proposes a push to main is told why the
+    platform refuses it and what to run instead. A non-main branch may be
+    pushed only by the explicit ``--git-write`` path.
+    """
+    if not pushes_main(refspec):
+        return PolicyDecision(
+            allowed=True,
+            code="not-main",
+            explanation=(
+                "This push does not target main, so the landing gate is not "
+                "involved. (Only the explicit --git-write path pushes a branch; "
+                "shipping to main stays the platform's path.)"
+            ),
+        )
+    return PolicyDecision(
+        allowed=False,
+        code="push-to-main",
+        explanation=(
+            "Refused: main only accepts SHAs that passed the server-side landing "
+            "gate (JB_DECISIONS 2026-09-08). A direct 'git push origin HEAD:main' "
+            "is rejected by the ruleset."
+        ),
+        remedy=(
+            "Ship the worktree branch instead: bash scripts/admin/ship_worktree.sh "
+            "(it rebases onto origin/main, runs the proof battery, and moves main "
+            "through bash scripts/admin/push_main_checked.sh)."
+        ),
+        command="bash scripts/admin/ship_worktree.sh",
+    )
+
+
+def _default_battery_runner(
+    hook_path: Path, ref_lines: str, cwd: Path
+) -> tuple[int, str]:
+    bash = os.environ.get("SID_HARNESS_BASH") or "bash"
+    proc = subprocess.run(
+        [bash, str(hook_path)],
+        input=ref_lines + "\n",
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        cwd=str(cwd),
+    )
+    return proc.returncode, (proc.stdout or "") + (proc.stderr or "")
+
+
+def run_pre_push_battery(
+    directory: str | os.PathLike[str],
+    *,
+    base: str = "origin/main",
+    runner=None,
+) -> PolicyDecision:
+    """Run the platform's own pre-push battery before a commit is offered.
+
+    The battery is the tracked hook ``.git-hooks/pre-push`` discovered on disk —
+    the harness does not carry a second list of checks. ``runner`` is injectable
+    for tests; the default shells the hook with the current branch's push line.
+    """
+    resolution = resolve_session_worktree(directory)
+    if not resolution.is_repo or resolution.root is None:
+        return PolicyDecision(
+            allowed=False,
+            code="not-a-repo",
+            explanation="Refusing: not a git repository; no pre-push battery to run.",
+        )
+
+    inventory = gate_inventory(resolution.root)
+    if inventory.hook_path is None:
+        return PolicyDecision(
+            allowed=False,
+            code="hook-missing",
+            explanation=(
+                "Refusing: the canonical pre-push battery (.git-hooks/pre-push) "
+                "is not present, so the platform's checks cannot be run."
+            ),
+            remedy="Restore .git-hooks/pre-push (bash scripts/admin/install_hooks.sh).",
+        )
+
+    branch = resolution.branch or "HEAD"
+    head = resolution.head or "HEAD"
+    ref_lines = f"refs/heads/{branch} {head} refs/heads/{branch}"
+    run = runner or _default_battery_runner
+    returncode, output = run(inventory.hook_path, ref_lines, resolution.root)
+    if returncode == 0:
+        return PolicyDecision(
+            allowed=True,
+            code="battery-passed",
+            explanation=(
+                f"Pre-push battery passed ({len(inventory.wired_gates)} wired "
+                f"gate(s); {len(inventory.gate_files)} on disk)."
+            ),
+        )
+    return PolicyDecision(
+        allowed=False,
+        code="battery-failed",
+        explanation=(output.strip() or "pre-push battery failed."),
+        remedy="Fix the reported gate(s) before committing; the platform would block this range.",
+    )
+
+
+def _commit_command(staged_paths: list[str] | tuple[str, ...]) -> str:
+    from shlex import quote
+
+    paths = " ".join(quote(p) for p in sorted(staged_paths))
+    return f'git commit -F "$MSG" -- {paths}'.strip()
+
+
+def offer_commit(
+    directory: str | os.PathLike[str],
+    staged_paths: list[str] | tuple[str, ...],
+    message: str,
+    *,
+    base: str = "origin/main",
+    battery_runner=None,
+) -> PolicyDecision:
+    """Decide whether a source commit may be offered, battery included.
+
+    Runs the main-checkout refusal first, then the pre-push battery. When both
+    pass it returns the sanctioned commit command — the harness never runs it
+    and never pushes.
+    """
+    commit_decision = check_source_commit(directory, staged_paths, message)
+    if not commit_decision.allowed:
+        return commit_decision
+
+    battery = run_pre_push_battery(directory, base=base, runner=battery_runner)
+    if not battery.allowed:
+        return battery
+
+    resolution = resolve_session_worktree(directory)
+    return PolicyDecision(
+        allowed=True,
+        code="offer-commit",
+        explanation=(
+            f"Source commit may be offered from {resolution.root} "
+            f"(branch {resolution.branch or '(detached)'}); pre-push battery passed."
+        ),
+        remedy=(
+            "This policy check never commits or pushes; the explicit --git-write "
+            "path is the only write path (and it refuses main/master). Run the "
+            "command yourself, or ship the branch with: "
+            "bash scripts/admin/ship_worktree.sh"
+        ),
+        command=_commit_command(staged_paths),
+    )
+
+
+def policy_report(directory: str | os.PathLike[str]) -> dict[str, object]:
+    """A single read-only summary for diagnostics/CLI: worktree + inventory."""
+    resolution = resolve_session_worktree(directory)
+    inventory = gate_inventory(directory)
+    return {
+        "worktree": resolution.as_dict(),
+        "gates": inventory.as_dict(),
+    }
+
+
+__all__ = [
+    "GateInventory",
+    "PolicyDecision",
+    "WorktreeResolution",
+    "check_push",
+    "check_source_commit",
+    "find_repo_root",
+    "gate_inventory",
+    "load_gate_module",
+    "main_worktree_root",
+    "offer_commit",
+    "policy_report",
+    "preflight_write",
+    "pushes_main",
+    "resolve_session_worktree",
+    "run_pre_push_battery",
+]