agentic-project-kit 1.0.1__py3-none-any.whl

agentic_project_kit/execution_mode_state.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import shutil
+import subprocess
+from typing import Literal
+
+import yaml
+
+STATE_FILE = Path(".agentic/execution_mode_state.yaml")
+ModeTarget = Literal["local", "remote"]
+
+
+@dataclass(frozen=True)
+class ModeCheckResult:
+    ok: bool
+    state: str
+    target: str
+    branch: str
+    dirty: bool
+    venv_available: bool
+    required_tools: dict[str, str]
+    findings: tuple[str, ...]
+
+
+def _run_git(repo_root: Path, args: list[str]) -> tuple[int, str]:
+    completed = subprocess.run(
+        ["git", *args],
+        cwd=repo_root,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        check=False,
+    )
+    return completed.returncode, completed.stdout.strip()
+
+
+def _current_branch(repo_root: Path) -> str:
+    rc, output = _run_git(repo_root, ["branch", "--show-current"])
+    if rc != 0:
+        return "unknown"
+    return output.strip() or "unknown"
+
+
+def _is_dirty(repo_root: Path) -> bool:
+    rc, output = _run_git(repo_root, ["status", "--short"])
+    if rc != 0:
+        return True
+    return bool(output.strip())
+
+
+def _tool_status(tool: str, repo_root: Path | None = None) -> str:
+    if shutil.which(tool):
+        return "ok"
+    if repo_root is not None and (repo_root / ".venv" / "bin" / tool).exists():
+        return "ok"
+    return "missing"
+
+
+def _venv_available(repo_root: Path) -> bool:
+    return (repo_root / ".venv" / "bin" / "python").exists() or (repo_root / ".venv" / "bin" / "python3").exists()
+
+
+def evaluate_mode_switch(
+    repo_root: Path,
+    target: ModeTarget,
+    expected_branch: str | None = None,
+    require_clean: bool = True,
+) -> ModeCheckResult:
+    repo_root = repo_root.resolve()
+    branch = _current_branch(repo_root)
+    dirty = _is_dirty(repo_root)
+    venv_available = _venv_available(repo_root)
+    required_tools = {tool: _tool_status(tool, repo_root) for tool in ("git", "gh")}
+    if target == "local":
+        required_tools["ruff"] = _tool_status("ruff", repo_root)
+    findings: list[str] = []
+
+    if expected_branch and branch != expected_branch:
+        findings.append(f"branch_mismatch expected={expected_branch} actual={branch}")
+    if require_clean and dirty:
+        findings.append("dirty_worktree")
+    for tool, status in required_tools.items():
+        if status != "ok":
+            findings.append(f"missing_tool={tool}")
+    if target == "local" and not venv_available:
+        findings.append("missing_venv_python")
+
+    ok = not findings
+    if ok:
+        state = "LOCAL_READY" if target == "local" else "REMOTE_READY"
+    elif dirty:
+        state = "DIRTY_LOCAL_BLOCKED"
+    elif any(item.startswith("missing_tool=") or item == "missing_venv_python" for item in findings):
+        state = "TOOLING_BLOCKED"
+    else:
+        state = "MODE_SWITCH_BLOCKED"
+
+    return ModeCheckResult(
+        ok=ok,
+        state=state,
+        target=target,
+        branch=branch,
+        dirty=dirty,
+        venv_available=venv_available,
+        required_tools=required_tools,
+        findings=tuple(findings),
+    )
+
+
+def render_mode_check(result: ModeCheckResult) -> str:
+    lines = [
+        "EXECUTION MODE STATE CHECK",
+        f"target={result.target}",
+        f"state={result.state}",
+        f"branch={result.branch}",
+        f"dirty={str(result.dirty).lower()}",
+        f"venv_available={str(result.venv_available).lower()}",
+        "required_tools:",
+    ]
+    for tool, status in sorted(result.required_tools.items()):
+        lines.append(f"  {tool}: {status}")
+    lines.append("findings:")
+    if result.findings:
+        lines.extend(f"  - {finding}" for finding in result.findings)
+    else:
+        lines.append("  - none")
+    lines.append("### RESULT: PASS ###" if result.ok else "### RESULT: FAIL ###")
+    return "\n".join(lines)
+
+
+def write_mode_state(repo_root: Path, result: ModeCheckResult, reason: str) -> Path:
+    path = repo_root.resolve() / STATE_FILE
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "schema_version": 1,
+        "mode_state": result.state,
+        "target": result.target,
+        "branch": result.branch,
+        "dirty": result.dirty,
+        "venv_available": result.venv_available,
+        "required_tools": result.required_tools,
+        "findings": list(result.findings),
+        "reason": reason,
+    }
+    path.write_text(yaml.safe_dump(payload, sort_keys=True), encoding="utf-8")
+    return path

