agentmandate 0.2.0__tar.gz → 0.3.0__tar.gz

{agentmandate-0.2.0 → agentmandate-0.3.0}/CHANGELOG.md

@@ -6,6 +6,48 @@ All notable changes to this project are documented here. The format follows
 
 ## Unreleased
 
+## 0.3.0 - 2026-07-28
+
+### Added
+
+- `mandate obligations` derives reviewable test obligations from the authority
+  a manifest actually makes reachable: irreversible effects, approval gates,
+  service-account principals, and value-bearing calls. A tool nobody can reach
+  produces no obligation, because listing it would pad a review with work that
+  protects nothing.
+- `--reviewed` accepts an obligations file whose decisions have been mapped by
+  a human, and `--suite` renders those into an `agentverity.decision-suite/v1`
+  skeleton that AgentVerity loads directly.
+- `docs/test-obligations.md` walks the whole path, including what deliberately
+  does not cross it.
+
+- `README` and `DESIGN` name Policy in Amazon Bedrock AgentCore alongside the
+  other enforcement tools, and say precisely where it stops: the engine
+  evaluates all applicable Cedar policies for one invocation, while its
+  documented analysis is policy-level. Neither models a sequence of permitted
+  calls or a release-to-release comparison of reachable authority.
+
+### Fixed
+
+- `--reviewed` reconciles against the live manifest by stable identifier
+  instead of replacing it. A stale or unrelated review previously generated a
+  suite for authority the agent no longer had, which is the drift this package
+  exists to catch.
+- A generated suite carries probes the reviewer wrote. It previously shipped
+  `REVIEW:` placeholder inputs that AgentVerity accepted and ran, producing
+  numbers about nothing. An obligation now needs both a decision and at least
+  one probe before it counts as reviewed.
+- A malformed reviewed file produces a usage error rather than a traceback.
+
+### Notes
+
+- Decisions are never invented. An effect class such as `irreversible on case`
+  is an authority fact; a decision such as `refund_approved` is an application
+  label somebody chose. No parsing turns one into the other, so the command
+  exits non-zero until every row carries a reviewed decision.
+- Compound breaches do not cross the bridge. A cumulative-value path is a
+  multi-call sequence, which is scenario testing rather than decision coverage.
+
 ## 0.2.0 - 2026-07-28
 
 ### Added

{agentmandate-0.2.0 → agentmandate-0.3.0}/DESIGN.md

@@ -110,13 +110,31 @@ usage error.
 
 ## Deliberate overlap
 
-`lint` covers ground that AgentWard, AgentShield, and AgentGuard already cover.
+`lint` covers ground that AgentWard, AgentShield, AgentGuard, and Policy in
+Amazon Bedrock AgentCore already cover.
 That is on purpose. A tool that reported only compound findings would need one
 of those running alongside it to be usable at all, and the first thing anyone
 does with a new analysis tool is run it on its own.
 
 The overlap is the floor. The contribution is `reach` and the diff built on it.
 
+Policy in AgentCore is worth naming precisely, because it is the strongest
+reason an AWS team would ask why this exists. It evaluates all applicable
+Cedar policies for every gateway tool invocation with default-deny and
+forbid-wins semantics. Its documented automated analysis flags policy-level
+problems such as policies that always allow or always deny. That is real
+analysis, but it does not model a sequence of individually permitted calls.
+
+Cedar has no notion of a call sequence. "May this principal invoke
+`issue_refund` now" is a different question from "do four individually
+permitted calls compose into a 1,000 GBP breach", and no per-decision engine
+answers the second by construction. Neither does any of them answer whether a
+release widened reachable authority, because that needs two manifests and a
+reachability computation over both.
+
+So the split is enforcement against offline analysis, and per-decision against
+compound. Running both is the intended shape.
+
 ## What was left out, and why
 
 **Data-flow reachability.** Finding that a read tool feeds an exfiltration path

