Merge pull request #69 from eduralph/feat/67-delegated-gates

feat(gates): first-class delegated gates via a host runner

Author: eduralph

copier.yml

@@ -152,3 +152,14 @@ leaves_mode:
     Stubs (offline; recommended to start): stub
     Real commands: command
   default: stub
+
+# ----------------------------------------------------------------------------
+# Integration: gates (docs 04). A host that already single-sources its gates in its
+# own runner (e.g. `cargo xtask`, `make`, `just`) can DELEGATE to it: set a runner and
+# each gate names a bare sub-command, so PDCA orchestrates the host runner instead of
+# re-declaring the gates (issue #67). Leave blank to declare gate commands inline.
+# ----------------------------------------------------------------------------
+gates_runner:
+  type: str
+  help: "External gate runner to delegate to (e.g. 'cargo xtask'); blank = inline gate commands"
+  default: ""

docs/05-check.md

@@ -66,6 +66,28 @@ They become NEEDS-HUMAN items.
 > *new* failure is `[delta]` (your fix may have caused it). You'll see a `[delta]`
 > bite in [step 06](06-signoff.md).
 
+### Delegating to a host runner
+
+If your project already single-sources its gates in its own runner (`cargo xtask`,
+`make`, `just`, …), don't re-declare them in `pdca.toml` — **delegate**. Set a runner
+and give each check a bare `subcmd`:
+
+```toml
+[gates]
+runner = "cargo xtask"
+checks = [
+  { id = "C4-verify", tier = "C4", label = "fix verified red->green", subcmd = "verify", gating = true,  scope = "bundle" },
+  { id = "T3-suite",  tier = "T3", label = "runtime suite",           subcmd = "test",   gating = false, scope = "repo" },
+]
+```
+
+PDCA runs `cargo xtask verify` / `cargo xtask test` and maps the results onto the
+5/5/1 — the host runner stays the single source of truth; PDCA only orchestrates it.
+A full `cmd` (e.g. `cmd = "cargo xtask ci"`) still works for wholesale delegation. A
+missing runner surfaces as a clear failing row (`runner '…' not found on PATH`), never
+a crash. Set it at render time with the `gates_runner` copier question, or later in
+`pdca.toml`.
+
 ## 2. Reviewer — the decorrelated second opinion
 
 Next the `reviewer` leaf runs against `{patch.diff, test, brief.md,

template/pdca.toml.jinja

@@ -192,6 +192,22 @@ argv = ["claude", "--agent", "publisher", "--permission-mode", "acceptEdits"]
 # full suite — the full suite mixes green tests with known-bug repros, so it is a
 # characterization, not a pass/fail signal. Cite each tier's rules back to the
 # project's normative ruleset (docs/INTEGRATION.md §4) so the gate is auditable.
+#
+# DELEGATED GATES (issue #67). If your project already single-sources its gates in its
+# own runner, point `runner` at it and give each check a bare `subcmd` instead of a full
+# `cmd`; PDCA runs `<runner> <subcmd>` and treats the host runner as the source of truth
+# (it never re-declares the gates). A missing runner surfaces as a clear failing row, not
+# a crash. A full `cmd` (e.g. `cmd = "cargo xtask ci"`) still works for wholesale delegation.
 [gates]
+{% if gates_runner %}
+# Delegated to the host runner — PDCA orchestrates it, the host owns the gate definitions.
+runner = "{{ gates_runner }}"
+checks = [
+  # Map the host's named sub-gates onto the 5/5/1 tiers. Each runs `{{ gates_runner }} <subcmd>`.
+  # { id = "C4-verify", tier = "C4", label = "fix verified red->green", subcmd = "verify", gating = true, scope = "bundle" },
+  # { id = "T3-suite",  tier = "T3", label = "runtime suite (baseline)", subcmd = "test",   gating = false, scope = "repo" },
+]
+{% else %}
 checks = []
+{% endif %}
 

template/src/pdca_harness/config.py

@@ -85,6 +85,10 @@ class Config:
     issue_trailer: str = "Fixes #{id}"  # commit/PR trailer; "" → none enforced
     repo_checkouts: dict[str, str] = field(default_factory=dict)  # repo_spec → local path
     gates_checks: list[dict] = field(default_factory=list)
+    # Delegated gates (issue #67): a host runner that single-sources its own gates
+    # (e.g. "cargo xtask"). A check's bare ``subcmd`` is run as ``<runner> <subcmd>``, so
+    # PDCA orchestrates the host runner instead of re-declaring the gates. "" ⇒ inline only.
+    gates_runner: str = ""
     # Target-aware gate selection (docs 04). A check may carry ``target`` (a label or
     # list); it runs iff its labels are a SUBSET of the bundle's label set. The bundle is
     # classified from its brief on two axes: a PRIMARY one (``gate_target_match``: label →
@@ -135,6 +139,7 @@ def load(cls, root: Path | None = None) -> "Config":
         leaves = data.get("leaves", {})
         gates = data.get("gates", {})
         gates_checks = list(gates.get("checks", []))
+        gates_runner = gates.get("runner", "")
         # Additive target flags: label → {field, substring}. A bare string is shorthand
         # for the "Repo + branch target" field (so flags and the primary axis can share it).
         gate_target_flags = {
@@ -207,6 +212,7 @@ def leaf(name: str) -> LeafConfig:
             act=leaf("act"),
             author=data.get("project", {}).get("author", ""),
             gates_checks=gates_checks,
+            gates_runner=gates_runner,
             lanes=lanes,
             close_dispositions=close_dispositions,
         )

template/src/pdca_harness/gates.py

@@ -33,6 +33,8 @@
 from __future__ import annotations
 
 import json
+import shlex
+import shutil
 import sys
 from pathlib import Path
 
@@ -171,15 +173,42 @@ def _run_checks(cfg: Config, *, cwd: Path, bundle: Path | None, scopes: tuple[st
                       f"(target={chk.get('target')}, bundle labels {set(labels)})",
                       file=sys.stderr, flush=True)
             continue
-        configured.append(_run_one(chk, cwd=cwd, bundle=bundle))
+        configured.append(_run_one(chk, cwd=cwd, bundle=bundle, runner=cfg.gates_runner))
     # Overlay the configured gate results onto the complete 5/5/1 matrix.
     return _assemble_matrix(configured, stub=False)
 
 
-def _run_one(chk: dict, *, cwd: Path, bundle: Path | None) -> dict:
-    cmd = chk.get("cmd", "")
+def _delegated_cmd(chk: dict, runner: str) -> tuple[str, str]:
+    """Resolve a check's command. A check may declare a bare ``subcmd`` (issue #67)
+    delegated to the host's single-sourced ``[gates] runner`` (e.g. ``cargo xtask``),
+    so PDCA orchestrates the host runner without re-declaring the gate; or a full ``cmd``
+    (which may itself be ``cargo xtask ci`` — wholesale delegation). Returns
+    ``(cmd, error)``: a non-empty ``error`` is a misconfiguration to surface as a fail
+    row (a ``subcmd`` with no runner, or a runner binary missing from PATH)."""
+    subcmd = chk.get("subcmd", "")
+    if not subcmd:
+        return chk.get("cmd", ""), ""
+    if not runner:
+        return "", "check declares 'subcmd' but [gates] runner is unset"
+    first = shlex.split(runner)[0] if runner.strip() else ""
+    # A clear error beats a cryptic shell failure when the host runner isn't installed.
+    if first and not first.startswith((".", "/")) and shutil.which(first) is None:
+        return "", f"delegated runner '{first}' not found on PATH — install it or fix [gates].runner"
+    return f"{runner} {subcmd}", ""
+
+
+def _run_one(chk: dict, *, cwd: Path, bundle: Path | None, runner: str = "") -> dict:
+    cmd, cmd_error = _delegated_cmd(chk, runner)
     gating = bool(chk.get("gating", True))
     label = f"{chk.get('id', '')}: {chk.get('label', '')}".strip(": ")
+    if cmd_error:
+        # Misconfigured delegation — surface as a failing row with a fix hint, never crash.
+        print(f"  · gate {label}: {cmd_error}", file=sys.stderr, flush=True)
+        return _row(
+            f"{chk.get('tier', '?')} {chk.get('label', chk.get('id', ''))}",
+            "fail", oracle=chk.get("subcmd", "") or cmd, rule_id=chk.get("id", ""),
+            path_line=cmd_error[:120], gating=gating, element=chk.get("tier", ""),
+        )
     env = {"PDCA_BUNDLE": str(bundle)} if bundle is not None else None
     # Stack mode (issue #54): when the brief names an existing PR's head to stack onto,
     # expose it as PDCA_BASE so the verify/repro gate establishes red→green on THAT branch

template/tests/test_driver_slice.py

@@ -312,6 +312,64 @@ def test_working_tree_skips_bundle_scope(self) -> None:
         self.assertNotIn("b", {r["rule_id"] for r in result["rows"]})
 
 
+class DelegatedGates(unittest.TestCase):
+    """Delegated gates (issue #67): a host runner single-sources the gates; a check's
+    bare `subcmd` runs as `<runner> <subcmd>`, so PDCA orchestrates without re-declaring."""
+
+    def setUp(self) -> None:
+        self.tmp = Path(tempfile.mkdtemp())
+
+    def tearDown(self) -> None:
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def _cfg(self, checks: list[dict], runner: str = "") -> Config:
+        cfg = _stub_config(self.tmp)
+        cfg.gates_checks = checks
+        cfg.gates_runner = runner
+        return cfg
+
+    def test_subcmd_resolved_against_runner(self) -> None:
+        # `subcmd` is run as `<runner> <subcmd>`; the resolved command is the oracle.
+        cfg = self._cfg(
+            [{"id": "ci", "tier": "T1", "label": "host ci", "subcmd": "ok-step",
+              "gating": True, "scope": "repo"}],
+            runner="echo")
+        result = gates.run_working_tree(cfg)
+        row = next(r for r in result["rows"] if r["rule_id"] == "ci")
+        self.assertEqual(row["result"], "pass")           # `echo ok-step` exits 0
+        self.assertEqual(row["oracle"], "echo ok-step")   # runner prefixed
+
+    def test_missing_runner_is_a_clear_failing_row_not_a_crash(self) -> None:
+        cfg = self._cfg(
+            [{"id": "x", "tier": "T1", "label": "host ci", "subcmd": "build",
+              "gating": True, "scope": "repo"}],
+            runner="definitely-not-a-real-binary-zzz xtask")
+        result = gates.run_working_tree(cfg)  # must not raise
+        row = next(r for r in result["rows"] if r["rule_id"] == "x")
+        self.assertEqual(row["result"], "fail")
+        self.assertIn("not found on PATH", row["path_line"])
+
+    def test_subcmd_without_runner_is_flagged(self) -> None:
+        cfg = self._cfg(
+            [{"id": "y", "tier": "T1", "label": "host ci", "subcmd": "build",
+              "gating": True, "scope": "repo"}],
+            runner="")  # subcmd declared but no runner configured
+        result = gates.run_working_tree(cfg)
+        row = next(r for r in result["rows"] if r["rule_id"] == "y")
+        self.assertEqual(row["result"], "fail")
+        self.assertIn("runner is unset", row["path_line"])
+
+    def test_inline_cmd_unaffected_by_runner(self) -> None:
+        # A full `cmd` still runs verbatim even when a runner is configured.
+        cfg = self._cfg(
+            [{"id": "z", "tier": "T1", "label": "inline", "cmd": "true",
+              "gating": True, "scope": "repo"}],
+            runner="echo")
+        row = next(r for r in gates.run_working_tree(cfg)["rows"] if r["rule_id"] == "z")
+        self.assertEqual(row["result"], "pass")
+        self.assertEqual(row["oracle"], "true")  # not prefixed with the runner
+
+
 class BuilderGuard(unittest.TestCase):
     """The PreToolUse hook enforcing the builder's STOP discipline."""