agentic_project_kit/final_summary_contract.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import re
+
+SUMMARY_FIELDS = (
+    "WORK RESULT",
+    "EVIDENCE RESULT",
+    "OVERALL RESULT",
+    "REMOTE_EVIDENCE",
+    "terminal_log",
+    "command_report",
+    "NEXT_CHAT_REPLY",
+)
+
+VALID_WORK = {"PASS", "FAIL", "PENDING", "HARD-FAIL"}
+VALID_EVIDENCE = {"PASS", "FAIL", "PARTIAL", "CHAT_ONLY", "NOT_REQUIRED"}
+VALID_REMOTE = {"PASS", "FAIL", "PARTIAL", "NOT_REQUIRED"}
+VALID_REPLY = {"p", "f", "paste-output", "continue", "stop"}
+
+BLOCK_RE = re.compile(r"(?ms)^={64}\nSUMMARY\n(?P<body>.*?)^={64}\s*$")
+RESULT_RE = re.compile(r"^### RESULT: (PASS|FAIL|PENDING|HARD-FAIL) ###$")
+
+def parse_final_summary(text: str) -> dict[str, str]:
+    matches = list(BLOCK_RE.finditer(text.rstrip()))
+    if len(matches) != 1:
+        raise ValueError("expected exactly one final SUMMARY block at end of text")
+    body = matches[0].group("body").strip().splitlines()
+    values: dict[str, str] = {}
+    for line in body:
+        if line.startswith("### RESULT:"):
+            if not RESULT_RE.match(line):
+                raise ValueError("invalid final result marker")
+            values["RESULT_MARKER"] = line.removeprefix("### RESULT: ").removesuffix(" ###")
+        elif "=" in line:
+            key, value = line.split("=", 1)
+            values[key.strip()] = value.strip()
+        elif ":" in line:
+            key, value = line.split(":", 1)
+            values[key.strip()] = value.strip()
+    missing = [field for field in SUMMARY_FIELDS if field not in values]
+    if missing:
+        raise ValueError(f"missing summary fields: {missing}")
+    if "RESULT_MARKER" not in values:
+        raise ValueError("missing final result marker")
+    return values
+
+def validate_final_summary(text: str) -> list[str]:
+    errors: list[str] = []
+    try:
+        values = parse_final_summary(text)
+    except ValueError as exc:
+        return [str(exc)]
+    work = values["WORK RESULT"]
+    evidence = values["EVIDENCE RESULT"]
+    overall = values["OVERALL RESULT"]
+    remote = values["REMOTE_EVIDENCE"]
+    reply = values["NEXT_CHAT_REPLY"]
+    marker = values["RESULT_MARKER"]
+    if work not in VALID_WORK:
+        errors.append("invalid WORK RESULT")
+    if evidence not in VALID_EVIDENCE:
+        errors.append("invalid EVIDENCE RESULT")
+    if overall not in VALID_WORK:
+        errors.append("invalid OVERALL RESULT")
+    if remote not in VALID_REMOTE:
+        errors.append("invalid REMOTE_EVIDENCE")
+    if reply not in VALID_REPLY:
+        errors.append("invalid NEXT_CHAT_REPLY")
+    if marker != overall:
+        errors.append("final result marker must match OVERALL RESULT")
+    if overall == "PASS" and work != "PASS":
+        errors.append("OVERALL RESULT: PASS requires WORK RESULT: PASS")
+    if overall == "PASS" and evidence not in {"PASS", "NOT_REQUIRED"}:
+        errors.append("OVERALL RESULT: PASS requires sufficient evidence")
+    if overall == "PASS" and remote not in {"PASS", "NOT_REQUIRED"}:
+        errors.append("OVERALL RESULT: PASS requires REMOTE_EVIDENCE: PASS or NOT_REQUIRED")
+    if remote != "PASS" and reply == "p":
+        errors.append("NEXT_CHAT_REPLY: p requires REMOTE_EVIDENCE: PASS")
+    final_start = text.rstrip().rfind("================================================================\nSUMMARY")
+    previous = text[:final_start]
+    if "### RESULT: FAIL ###" in previous and overall == "PASS":
+        errors.append("previous inner FAIL cannot be relabeled as OVERALL RESULT: PASS")
+    if "### RESULT: HARD-FAIL ###" in previous and overall == "PASS":
+        errors.append("previous inner HARD-FAIL cannot be relabeled as OVERALL RESULT: PASS")
+    return errors