{agentmandate-0.2.0 → agentmandate-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentmandate
-Version: 0.2.0
+Version: 0.3.0
 Summary: Compound-path and cross-release analysis of what an AI agent is permitted to do
 Project-URL: Homepage, https://github.com/mrwersa/agentmandate
 Project-URL: Repository, https://github.com/mrwersa/agentmandate
@@ -64,6 +64,8 @@ cannot:
   authority, not configuration text.
 - **Does runtime evidence match the declaration?** `mandate verify` fails
   closed when a required control field is absent.
+- **What must the tests exercise?** `mandate obligations` turns reachable
+  authority into reviewable test obligations.
 
 Alpha. Apache-2.0.
 
@@ -200,6 +202,7 @@ A ceiling is the maximum **cumulative** value one tool may spend against one bin
 | `mandate reach` | Bounded search for a legal call sequence that breaches a limit, reported as a counterexample |
 | `mandate diff` | Effective-authority comparison of two manifests, including limits, preconditions, approvals, effects, and scope minting. `--record` emits a change record |
 | `mandate verify` | Replays recorded tool calls against the manifest and fails closed when evidence required by a declared control is missing |
+| `mandate obligations` | Derives reviewable test obligations from reachable authority, and renders reviewed ones as an [AgentVerity](https://github.com/mrwersa/agentverity) decision suite |
 
 Every analysis command takes `--json` and exits non-zero on a finding, so they drop into CI unchanged. `scan` writes a manifest to standard output and is a one-off, not a gate.
 
@@ -228,9 +231,25 @@ does not pass as an empty value.
 
 This is analysis, not enforcement. It runs in CI against a manifest, it does not sit in the request path.
 
-[AgentWard](https://github.com/agentward-ai/agentward) is a runtime proxy that enforces policy on each call and can diff two policy files. [AgentShield](https://github.com/affaan-m/agentshield) scans agent configuration and MCP servers, with a drift gate over scan findings. [AgentGuard](https://github.com/WhitzardAgent/AgentGuard) implements attribute-based access control for tool calls. [OPA](https://www.openpolicyagent.org/docs) and [Cedar](https://docs.cedarpolicy.com/) decide one authorisation at a time.
+| Tool | What it does | Relationship |
+|---|---|---|
+| [Policy in Amazon Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy.html) | Evaluates all applicable Cedar policies for each gateway tool invocation, with default-deny, forbid-wins, and analysis that flags always-allow and always-deny policies | Enforces each invocation. Its documented analysis is policy-level, not a model of a sequence of permitted calls |
+| [AgentWard](https://github.com/agentward-ai/agentward) | Runtime proxy enforcing policy per call, diffs two policy files | Enforces. Diffs declared text rather than reachable authority |
+| [AgentShield](https://github.com/affaan-m/agentshield) | Scans agent configuration and MCP servers, drift gate over findings | Scans. Drift is over finding counts, not permission direction |
+| [AgentGuard](https://github.com/WhitzardAgent/AgentGuard) | Attribute-based access control for tool calls | Enforces |
+| [OPA](https://www.openpolicyagent.org/docs), [Cedar](https://docs.cedarpolicy.com/) | Decide one authorisation at a time | Enforces |
 
-Use those to enforce. AgentMandate complements them by analysing compound sequences and comparing *effective* authority across releases. The closest prior art in a neighbouring domain is [IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-concepts.html), which derives reachable access from policy by automated reasoning rather than waiting for a log event. This is that idea pointed at agent tool graphs.
+Use those to enforce. AgentMandate is the offline half: it analyses sequences of individually permitted calls and compares *effective* authority across releases.
+
+**If you already run AgentCore Policy**, the gap is specific. The policy engine
+answers "may this principal invoke this tool now" by evaluating all applicable
+policies, and its documented analysis catches policy-level problems such as an
+unconditional allow. It does not model whether four separately permitted calls
+compose into a 1,000 GBP breach or whether a release widened what the agent can
+reach. AgentMandate is vendor-neutral and runs in CI before deployment, so it
+complements the gateway rather than duplicating it.
+
+The closest prior art in a neighbouring domain is [IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-concepts.html), which derives reachable access from policy by automated reasoning rather than waiting for a log event. This is that idea pointed at agent tool graphs.
 
 The `lint` command deliberately overlaps the scanners above. A tool that reported only compound findings would need one of them running alongside it to be usable at all.
 
@@ -267,7 +286,7 @@ ruff check .
 
 ## Status
 
-Alpha, version 0.2.0. The authority model is the part most likely to change,
+Alpha, version 0.3.0. The authority model is the part most likely to change,
 because it has not yet been pointed at enough real tool graphs to know where it
 is too coarse. Issues describing a graph it models badly are the most useful
 thing you can file.

{agentmandate-0.2.0 → agentmandate-0.3.0}/README.md

@@ -30,6 +30,8 @@ cannot:
   authority, not configuration text.
 - **Does runtime evidence match the declaration?** `mandate verify` fails
   closed when a required control field is absent.
+- **What must the tests exercise?** `mandate obligations` turns reachable
+  authority into reviewable test obligations.
 
 Alpha. Apache-2.0.
 
@@ -166,6 +168,7 @@ A ceiling is the maximum **cumulative** value one tool may spend against one bin
 | `mandate reach` | Bounded search for a legal call sequence that breaches a limit, reported as a counterexample |
 | `mandate diff` | Effective-authority comparison of two manifests, including limits, preconditions, approvals, effects, and scope minting. `--record` emits a change record |
 | `mandate verify` | Replays recorded tool calls against the manifest and fails closed when evidence required by a declared control is missing |
+| `mandate obligations` | Derives reviewable test obligations from reachable authority, and renders reviewed ones as an [AgentVerity](https://github.com/mrwersa/agentverity) decision suite |
 
 Every analysis command takes `--json` and exits non-zero on a finding, so they drop into CI unchanged. `scan` writes a manifest to standard output and is a one-off, not a gate.
 
@@ -194,9 +197,25 @@ does not pass as an empty value.
 
 This is analysis, not enforcement. It runs in CI against a manifest, it does not sit in the request path.
 
-[AgentWard](https://github.com/agentward-ai/agentward) is a runtime proxy that enforces policy on each call and can diff two policy files. [AgentShield](https://github.com/affaan-m/agentshield) scans agent configuration and MCP servers, with a drift gate over scan findings. [AgentGuard](https://github.com/WhitzardAgent/AgentGuard) implements attribute-based access control for tool calls. [OPA](https://www.openpolicyagent.org/docs) and [Cedar](https://docs.cedarpolicy.com/) decide one authorisation at a time.
+| Tool | What it does | Relationship |
+|---|---|---|
+| [Policy in Amazon Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy.html) | Evaluates all applicable Cedar policies for each gateway tool invocation, with default-deny, forbid-wins, and analysis that flags always-allow and always-deny policies | Enforces each invocation. Its documented analysis is policy-level, not a model of a sequence of permitted calls |
+| [AgentWard](https://github.com/agentward-ai/agentward) | Runtime proxy enforcing policy per call, diffs two policy files | Enforces. Diffs declared text rather than reachable authority |
+| [AgentShield](https://github.com/affaan-m/agentshield) | Scans agent configuration and MCP servers, drift gate over findings | Scans. Drift is over finding counts, not permission direction |
+| [AgentGuard](https://github.com/WhitzardAgent/AgentGuard) | Attribute-based access control for tool calls | Enforces |
+| [OPA](https://www.openpolicyagent.org/docs), [Cedar](https://docs.cedarpolicy.com/) | Decide one authorisation at a time | Enforces |
 
-Use those to enforce. AgentMandate complements them by analysing compound sequences and comparing *effective* authority across releases. The closest prior art in a neighbouring domain is [IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-concepts.html), which derives reachable access from policy by automated reasoning rather than waiting for a log event. This is that idea pointed at agent tool graphs.
+Use those to enforce. AgentMandate is the offline half: it analyses sequences of individually permitted calls and compares *effective* authority across releases.
+
+**If you already run AgentCore Policy**, the gap is specific. The policy engine
+answers "may this principal invoke this tool now" by evaluating all applicable
+policies, and its documented analysis catches policy-level problems such as an
+unconditional allow. It does not model whether four separately permitted calls
+compose into a 1,000 GBP breach or whether a release widened what the agent can
+reach. AgentMandate is vendor-neutral and runs in CI before deployment, so it
+complements the gateway rather than duplicating it.
+
+The closest prior art in a neighbouring domain is [IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-concepts.html), which derives reachable access from policy by automated reasoning rather than waiting for a log event. This is that idea pointed at agent tool graphs.
 
 The `lint` command deliberately overlaps the scanners above. A tool that reported only compound findings would need one of them running alongside it to be usable at all.
 
@@ -233,7 +252,7 @@ ruff check .
 
 ## Status
 
-Alpha, version 0.2.0. The authority model is the part most likely to change,
+Alpha, version 0.3.0. The authority model is the part most likely to change,
 because it has not yet been pointed at enough real tool graphs to know where it
 is too coarse. Issues describing a graph it models badly are the most useful
 thing you can file.

{agentmandate-0.2.0 → agentmandate-0.3.0}/agentmandate/__init__.py

@@ -13,11 +13,20 @@ against the declaration, so it is usable without another tool alongside it.
 
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 from .diff import Change, Delta, compare
 from .lint import Finding, check
 from .manifest import Mandate, ManifestError, Money, Tool, load, loads
+from .obligations import (
+    OBLIGATIONS_SCHEMA,
+    Obligation,
+    ObligationSet,
+    derive,
+    load_obligations,
+    save_obligations,
+    to_decision_suite,
+)
 from .reach import Authority, Breach, Step, analyse
 from .scan import Proposal, propose, render, scan_file
 from .verify import Conformance, Observation, Violation, replay, replay_file
@@ -31,7 +40,10 @@ __all__ = [
     "Finding",
     "Mandate",
     "ManifestError",
+    "OBLIGATIONS_SCHEMA",
     "Money",
+    "Obligation",
+    "ObligationSet",
     "Observation",
     "Proposal",
     "Step",
@@ -40,9 +52,13 @@ __all__ = [
     "__version__",
     "analyse",
     "check",
+    "derive",
     "compare",
     "load",
+    "load_obligations",
     "loads",
+    "save_obligations",
+    "to_decision_suite",
     "propose",
     "render",
     "replay",

{agentmandate-0.2.0 → agentmandate-0.3.0}/agentmandate/cli.py

@@ -11,6 +11,12 @@ from . import __version__
 from .diff import compare
 from .lint import ERROR, check
 from .manifest import ManifestError, load
+from .obligations import (
+    derive,
+    load_obligations,
+    reconcile,
+    to_decision_suite,
+)
 from .reach import analyse
 from .scan import scan_file
 from .verify import replay_file
@@ -74,6 +80,26 @@ def build_parser() -> argparse.ArgumentParser:
         help="emit a markdown change record for a change advisory board",
     )
 
+    obligations_parser = subparsers.add_parser(
+        "obligations",
+        help="derive reviewable test obligations from reachable authority",
+    )
+    _add_manifest(obligations_parser)
+    obligations_parser.add_argument("--depth", type=_positive_int, default=None)
+    obligations_parser.add_argument(
+        "--json", action="store_true", help="machine-readable output"
+    )
+    obligations_parser.add_argument(
+        "--suite",
+        action="store_true",
+        help="render reviewed obligations as an AgentVerity decision suite",
+    )
+    obligations_parser.add_argument(
+        "--reviewed",
+        default=None,
+        help="an obligations file whose decisions have been filled in",
+    )
+
     verify_parser = subparsers.add_parser(
         "verify", help="replay recorded calls against the manifest"
     )
@@ -124,6 +150,27 @@ def main(argv: Sequence[str] | None = None) -> int:
         print(f"error: {exc}", file=sys.stderr)
         return EXIT_USAGE
 
+    if args.command == "obligations":
+        obligations = derive(mandate, depth=args.depth)
+        if args.reviewed:
+            # Reconciled against the live manifest rather than trusted on its
+            # own. A stale review would otherwise generate a suite for
+            # authority the agent no longer has.
+            try:
+                obligations = reconcile(obligations, load_obligations(args.reviewed))
+            except ValueError as exc:
+                print(f"error: {exc}", file=sys.stderr)
+                return EXIT_USAGE
+        if args.suite:
+            try:
+                print(json.dumps(to_decision_suite(obligations), indent=2))
+            except ValueError as exc:
+                print(f"error: {exc}", file=sys.stderr)
+                return EXIT_FINDING
+            return EXIT_OK
+        _emit(obligations.to_dict(), args.json, obligations.render())
+        return EXIT_FINDING if obligations.unreviewed else EXIT_OK
+
     if args.command == "lint":
         findings = check(mandate)
         payload = {

agentmandate-0.3.0/agentmandate/obligations.py

@@ -0,0 +1,360 @@
+"""Turn reachable authority into reviewable test obligations.
+
+A mandate says what an agent is permitted to do. A test suite says what was
+actually exercised. Nothing connects them today, so a manifest can declare an
+irreversible refund the tests never approach and both artefacts look healthy.
+
+This emits an obligation per consequential thing the agent can reach: a
+statement that some reviewed test case ought to exercise this decision point.
+
+What it deliberately does not do:
+
+- It does not generate decision labels. An effect class such as
+  ``irreversible on case`` is an authority fact. A decision such as
+  ``card_security`` is an application label chosen by whoever designed the
+  router. No parsing turns one into the other, and inventing the mapping would
+  be a confident guess about somebody else's domain.
+- It does not emit compound breaches. A cumulative-value path is a multi-call
+  sequence, which is scenario testing rather than decision coverage. Those
+  stay in ``reach`` and do not cross into a test suite.
+
+So the output is a skeleton with a blank ``decision`` on every row, for a human
+to fill in. Extract then annotate, the same discipline ``scan`` already follows.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .manifest import IRREVERSIBLE, SERVICE, Mandate
+from .reach import analyse
+
+OBLIGATIONS_SCHEMA = "agentmandate.obligations/v1"
+
+
+@dataclass(frozen=True)
+class Obligation:
+    """One reachable authority fact a reviewed test ought to exercise."""
+
+    kind: str
+    subject: str
+    reason: str
+    decision: str = ""
+    # Probe texts a reviewer wrote to reach this decision. A generated suite
+    # needs real inputs, and inventing them would produce a file that runs and
+    # measures nothing.
+    cases: tuple[str, ...] = ()
+
+    @property
+    def identifier(self) -> str:
+        """A stable name, so a reviewed mapping survives regeneration."""
+        return f"{self.kind}:{self.subject}"
+
+    @property
+    def reviewed(self) -> bool:
+        """Whether a human has supplied both the decision and a probe.
+
+        A decision without a case is half a review. The suite it generates
+        would carry placeholder text that AgentVerity happily runs, producing
+        numbers about nothing.
+        """
+        return bool(self.decision) and bool(self.cases)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.identifier,
+            "kind": self.kind,
+            "subject": self.subject,
+            "reason": self.reason,
+            "decision": self.decision,
+            "cases": list(self.cases),
+        }
+
+    @classmethod
+    def from_dict(cls, value: Any) -> Obligation:
+        if not isinstance(value, dict):
+            raise ValueError("obligation must be an object")
+        missing = {"kind", "subject"} - set(value)
+        if missing:
+            raise ValueError(
+                "obligation is missing " + ", ".join(sorted(missing))
+            )
+        kind = value["kind"]
+        subject = value["subject"]
+        reason = value.get("reason", "")
+        decision = value.get("decision", "")
+        cases = value.get("cases", [])
+        for field, item in (
+            ("kind", kind),
+            ("subject", subject),
+            ("reason", reason),
+            ("decision", decision),
+        ):
+            if not isinstance(item, str):
+                raise ValueError(f"obligation {field} must be a string")
+        if not kind.strip() or not subject.strip():
+            raise ValueError("obligation kind and subject must not be blank")
+        if decision and not decision.strip():
+            raise ValueError("obligation decision must not be whitespace")
+        if not isinstance(cases, list) or any(
+            not isinstance(case, str) or not case.strip() for case in cases
+        ):
+            raise ValueError("obligation cases must be a list of non-blank strings")
+        if len(cases) != len(set(cases)):
+            raise ValueError("obligation cases must not contain duplicates")
+        identifier = f"{kind}:{subject}"
+        if "id" in value and value["id"] != identifier:
+            raise ValueError(
+                f"obligation id {value['id']!r} does not match {identifier!r}"
+            )
+        return cls(
+            kind=kind,
+            subject=subject,
+            reason=reason,
+            decision=decision,
+            cases=tuple(cases),
+        )
+
+
+@dataclass(frozen=True)
+class ObligationSet:
+    """Every obligation derived from one mandate."""
+
+    agent: str
+    obligations: tuple[Obligation, ...]
+
+    @property
+    def unreviewed(self) -> tuple[str, ...]:
+        """Obligations with no decision mapped to them yet."""
+        return tuple(o.identifier for o in self.obligations if not o.reviewed)
+
+    @property
+    def decisions(self) -> tuple[str, ...]:
+        """The distinct decisions a reviewer has mapped."""
+        return tuple(sorted({o.decision for o in self.obligations if o.reviewed}))
+
+    def render(self) -> str:
+        lines = [f"test obligations for {self.agent}"]
+        if not self.obligations:
+            lines.append("  none: no consequential authority is reachable")
+            return "\n".join(lines)
+        for obligation in self.obligations:
+            lines.append(f"  {obligation.identifier}")
+            lines.append(f"    why:      {obligation.reason}")
+            lines.append(
+                f"    decision: {obligation.decision or 'REVIEW: map a decision'}"
+            )
+            lines.append(
+                "    cases:    "
+                + (
+                    ", ".join(obligation.cases)
+                    if obligation.cases
+                    else "REVIEW: write at least one probe that reaches it"
+                )
+            )
+        if self.unreviewed:
+            lines.append("")
+            lines.append(
+                f"{len(self.unreviewed)} obligation(s) need a reviewed decision "
+                "before a suite can be generated"
+            )
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema": OBLIGATIONS_SCHEMA,
+            "agent": self.agent,
+            "obligations": [o.to_dict() for o in self.obligations],
+        }
+
+    @classmethod
+    def from_dict(cls, value: Any) -> ObligationSet:
+        if not isinstance(value, dict):
+            raise ValueError("obligations root must be an object")
+        if value.get("schema") != OBLIGATIONS_SCHEMA:
+            raise ValueError(
+                f"unsupported obligations schema: {value.get('schema')!r}"
+            )
+        raw = value.get("obligations")
+        if not isinstance(raw, list):
+            raise ValueError("obligations must be a list")
+        return cls(
+            agent=str(value.get("agent", "")),
+            obligations=tuple(Obligation.from_dict(entry) for entry in raw),
+        )
+
+
+def derive(mandate: Mandate, depth: int | None = None) -> ObligationSet:
+    """Derive obligations from what the mandate actually lets the agent reach.
+
+    Reachability rather than declaration: a tool nobody can get to needs no
+    test, and listing it would pad the review with work that protects nothing.
+    """
+    authority = analyse(mandate, depth=depth)
+    obligations: list[Obligation] = []
+
+    for name in sorted(authority.reachable_tools):
+        tool = mandate.tool(name)
+        if tool is None:  # pragma: no cover - reachable names come from tools
+            continue
+        if tool.effect == IRREVERSIBLE:
+            obligations.append(
+                Obligation(
+                    kind="irreversible",
+                    subject=name,
+                    reason=(
+                        "an irreversible effect is reachable, so some reviewed "
+                        "case should exercise the decision that leads to it"
+                    ),
+                )
+            )
+        if tool.requires_approval:
+            obligations.append(
+                Obligation(
+                    kind="approval-required",
+                    subject=name,
+                    reason=(
+                        "an approval gate is reachable, and a gate no test "
+                        "reaches has never been shown to hold"
+                    ),
+                )
+            )
+        if tool.principal == SERVICE:
+            obligations.append(
+                Obligation(
+                    kind="service-principal",
+                    subject=name,
+                    reason=(
+                        "this call spends a service account rather than the "
+                        "caller's identity, which is the confused-deputy shape"
+                    ),
+                )
+            )
+        if tool.spends_value:
+            obligations.append(
+                Obligation(
+                    kind="value-bearing",
+                    subject=name,
+                    reason=(
+                        f"this call spends value up to {tool.ceiling}, so the "
+                        "decision that authorises it deserves reviewed cases"
+                    ),
+                )
+            )
+    return ObligationSet(agent=mandate.agent, obligations=tuple(obligations))
+
+
+def reconcile(current: ObligationSet, reviewed: ObligationSet) -> ObligationSet:
+    """Carry reviewed decisions onto obligations derived from the live manifest.
+
+    A reviewed file is a record of decisions somebody mapped, not a substitute
+    for the manifest. Trusting it on its own lets a stale or unrelated review
+    generate a suite for authority the agent no longer has, which is the exact
+    drift this package exists to catch.
+
+    Matching is by stable identifier, so:
+
+    - an obligation that still exists keeps its reviewed decision and cases
+    - an obligation the manifest no longer reaches is dropped
+    - a newly reachable obligation appears unreviewed, and blocks generation
+      until somebody looks at it
+    """
+    mapped = {o.identifier: o for o in reviewed.obligations}
+    return ObligationSet(
+        agent=current.agent,
+        obligations=tuple(
+            (
+                Obligation(
+                    kind=obligation.kind,
+                    subject=obligation.subject,
+                    reason=obligation.reason,
+                    decision=mapped[obligation.identifier].decision,
+                    cases=mapped[obligation.identifier].cases,
+                )
+                if obligation.identifier in mapped
+                else obligation
+            )
+            for obligation in current.obligations
+        ),
+    )
+
+
+def to_decision_suite(
+    obligations: ObligationSet, *, critical: bool = True
+) -> dict[str, Any]:
+    """Render reviewed obligations as an AgentVerity decision-suite skeleton.
+
+    Every obligation must carry a reviewed decision first. Generating a suite
+    from unreviewed rows would invent application labels from authority facts,
+    which is exactly the guess this module refuses to make.
+
+    Raises:
+        ValueError: If any obligation still lacks a decision.
+    """
+    if obligations.unreviewed:
+        raise ValueError(
+            "these obligations are not fully reviewed yet: "
+            + ", ".join(obligations.unreviewed)
+            + ". Each needs the decision your agent returns and at least one "
+            "probe that reaches it. A suite generated from placeholders would "
+            "run and measure nothing."
+        )
+
+    decisions = obligations.decisions
+    if not decisions:
+        raise ValueError("no obligations to generate a suite from")
+    seen: set[str] = set()
+    for obligation in obligations.obligations:
+        duplicates = seen & set(obligation.cases)
+        if duplicates:
+            raise ValueError(
+                "the same probe is reviewed twice: " + ", ".join(sorted(duplicates))
+            )
+        seen.update(obligation.cases)
+
+    contract: dict[str, Any] = {
+        "allowed": list(decisions),
+        "required": list(decisions),
+    }
+    if critical:
+        # An irreversible or value-bearing obligation is what "critical" is
+        # for. Approval gates and service principals matter, but they are not
+        # in themselves a consequence class.
+        contract["critical"] = sorted(
+            {
+                o.decision
+                for o in obligations.obligations
+                if o.kind in {"irreversible", "value-bearing"}
+            }
+        )
+
+    return {
+        "schema": "agentverity.decision-suite/v1",
+        "contract": contract,
+        # Inputs come from the reviewer. Authority analysis cannot invent a
+        # probe that reaches a decision, and shipping placeholder text would
+        # produce a suite AgentVerity runs happily while measuring nothing.
+        "cases": [
+            {"input": case, "expected": obligation.decision}
+            for obligation in obligations.obligations
+            for case in obligation.cases
+        ],
+    }
+
+
+def load_obligations(path: str | Path) -> ObligationSet:
+    try:
+        value = json.loads(Path(path).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ValueError(f"cannot load obligations: {exc}") from exc
+    return ObligationSet.from_dict(value)
+
+
+def save_obligations(obligations: ObligationSet, path: str | Path) -> None:
+    Path(path).write_text(
+        json.dumps(obligations.to_dict(), indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )