agentflow-proof 1.0.0__py3-none-any.whl

agentflow/versioning.py

@@ -0,0 +1,120 @@
+"""Schema-version parsing and compatibility checks."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import List, Optional
+
+from .contracts import POLICY_EXACT, POLICY_NONE, POLICY_SAME_MAJOR
+
+
+@dataclass(frozen=True)
+class SchemaVersion:
+    major: int
+    minor: int
+    patch: int
+
+
+# Strict dotted triple: no whitespace, signs, leading zeros, or pre-release
+# suffixes (int() would silently accept " 3"; "01" would alias "1").
+_SCHEMA_VERSION_RE = re.compile(r"(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)")
+
+
+def parse_schema_version(value: str) -> SchemaVersion:
+    match = _SCHEMA_VERSION_RE.fullmatch(value)
+    if match is None:
+        raise ValueError("schema_version must be MAJOR.MINOR.PATCH")
+    return SchemaVersion(*(int(part) for part in match.groups()))
+
+
+def is_schema_version_compatible(actual: str, supported: str) -> bool:
+    try:
+        actual_version = parse_schema_version(actual)
+        supported_version = parse_schema_version(supported)
+    except ValueError:
+        return False
+    return (
+        actual_version.major == supported_version.major
+        and actual_version.minor <= supported_version.minor
+    )
+
+
+def validate_schema_version(
+    actual: object, supported: str, artifact: str, policy: Optional[str] = None
+) -> List[str]:
+    if policy is None:
+        from .contracts import (
+            ARTIFACT_COMPATIBILITY_POLICIES,
+            DEFAULT_COMPATIBILITY_POLICY,
+        )
+
+        policy = ARTIFACT_COMPATIBILITY_POLICIES.get(
+            artifact, DEFAULT_COMPATIBILITY_POLICY
+        )
+    return validate_schema_version_policy(actual, supported, artifact, policy)
+
+
+def validate_schema_version_policy(
+    actual: object, supported: str, artifact: str, policy: str
+) -> List[str]:
+    if policy == POLICY_NONE:
+        return []
+    if policy not in {POLICY_EXACT, POLICY_SAME_MAJOR}:
+        raise ValueError(f"unknown schema compatibility policy: {policy}")
+    if not isinstance(actual, str):
+        return [f"{artifact} schema_version must be MAJOR.MINOR.PATCH"]
+    try:
+        parse_schema_version(actual)
+    except ValueError:
+        return [f"{artifact} schema_version must be MAJOR.MINOR.PATCH"]
+    try:
+        parse_schema_version(supported)
+    except ValueError as exc:
+        # A malformed *supported* version is a broken constant (developer
+        # error), not bad user data; never blame the artifact for it.
+        raise ValueError(
+            f"invalid supported schema_version for {artifact}: {supported!r}"
+        ) from exc
+    compatible = (
+        actual == supported
+        if policy == POLICY_EXACT
+        else is_schema_version_compatible(actual, supported)
+    )
+    if not compatible:
+        return [
+            f"{artifact} schema_version {actual} is incompatible with supported {supported}"
+        ]
+    return []
+
+
+def validate_historical_proof_schema_version(
+    actual: object, supported: str
+) -> List[str]:
+    """Validate the bounded verify-proof historical promise."""
+    if isinstance(actual, str):
+        try:
+            actual_version = parse_schema_version(actual)
+        except ValueError:
+            return ["proof-pack schema_version must be MAJOR.MINOR.PATCH"]
+        else:
+            # supported comes from a constant; a parse failure there is a
+            # developer error and must not be blamed on the proof.
+            supported_version = parse_schema_version(supported)
+            if (
+                supported_version.major == 1
+                and actual_version.major == 0
+                and (actual_version.minor, actual_version.patch) >= (4, 0)
+            ):
+                return []
+            if (actual_version.major, actual_version.minor) > (
+                supported_version.major,
+                supported_version.minor,
+            ):
+                return [
+                    f"proof-pack schema_version {actual} is a newer schema than "
+                    f"supported {supported}; upgrade Agentflow"
+                ]
+    return validate_schema_version_policy(
+        actual, supported, "proof-pack", POLICY_SAME_MAJOR
+    )

agentflow/viewer.py

@@ -0,0 +1,391 @@
+"""Static HTML proof viewer (#18).
+
+Renders a self-contained, dependency-free report from ``.agent/proof-pack.json``
+and related ledgers. The report is a review aid only; ``verify-proof`` remains
+the authoritative check. The renderer emits no ``<script>`` tags and no
+external references, and every interpolated value is HTML-escaped.
+"""
+
+from __future__ import annotations
+
+import html
+import os
+from pathlib import Path
+from urllib.parse import urlsplit
+from typing import Any, Dict, List, Optional
+
+from .artifacts import read_jsonl, try_read_json
+from .contracts import EXECUTION_ARTIFACT_PATHS
+from .execution import read_step_state
+
+
+def _try_read_jsonl(path: Path, warnings: List[str]) -> List[Dict[str, Any]]:
+    try:
+        return read_jsonl(path)
+    except (OSError, ValueError):
+        warnings.append(f"{path.name} ledger unreadable; section omitted")
+        return []
+
+
+def _try_read_json(path: Path) -> tuple[Optional[Dict[str, Any]], Optional[str]]:
+    try:
+        return try_read_json(path)
+    except OSError as exc:
+        return None, str(exc)
+
+
+def _receipt_href(root: Path, output_dir: Path, relative_path: Any) -> Optional[str]:
+    if not isinstance(relative_path, str) or not relative_path:
+        return None
+    root = root.resolve()
+    target = (root / relative_path).resolve()
+    if not target.is_relative_to(root):
+        return None
+    if not target.exists():
+        return None
+    href = os.path.relpath(target, output_dir.resolve()).replace(os.sep, "/")
+    if urlsplit(href).scheme:
+        return None
+    return href
+
+
+def _list(value: Any) -> List[Any]:
+    return value if isinstance(value, list) else []
+
+
+def _steps(plan: Dict[str, Any]) -> List[Dict[str, Any]]:
+    return [step for step in _list(plan.get("steps")) if isinstance(step, dict)]
+
+
+def collect_view_model(root: Path, proof_path: Path, output_path: Path) -> Dict[str, Any]:
+    """Read proof + ledgers into a render model. Only the proof is required."""
+    if not proof_path.exists():
+        raise ValueError(
+            f"proof metadata missing: {proof_path}; run `agentflow build-proof` first"
+        )
+    proof, proof_error = _try_read_json(proof_path)
+    if proof is None:
+        raise ValueError(f"proof metadata unreadable: {proof_error}; run `agentflow build-proof`")
+
+    warnings: List[str] = []
+    plan: Optional[Dict[str, Any]] = None
+    plan_path = root / ".agent/plan.lock.json"
+    if plan_path.exists():
+        plan, plan_error = _try_read_json(plan_path)
+        if plan is None:
+            warnings.append(f"plan.lock.json unreadable: {plan_error}")
+
+    output_dir = output_path.parent
+    command_rows = _try_read_jsonl(root / EXECUTION_ARTIFACT_PATHS["command-receipts"], warnings)
+    command_receipts = []
+    for receipt in command_rows:
+        if not isinstance(receipt, dict):
+            continue
+        enriched = dict(receipt)
+        enriched["stdout_href"] = _receipt_href(root, output_dir, receipt.get("stdout_path"))
+        enriched["stderr_href"] = _receipt_href(root, output_dir, receipt.get("stderr_path"))
+        command_receipts.append(enriched)
+    file_receipts = [
+        receipt
+        for receipt in _try_read_jsonl(root / EXECUTION_ARTIFACT_PATHS["file-receipts"], warnings)
+        if isinstance(receipt, dict)
+    ]
+
+    step_state: Optional[Dict[str, Any]] = None
+    if (root / EXECUTION_ARTIFACT_PATHS["execution-contract"]).exists():
+        try:
+            step_state = read_step_state(root)
+        except (OSError, ValueError):
+            warnings.append("step-runs.jsonl ledger unreadable; step status omitted")
+
+    drift: Optional[Dict[str, Any]] = None
+    drift_path = root / ".agent/drift-report.json"
+    if drift_path.exists():
+        drift, drift_error = _try_read_json(drift_path)
+        if drift is None:
+            warnings.append(f"drift-report.json unreadable: {drift_error}")
+
+    return {
+        "proof": proof,
+        "plan": plan,
+        "command_receipts": command_receipts,
+        "file_receipts": file_receipts,
+        "step_state": step_state,
+        "drift": drift,
+        "warnings": warnings,
+    }
+
+
+class _Raw(str):
+    """Cell content that is already safe HTML (built by this module only)."""
+
+
+def _esc(value: Any) -> str:
+    return html.escape(str(value), quote=True)
+
+
+def _cell(value: Any) -> str:
+    return value if isinstance(value, _Raw) else _esc(value)
+
+
+def _table(headers: List[str], rows: List[List[Any]], row_classes: Optional[List[str]] = None) -> str:
+    head = "".join(f"<th>{_esc(header)}</th>" for header in headers)
+    body_rows = []
+    for index, row in enumerate(rows):
+        cells = "".join(f"<td>{_cell(value)}</td>" for value in row)
+        cls = row_classes[index] if row_classes else ""
+        attr = f' class="{_esc(cls)}"' if cls else ""
+        body_rows.append(f"<tr{attr}>{cells}</tr>")
+    return f"<table><thead><tr>{head}</tr></thead><tbody>{''.join(body_rows)}</tbody></table>"
+
+
+def _items(values: List[Any], empty: str) -> str:
+    if not values:
+        return f"<p>{_esc(empty)}</p>"
+    entries = "".join(f"<li>{_cell(value)}</li>" for value in values)
+    return f"<ul>{entries}</ul>"
+
+
+def _section(title: str, body: str) -> str:
+    return f"<section><h2>{_esc(title)}</h2>{body}</section>"
+
+
+_STATUS_CLASSES = {"passed": "status-passed", "warning": "status-warning", "failed": "status-failed"}
+
+_STYLE = """
+body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+       margin: 2rem auto; max-width: 60rem; padding: 0 1rem; color: #1a1a1a; }
+h1 { border-bottom: 2px solid #ccc; padding-bottom: .3rem; }
+.banner { background: #fff8e1; border: 1px solid #e0c341; border-radius: 4px; padding: .6rem .8rem; }
+table { border-collapse: collapse; width: 100%; margin: .5rem 0 1rem; font-size: .9rem; }
+th, td { border: 1px solid #ccc; padding: .3rem .5rem; text-align: left; vertical-align: top; }
+th { background: #f2f2f2; }
+code, .hash { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .85em;
+              word-break: break-all; }
+.status-passed { background: #eaf7ea; }
+.status-warning { background: #fff8e1; }
+.status-failed { background: #fdecea; }
+section { margin-bottom: 1.2rem; }
+"""
+
+
+def _step_status_body(plan: Optional[Dict[str, Any]], step_state: Optional[Dict[str, Any]]) -> str:
+    if not plan:
+        return "<p>Plan not recorded.</p>"
+    steps = _steps(plan)
+    if not steps:
+        return "<p>No plan steps recorded.</p>"
+    states = step_state.get("steps", {}) if step_state else {}
+    attempts = step_state.get("attempts", {}) if step_state else {}
+    rows: List[List[Any]] = []
+    for step in steps:
+        step_id = step.get("id", "unknown")
+        if step_state is None:
+            status = "execution ledger not recorded"
+            attempt_count: Any = ""
+        else:
+            status = "completed" if states.get(step_id, {}).get("completed") else "not completed"
+            attempt_count = sum(
+                1 for attempt in attempts.values() if attempt.get("step_id") == step_id
+            )
+        rows.append([step_id, step.get("action", ""), status, attempt_count])
+    return _table(["Step", "Action", "Status", "Attempts"], rows)
+
+
+def _output_link(receipt: Dict[str, Any], stream: str) -> Any:
+    href = receipt.get(f"{stream}_href")
+    if href:
+        return _Raw(f'<a href="{_esc(href)}">{_esc(stream)}</a>')
+    path = receipt.get(f"{stream}_path")
+    return path or ""
+
+
+def _command_receipts_body(receipts: List[Dict[str, Any]]) -> str:
+    if not receipts:
+        return "<p>No command receipts recorded.</p>"
+    rows: List[List[Any]] = []
+    for receipt in receipts:
+        command = receipt.get("command")
+        rendered = " ".join(str(part) for part in command) if isinstance(command, list) else str(command or "")
+        risk_value = receipt.get("risk")
+        risk = risk_value if isinstance(risk_value, dict) else {}
+        outputs = [_output_link(receipt, stream) for stream in ("stdout", "stderr")]
+        links = _Raw(" ".join(_cell(value) for value in outputs if value != ""))
+        rows.append(
+            [
+                receipt.get("id", ""),
+                receipt.get("step_id", ""),
+                receipt.get("provenance", ""),
+                receipt.get("decision", ""),
+                "" if receipt.get("exit_code") is None else receipt.get("exit_code"),
+                risk.get("level", ""),
+                _Raw(f"<code>{_esc(rendered)}</code>"),
+                links,
+            ]
+        )
+    return _table(
+        ["Id", "Step", "Provenance", "Decision", "Exit", "Risk", "Command", "Output"], rows
+    )
+
+
+def _file_receipts_body(receipts: List[Dict[str, Any]]) -> str:
+    if not receipts:
+        return "<p>No file receipts recorded.</p>"
+    rows = [
+        [receipt.get("id", ""), receipt.get("step_id", ""), receipt.get("path", ""), receipt.get("change_kind", "")]
+        for receipt in receipts
+    ]
+    return _table(["Id", "Step", "Path", "Change"], rows)
+
+
+def _drift_body(drift: Optional[Dict[str, Any]]) -> str:
+    if drift is None:
+        return "<p>Drift report not recorded.</p>"
+    parts = [f"<p>Status: <strong>{_esc(drift.get('status', 'missing'))}</strong></p>"]
+    notes = [note for note in _list(drift.get("notes"))]
+    if notes:
+        parts.append(_items(notes, ""))
+    unmapped = [
+        entry.get("path", "")
+        for entry in _list(drift.get("unmapped_hunks"))
+        if isinstance(entry, dict)
+    ]
+    if unmapped:
+        parts.append("<p>Unmapped hunks:</p>")
+        parts.append(_items(unmapped, ""))
+    return "".join(parts)
+
+
+def _checks_body(proof: Dict[str, Any]) -> str:
+    checks = [check for check in _list(proof.get("checks")) if isinstance(check, dict)]
+    if not checks:
+        return "<p>No checks recorded.</p>"
+    rows: List[List[Any]] = []
+    classes: List[str] = []
+    for check in checks:
+        status = str(check.get("status", ""))
+        message = check.get("message", "")
+        if not message and "count" in check:
+            message = f"count: {check.get('count')}"
+        rows.append([check.get("id", "unknown"), status, message])
+        classes.append(_STATUS_CLASSES.get(status, ""))
+    return _table(["Check", "Status", "Detail"], rows, classes)
+
+
+def _residual_warnings_body(proof: Dict[str, Any], collect_warnings: List[str]) -> str:
+    warnings = [
+        f"{check.get('id', 'unknown')}: {check.get('message', check.get('count', ''))}"
+        for check in _list(proof.get("checks"))
+        if isinstance(check, dict) and check.get("status") == "warning"
+    ]
+    warnings.extend(collect_warnings)
+    return _items(warnings, "No residual warnings.")
+
+
+def _finding_location(value: Any) -> str:
+    if not isinstance(value, dict):
+        return ""
+    path = value.get("path")
+    if not isinstance(path, str):
+        return ""
+    line = value.get("line")
+    line_end = value.get("line_end")
+    if not isinstance(line, int):
+        return path
+    suffix = f":{line}"
+    if isinstance(line_end, int) and line_end != line:
+        suffix += f"-{line_end}"
+    return path + suffix
+
+
+def _review_findings_body(proof: Dict[str, Any]) -> str:
+    review = proof.get("review") if isinstance(proof.get("review"), dict) else {}
+    runs = [run for run in _list(review.get("review_runs")) if isinstance(run, dict)]
+    if not runs:
+        return "<p>No review runs recorded.</p>"
+    rows: List[List[Any]] = []
+    for run in runs:
+        findings = run.get("findings") if isinstance(run.get("findings"), dict) else {}
+        index = [row for row in _list(findings.get("index")) if isinstance(row, dict)]
+        if not index:
+            rows.append([
+                run.get("review_run_id", ""),
+                "",
+                "",
+                "",
+                "",
+                "",
+                "",
+                "yes" if run.get("amendment_ready") is True else "no",
+            ])
+            continue
+        for finding in index:
+            rows.append([
+                run.get("review_run_id", ""),
+                finding.get("finding_id", ""),
+                finding.get("status", ""),
+                finding.get("owning_step", ""),
+                finding.get("claim", ""),
+                _finding_location(finding.get("location")),
+                finding.get("suggested_fix", ""),
+                "yes" if run.get("amendment_ready") is True else "no",
+            ])
+    return _table(
+        ["Review", "Finding", "Status", "Owner", "Claim", "Location", "Suggested fix", "Amendment ready"],
+        rows,
+    )
+
+
+def _hashes_body(proof: Dict[str, Any]) -> str:
+    rows = [
+        [item.get("path", ""), _Raw(f'<span class="hash">{_esc(item.get("sha256", ""))}</span>')]
+        for item in _list(proof.get("files"))
+        if isinstance(item, dict)
+    ]
+    table = _table(["Path", "SHA-256"], rows) if rows else "<p>No file hashes recorded.</p>"
+    core = proof.get("core_sha256", "")
+    return table + f'<p>Core checksum: <span class="hash">{_esc(core)}</span></p>'
+
+
+def render_html(model: Dict[str, Any]) -> str:
+    proof: Dict[str, Any] = model.get("proof") or {}
+    plan: Optional[Dict[str, Any]] = model.get("plan")
+    meta = proof.get("meta", {}) if isinstance(proof.get("meta"), dict) else {}
+
+    objective = (plan or {}).get("objective") or (
+        "Plan not recorded." if plan is None else "No objective recorded."
+    )
+    gates: List[Any] = list(_list((plan or {}).get("validation_gates")))
+    for step in _steps(plan or {}):
+        gates.extend(_list(step.get("validation")))
+
+    sections = [
+        _section("Objective", f"<p>{_esc(objective)}</p>"),
+        _section("Scope", _items(_list((plan or {}).get("scope")), "No scope recorded.")),
+        _section("Step Status", _step_status_body(plan, model.get("step_state"))),
+        _section("Validation Gates", _items(gates, "No validation gates recorded.")),
+        _section("Command Receipts", _command_receipts_body(model.get("command_receipts", []))),
+        _section("File Receipts", _file_receipts_body(model.get("file_receipts", []))),
+        _section("Drift Audit", _drift_body(model.get("drift"))),
+        _section("Checks", _checks_body(proof)),
+        _section("Residual Warnings", _residual_warnings_body(proof, model.get("warnings", []))),
+        _section("Review Findings", _review_findings_body(proof)),
+        _section("Proof Hashes", _hashes_body(proof)),
+    ]
+    meta_line = (
+        f"Generated {_esc(meta.get('created_at', 'unknown'))} by Agentflow "
+        f"{_esc(meta.get('tool_version', 'unknown'))} "
+        f"(proof schema {_esc(proof.get('schema_version', 'unknown'))})"
+    )
+    return (
+        "<!doctype html>\n"
+        '<html lang="en"><head><meta charset="utf-8">'
+        "<title>Agentflow Proof Report</title>"
+        f"<style>{_STYLE}</style></head><body>"
+        "<h1>Agentflow Proof Report</h1>"
+        '<p class="banner">Review aid. <code>agentflow verify-proof</code> is the '
+        "authoritative check.</p>"
+        f"<p>{meta_line}</p>"
+        f"{''.join(sections)}"
+        "</body></html>\n"
+    )

agentflow/workflow_contract.py

@@ -0,0 +1,164 @@
+"""Workflow contract artifact validation and summaries."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List
+
+from .artifacts import read_json, write_json
+from .contracts import (
+    HUNK_ATTRIBUTION_POLICIES,
+    WORKFLOW_CONTRACT_SCHEMA_VERSION,
+    WORKFLOW_REVIEW_DEPTHS,
+)
+from .versioning import validate_schema_version
+
+
+WORKFLOW_CONTRACT_PATH = ".agent/workflow.contract.json"
+
+TOP_LEVEL_FIELDS = {
+    "schema_version",
+    "workflow_pack",
+    "workflow_profile",
+    "selected_by",
+    "selection_reason",
+    "required_capabilities",
+    "review_depth",
+    "validation_policy",
+    "proof_policy",
+}
+REQUIRED_FIELDS = {
+    "schema_version": str,
+    "workflow_pack": str,
+    "workflow_profile": str,
+    "selected_by": str,
+    "selection_reason": str,
+    "required_capabilities": list,
+    "review_depth": str,
+    "validation_policy": dict,
+    "proof_policy": dict,
+}
+CAPABILITY_FIELDS = {"id", "required"}
+VALIDATION_POLICY_FIELDS = {"required_gates"}
+PROOF_POLICY_FIELDS = {"hunk_attribution", "require_review_run"}
+
+
+def _non_empty_string(value: Any) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def _non_empty_string_list(value: Any) -> bool:
+    return isinstance(value, list) and all(_non_empty_string(item) for item in value)
+
+
+def validate_workflow_contract(contract: Dict[str, Any]) -> List[str]:
+    errors: List[str] = []
+    if not isinstance(contract, dict):
+        return ["workflow contract must be a JSON object"]
+
+    for field in sorted(set(contract) - TOP_LEVEL_FIELDS):
+        errors.append(f"unknown workflow contract field: {field}")
+
+    for field, expected_type in REQUIRED_FIELDS.items():
+        if field not in contract:
+            errors.append(f"missing required workflow contract field: {field}")
+            continue
+        if not isinstance(contract[field], expected_type):
+            errors.append(f"{field} must be {expected_type.__name__}")
+
+    if errors:
+        return errors
+
+    errors.extend(
+        validate_schema_version(
+            contract["schema_version"],
+            WORKFLOW_CONTRACT_SCHEMA_VERSION,
+            "workflow-contract",
+        )
+    )
+
+    for field in ("workflow_pack", "workflow_profile", "selected_by", "selection_reason"):
+        if not _non_empty_string(contract[field]):
+            errors.append(f"{field} must be a non-empty string")
+
+    for index, capability in enumerate(contract["required_capabilities"], start=1):
+        prefix = f"required_capabilities[{index}]"
+        if not isinstance(capability, dict):
+            errors.append(f"{prefix} must be an object")
+            continue
+        for field in sorted(set(capability) - CAPABILITY_FIELDS):
+            errors.append(f"{prefix} unknown field: {field}")
+        if not _non_empty_string(capability.get("id")):
+            errors.append(f"{prefix}.id must be a non-empty string")
+        if not isinstance(capability.get("required"), bool):
+            errors.append(f"{prefix}.required must be boolean")
+
+    review_depth = contract["review_depth"]
+    if review_depth not in WORKFLOW_REVIEW_DEPTHS:
+        errors.append(
+            "review_depth must be one of: " + ", ".join(WORKFLOW_REVIEW_DEPTHS)
+        )
+
+    validation_policy = contract["validation_policy"]
+    for field in sorted(set(validation_policy) - VALIDATION_POLICY_FIELDS):
+        errors.append(f"validation_policy unknown field: {field}")
+    required_gates = validation_policy.get("required_gates")
+    if not _non_empty_string_list(required_gates):
+        errors.append("validation_policy.required_gates must contain non-empty strings")
+
+    proof_policy = contract["proof_policy"]
+    for field in sorted(set(proof_policy) - PROOF_POLICY_FIELDS):
+        errors.append(f"proof_policy unknown field: {field}")
+    hunk_attribution = proof_policy.get("hunk_attribution")
+    if hunk_attribution not in HUNK_ATTRIBUTION_POLICIES:
+        errors.append(
+            "proof_policy.hunk_attribution must be one of: "
+            + ", ".join(HUNK_ATTRIBUTION_POLICIES)
+        )
+    if not isinstance(proof_policy.get("require_review_run"), bool):
+        errors.append("proof_policy.require_review_run must be boolean")
+
+    return errors
+
+
+def read_workflow_contract(root: Path) -> Dict[str, Any]:
+    return read_json(root / WORKFLOW_CONTRACT_PATH)
+
+
+def write_workflow_contract(root: Path, contract: Dict[str, Any]) -> Path:
+    errors = validate_workflow_contract(contract)
+    if errors:
+        raise ValueError("; ".join(errors))
+    path = root / WORKFLOW_CONTRACT_PATH
+    write_json(path, contract)
+    return path
+
+
+def workflow_contract_summary(contract: Dict[str, Any]) -> Dict[str, Any]:
+    required_capabilities = [
+        item["id"]
+        for item in contract.get("required_capabilities", [])
+        if isinstance(item, dict)
+        and item.get("required") is True
+        and isinstance(item.get("id"), str)
+    ]
+    validation_policy = contract.get("validation_policy", {})
+    proof_policy = contract.get("proof_policy", {})
+    return {
+        "workflow_pack": contract.get("workflow_pack"),
+        "workflow_profile": contract.get("workflow_profile"),
+        "selected_by": contract.get("selected_by"),
+        "review_depth": contract.get("review_depth"),
+        "required_capabilities": required_capabilities,
+        "required_gates": list(validation_policy.get("required_gates", []))
+        if isinstance(validation_policy, dict)
+        else [],
+        "proof_policy": {
+            "hunk_attribution": proof_policy.get("hunk_attribution")
+            if isinstance(proof_policy, dict)
+            else None,
+            "require_review_run": proof_policy.get("require_review_run")
+            if isinstance(proof_policy, dict)
+            else None,
+        },
+    }