agentic_project_kit/finalize_guard.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class FinalizeGuardStatus(StrEnum):
+    PASS_ALREADY_ON_MAIN = "PASS_ALREADY_ON_MAIN"
+    PASS_NOOP_BRANCH = "PASS_NOOP_BRANCH"
+    PASS_NEEDS_PR = "PASS_NEEDS_PR"
+    PASS_SUPERSEDED = "PASS_SUPERSEDED"
+    FAIL_CONFLICT_RELEVANT = "FAIL_CONFLICT_RELEVANT"
+    FAIL_NEEDS_HUMAN_REVIEW = "FAIL_NEEDS_HUMAN_REVIEW"
+
+
+@dataclass(frozen=True)
+class FinalizeGuardDecision:
+    status: FinalizeGuardStatus
+    result: str
+    message: str
+    needs_pr: bool = False
+    needs_human_review: bool = False
+
+
+def classify_finalize_guard_state(
+    *,
+    marker_requested: bool,
+    marker_on_main: bool,
+    local_branch_exists: bool,
+    remote_branch_exists: bool,
+    commits_ahead_of_main: int | None,
+    merge_conflict: bool | None,
+) -> FinalizeGuardDecision:
+    if not local_branch_exists and not remote_branch_exists:
+        return FinalizeGuardDecision(
+            status=FinalizeGuardStatus.PASS_NOOP_BRANCH,
+            result="PASS",
+            message="Finalization branch does not exist; no cleanup or PR action is needed.",
+        )
+
+    if commits_ahead_of_main is None:
+        return FinalizeGuardDecision(
+            status=FinalizeGuardStatus.FAIL_NEEDS_HUMAN_REVIEW,
+            result="FAIL",
+            message="Cannot classify branch without ahead/behind information.",
+            needs_human_review=True,
+        )
+
+    if commits_ahead_of_main == 0:
+        status = FinalizeGuardStatus.PASS_ALREADY_ON_MAIN if marker_requested and marker_on_main else FinalizeGuardStatus.PASS_NOOP_BRANCH
+        message = "Idempotent completion: requested finalization marker is already present on main." if status == FinalizeGuardStatus.PASS_ALREADY_ON_MAIN else "Idempotent completion: finalization branch has no commits ahead of main."
+        return FinalizeGuardDecision(status=status, result="PASS", message=message)
+
+    if merge_conflict is None:
+        return FinalizeGuardDecision(
+            status=FinalizeGuardStatus.FAIL_NEEDS_HUMAN_REVIEW,
+            result="FAIL",
+            message="Cannot classify relevant branch without merge conflict information.",
+            needs_human_review=True,
+        )
+
+    if not merge_conflict:
+        return FinalizeGuardDecision(
+            status=FinalizeGuardStatus.PASS_NEEDS_PR,
+            result="PASS",
+            message="Finalization branch has relevant commits and appears mergeable; continue normal PR path.",
+            needs_pr=True,
+        )
+
+    if marker_requested and marker_on_main:
+        return FinalizeGuardDecision(
+            status=FinalizeGuardStatus.PASS_SUPERSEDED,
+            result="PASS",
+            message="Finalization branch conflicts but requested marker is already represented on main.",
+        )
+
+    return FinalizeGuardDecision(
+        status=FinalizeGuardStatus.FAIL_CONFLICT_RELEVANT,
+        result="FAIL",
+        message="Finalization branch has commits ahead of main and conflicts; human review is required.",
+        needs_human_review=True,
+    )
+
+
+def render_finalize_guard_decision(decision: FinalizeGuardDecision) -> str:
+    return "\n".join((
+        f"STATUS: {decision.status.value}",
+        decision.message,
+        f"### RESULT: {decision.result} ###",
+    ))
+
+
+def _parse_bool(value: str) -> bool:
+    normalized = value.strip().lower()
+    if normalized in {"1", "true", "yes", "y"}:
+        return True
+    if normalized in {"0", "false", "no", "n"}:
+        return False
+    raise argparse.ArgumentTypeError(f"expected boolean value, got {value!r}")
+
+
+def _parse_optional_int(value: str) -> int | None:
+    normalized = value.strip().lower()
+    if normalized in {"none", "unknown", ""}:
+        return None
+    return int(value)
+
+
+def _parse_optional_bool(value: str) -> bool | None:
+    normalized = value.strip().lower()
+    if normalized in {"none", "unknown", ""}:
+        return None
+    return _parse_bool(value)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Classify finalize-guard state.")
+    parser.add_argument("--marker-requested", required=True, type=_parse_bool)
+    parser.add_argument("--marker-on-main", required=True, type=_parse_bool)
+    parser.add_argument("--local-branch-exists", required=True, type=_parse_bool)
+    parser.add_argument("--remote-branch-exists", required=True, type=_parse_bool)
+    parser.add_argument("--commits-ahead-of-main", required=True, type=_parse_optional_int)
+    parser.add_argument("--merge-conflict", required=True, type=_parse_optional_bool)
+    args = parser.parse_args(argv)
+    decision = classify_finalize_guard_state(
+        marker_requested=args.marker_requested,
+        marker_on_main=args.marker_on_main,
+        local_branch_exists=args.local_branch_exists,
+        remote_branch_exists=args.remote_branch_exists,
+        commits_ahead_of_main=args.commits_ahead_of_main,
+        merge_conflict=args.merge_conflict,
+    )
+    print(render_finalize_guard_decision(decision))
+    return 0 if decision.result == "PASS" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentic_project_kit/gatekeeper_core.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from agentic_project_kit.transfer_state import (
+    PRIMARY_BLOCKED,
+    PRIMARY_FAILED,
+    PRIMARY_READY,
+    PRIMARY_WAIT,
+    TransferStateSnapshot,
+)
+
+ACTION_DIAGNOSE = "diagnose"
+ACTION_REFRESH_RULES = "refresh_rules"
+ACTION_ACKNOWLEDGE_RULES = "acknowledge_rules"
+ACTION_INSPECT_TRANSFER = "inspect_transfer"
+ACTION_APPLY_TRANSFER = "apply_transfer"
+ACTION_CLOSEOUT_LAST_RUN = "closeout_last_run"
+ACTION_QUEUE_TRANSFER_ORDER = "queue_transfer_order"
+
+SAFE_READ_ONLY_ACTIONS = frozenset({ACTION_DIAGNOSE, ACTION_REFRESH_RULES})
+MUTATING_ACTIONS = frozenset(
+    {
+        ACTION_ACKNOWLEDGE_RULES,
+        ACTION_INSPECT_TRANSFER,
+        ACTION_APPLY_TRANSFER,
+        ACTION_CLOSEOUT_LAST_RUN,
+        ACTION_QUEUE_TRANSFER_ORDER,
+    }
+)
+
+
+@dataclass(frozen=True)
+class GatekeeperAction:
+    """Machine-readable action decision for a future GUI control."""
+
+    name: str
+    label: str
+    enabled: bool
+    category: str
+    required_capability: str | None = None
+    blocked_reason: str = ""
+    next_action: str = ""
+
+    def as_json_data(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "label": self.label,
+            "enabled": self.enabled,
+            "category": self.category,
+            "required_capability": self.required_capability,
+            "blocked_reason": self.blocked_reason,
+            "next_action": self.next_action,
+        }
+
+
+@dataclass(frozen=True)
+class GatekeeperActionContract:
+    """State/action contract consumed by CLI, tests, and later GUI code."""
+
+    schema_version: int
+    primary_state: str
+    next_action: str
+    reasons: tuple[str, ...]
+    actions: tuple[GatekeeperAction, ...]
+
+    def action(self, name: str) -> GatekeeperAction:
+        for candidate in self.actions:
+            if candidate.name == name:
+                return candidate
+        raise KeyError(name)
+
+    def as_json_data(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "primary_state": self.primary_state,
+            "next_action": self.next_action,
+            "reasons": list(self.reasons),
+            "actions": [action.as_json_data() for action in self.actions],
+        }
+
+
+def _blocked_reason(snapshot: TransferStateSnapshot, capability: str) -> str:
+    if snapshot.capabilities.get(capability, False):
+        return ""
+    if snapshot.reasons:
+        return ",".join(snapshot.reasons)
+    if capability == "rules_confirmed":
+        return "rules_not_confirmed"
+    if capability == "run_next_command":
+        return "transfer_not_ready"
+    if capability == "closeout_last_run":
+        return "closeout_not_ready"
+    return "capability_disabled"
+
+
+def _capability_action(
+    snapshot: TransferStateSnapshot,
+    *,
+    name: str,
+    label: str,
+    category: str,
+    capability: str,
+) -> GatekeeperAction:
+    enabled = snapshot.capabilities.get(capability, False)
+    return GatekeeperAction(
+        name=name,
+        label=label,
+        enabled=enabled,
+        category=category,
+        required_capability=capability,
+        blocked_reason=_blocked_reason(snapshot, capability),
+        next_action=snapshot.next_action,
+    )
+
+
+def _acknowledge_rules_action(snapshot: TransferStateSnapshot) -> GatekeeperAction:
+    rule_snapshot = snapshot.rule_snapshot
+    fail_closed = bool(rule_snapshot.get("fail_closed", False)) if isinstance(rule_snapshot, dict) else False
+    rules_confirmed = snapshot.capabilities.get("rules_confirmed", False)
+    enabled = not fail_closed and not rules_confirmed and snapshot.primary_state != PRIMARY_FAILED
+    if enabled:
+        blocked_reason = ""
+    elif fail_closed:
+        blocked_reason = "rule_snapshot_fail_closed"
+    elif rules_confirmed:
+        blocked_reason = "rules_already_confirmed"
+    else:
+        blocked_reason = _blocked_reason(snapshot, "rules_confirmed")
+    return GatekeeperAction(
+        name=ACTION_ACKNOWLEDGE_RULES,
+        label="Acknowledge current rule snapshot",
+        enabled=enabled,
+        category="mutating",
+        required_capability="rules_confirmed",
+        blocked_reason=blocked_reason,
+        next_action=snapshot.next_action,
+    )
+
+
+def _queue_transfer_order_action(snapshot: TransferStateSnapshot) -> GatekeeperAction:
+    pending_order = bool(snapshot.closeout.get("pending_transfer_order", False))
+    dirty = bool(snapshot.closeout.get("dirty_worktree", False))
+    rules_confirmed = snapshot.capabilities.get("rules_confirmed", False)
+    enabled = rules_confirmed and not dirty and not pending_order
+    if enabled:
+        blocked_reason = ""
+    elif dirty:
+        blocked_reason = "dirty_worktree"
+    elif pending_order:
+        blocked_reason = "pending_transfer_order_exists"
+    elif not rules_confirmed:
+        blocked_reason = _blocked_reason(snapshot, "rules_confirmed")
+    else:
+        blocked_reason = "queue_not_ready"
+    return GatekeeperAction(
+        name=ACTION_QUEUE_TRANSFER_ORDER,
+        label="Queue transfer order",
+        enabled=enabled,
+        category="mutating",
+        required_capability="rules_confirmed",
+        blocked_reason=blocked_reason,
+        next_action=snapshot.next_action,
+    )
+
+
+def derive_gatekeeper_action_contract(
+    snapshot: TransferStateSnapshot,
+) -> GatekeeperActionContract:
+    """Derive the deterministic B11 state/action contract from a transfer snapshot.
+
+    The contract is deliberately UI-free. A later GUI may render these actions as buttons,
+    but must not invent additional enable/disable rules outside this core contract.
+    """
+
+    actions = (
+        _capability_action(
+            snapshot,
+            name=ACTION_DIAGNOSE,
+            label="Diagnose state",
+            category="read_only",
+            capability="diagnose",
+        ),
+        _capability_action(
+            snapshot,
+            name=ACTION_REFRESH_RULES,
+            label="Refresh rule snapshot",
+            category="read_only",
+            capability="refresh_rules",
+        ),
+        _acknowledge_rules_action(snapshot),
+        _queue_transfer_order_action(snapshot),
+        _capability_action(
+            snapshot,
+            name=ACTION_INSPECT_TRANSFER,
+            label="Inspect transfer order",
+            category="mutating",
+            capability="run_next_command",
+        ),
+        _capability_action(
+            snapshot,
+            name=ACTION_APPLY_TRANSFER,
+            label="Apply inspected transfer order",
+            category="mutating",
+            capability="run_next_command",
+        ),
+        _capability_action(
+            snapshot,
+            name=ACTION_CLOSEOUT_LAST_RUN,
+            label="Close out last run",
+            category="mutating",
+            capability="closeout_last_run",
+        ),
+    )
+    return GatekeeperActionContract(
+        schema_version=1,
+        primary_state=snapshot.primary_state,
+        next_action=snapshot.next_action,
+        reasons=snapshot.reasons,
+        actions=actions,
+    )
+
+
+def derive_gatekeeper_action_contract_json_data(
+    snapshot: TransferStateSnapshot,
+) -> dict[str, Any]:
+    return derive_gatekeeper_action_contract(snapshot).as_json_data()
+
+
+def primary_state_is_supported(primary_state: str) -> bool:
+    return primary_state in {PRIMARY_READY, PRIMARY_WAIT, PRIMARY_BLOCKED, PRIMARY_FAILED}

agentic_project_kit/github.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+import shutil
+import subprocess
+
+
+def require_gh() -> None:
+    if shutil.which("gh") is None:
+        raise RuntimeError("GitHub CLI 'gh' not found. Install gh or run without GitHub creation.")
+
+
+def check_gh_auth() -> None:
+    require_gh()
+    result = subprocess.run(["gh", "auth", "status"], text=True, capture_output=True)
+    if result.returncode != 0:
+        raise RuntimeError("GitHub CLI is not authenticated. Run: gh auth login")
+
+
+def create_github_repo(project_dir: Path, owner: str | None, visibility: str, push: bool = True) -> None:
+    check_gh_auth()
+    repo_name = project_dir.name
+    repo = f"{owner}/{repo_name}" if owner else repo_name
+    cmd = ["gh", "repo", "create", repo, f"--{visibility}", "--source", str(project_dir), "--remote", "origin"]
+    if push:
+        cmd.append("--push")
+    subprocess.run(cmd, cwd=project_dir, check=True)

agentic_project_kit/governance.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from agentic_project_kit.action_specs import (
+    built_in_action_specs,
+    validate_current_handoff_action_surfaces,
+)
+from agentic_project_kit.handoff_state import load_handoff_state, validate_handoff_state
+from agentic_project_kit.work_orders import check_work_orders
+
+CONSTITUTION_FILES = (
+    ".agentic/project.yaml",
+    "sentinel.yaml",
+    "AGENTS.md",
+    "README.md",
+    "docs/STATUS.md",
+    "docs/handoff/CURRENT_HANDOFF.md",
+    "docs/architecture/ARCHITECTURE_CONTRACT.md",
+    "docs/DOCUMENTATION_COVERAGE.yaml",
+    "docs/workflow/HANDOFF_STATE.md",
+    "docs/workflow/WORK_ORDERS.md",
+    "docs/workflow/PARAMETERIZED_ACTIONS.md",
+)
+
+def governance_check() -> list[str]:
+    errors: list[str] = []
+    for file_name in CONSTITUTION_FILES:
+        if not Path(file_name).exists():
+            errors.append(f"missing constitution file: {file_name}")
+    try:
+        handoff_state = load_handoff_state()
+    except (FileNotFoundError, ValueError) as exc:
+        errors.append(str(exc))
+    else:
+        errors.extend(f"handoff: {error}" for error in validate_handoff_state(handoff_state))
+    errors.extend(f"work-order: {error}" for error in check_work_orders())
+    action_specs = built_in_action_specs()
+    required_actions = (
+        "pr-check-merge",
+        "release-verify",
+        "release-prepare",
+        "doi-record",
+        "finalize-release",
+    )
+    for required in required_actions:
+        if required not in action_specs:
+            errors.append(f"missing action spec: {required}")
+    errors.extend(
+        f"action-spec: {error}" for error in validate_current_handoff_action_surfaces(action_specs)
+    )
+    return errors
+
+def render_governance_check(errors: list[str]) -> str:
+    if not errors:
+        return "Governance check passed"
+    lines = ["Governance check failed"]
+    lines.extend(f"[FAIL] {error}" for error in errors)
+    return "\n".join(lines)