feat(cli): --mandate — a run announces what it will do, and settles for it

Krav 2: a run must be clear about what it shall do and achieve. `--mandate`
makes both ends explicit. BEFORE the first (paid) model call the run prints what
it was commissioned to do — objective, every named approach, whether its own
proposals are allowed, the scope, the caps, and which external services it will
contact. AFTER the run it settles: one row per approach, validated with the
figure, rejected with the validator's reason, or not evaluated with why.

The announcement is placed with the other refusals and above the scripted
banner, for the reason the required-args guard was hoisted there: a refused run
must not first print a banner about work it never did. `--live-dry-run`
announces without contacting anything, so a commission can be inspected before
it costs money.

`settle` renders the goal verdict it is GIVEN and never decides it. `ledger.to_ore`
is the framework's one NOK->øre conversion and the goal comparison already runs on
quantised integers, but `mandate.py` cannot import it without dragging `verdicts`
— and therefore agent_framework — into a deliberately framework-neutral module,
while a private copy of a money conversion is exactly the (p) defect. So the
caller decides and this renders; a goal figure without a decided verdict makes no
claim at all.

The caps the announcement prints come from named constants shared with
`run_project`/`run_portfolio`'s defaults — a second copy could drift and make the
announcement describe a run that never happened.

Load-bearing MEASURED against the whole 717-test suite, four mutations all red:
detach the announcement (4) · detach the settlement print (2) · make the CLI
loader tolerant (2) · announce the commission but never hand it to the run (2).
The last one is the one that matters: without it, a run could print a commission
it had no intention of executing.

DEVIATION from the approved plan, stated rather than quietly dropped: --goals is
still refused outside portfolio mode. Accepting it in single-project mode would
have admitted a flag whose documented function (the goal-stop against the ledger)
still does nothing there — the same accepted-but-inert defect --embedder-config
was just fixed for. The mandate's success_criteria carries "what shall this run
achieve" in the expert's own words instead; the numeric target stays portfolio-level.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ULCqjLF61rehj5cZmdUoR3

tests/test_mandate.py

@@ -24,9 +24,11 @@ from pydantic import ValidationError
 from portfolio_optimiser.mandate import (
     OWN_PROPOSAL_ID,
     Approach,
+    ApproachOutcome,
     Mandate,
     announce,
     load_mandate,
+    settle,
 )
 
 
@@ -222,3 +224,86 @@ def test_announce_states_the_caps() -> None:
 def test_announce_is_deterministic() -> None:
     """Byte-stable: no wall clock, no set-iteration ordering — so it can be golden-tested."""
     assert _announce() == _announce()
+
+
+# --- the settlement (Trekk A4): what the run actually did about each approach -------------------
+
+_ROWS = (
+    ApproachOutcome(id="led-retrofit", label="LED", status="validated", saving_nok=30_000.0),
+    ApproachOutcome(
+        id="service-contract",
+        label="Contract",
+        status="rejected",
+        detail="claimed 200000 exceeds feasible 90000",
+    ),
+    ApproachOutcome(
+        id="night-setback",
+        label="Setback",
+        status="not_evaluated",
+        detail="budget exhausted before this approach was evaluated",
+    ),
+)
+
+
+def test_settle_reports_every_row_including_the_unevaluated_one() -> None:
+    """All three statuses reach the report. The unevaluated row is the point: an approach the run
+    never got to must be visibly unreached, not absent."""
+    text = settle(_ROWS)
+    assert "led-retrofit" in text
+    assert "service-contract" in text
+    assert "night-setback" in text
+    assert "NOT EVALUATED" in text
+
+
+def test_settle_carries_the_rejection_reason() -> None:
+    """A rejected approach without its reason tells the expert nothing they can act on."""
+    assert "claimed 200000 exceeds feasible 90000" in settle(_ROWS)
+
+
+def test_settle_totals_only_the_validated_savings() -> None:
+    """The total is what passed the validator — never the claimed sum of everything attempted."""
+    text = settle(_ROWS)
+    assert "30000" in text
+    assert "200000 NOK" not in text  # the rejected claim is never folded into a total
+
+
+def test_settle_states_whether_the_target_was_reached() -> None:
+    """Krav 2's second half: the run answers, in its own output, whether it achieved what it was
+    commissioned to achieve."""
+    missed = settle(_ROWS, goal_nok=150_000.0, goal_reached=False)
+    hit = settle(_ROWS, goal_nok=10_000.0, goal_reached=True)
+    assert "not reached" in missed
+    assert "reached" in hit and "not reached" not in hit
+
+
+def test_settle_renders_the_goal_verdict_it_is_GIVEN_and_never_decides_it() -> None:
+    """The renderer must not form a SECOND opinion on a money question.
+
+    ``ledger.to_ore`` is the framework's one NOK->øre conversion and the goal comparison already
+    runs on quantised integers; this module cannot import it without dragging ``verdicts`` — and
+    therefore ``agent_framework`` — into a deliberately framework-neutral file, and a private copy
+    of a money conversion is exactly the ``(p)`` defect. So the caller decides and this renders.
+    Told the opposite of what its own float sum suggests, it prints what it was told.
+    """
+    text = settle(_ROWS, goal_nok=150_000.0, goal_reached=True)
+    assert "not reached" not in text
+
+
+def test_settle_omits_the_target_line_when_no_goal_was_configured() -> None:
+    """No goal configured -> no verdict on a goal. An absent target must not read as a missed one."""
+    assert "Target" not in settle(_ROWS)
+    # ...and a goal figure without a decided verdict renders no claim either.
+    assert "Target" not in settle(_ROWS, goal_nok=150_000.0)
+
+
+def test_settle_is_empty_without_coverage() -> None:
+    """No mandate -> nothing to settle. An empty block beats a header over zero rows, which would
+    imply a commission that never existed."""
+    assert settle(()) == ""
+
+
+def test_settle_is_deterministic() -> None:
+    """Byte-stable, like the announcement."""
+    assert settle(_ROWS, goal_nok=150_000.0, goal_reached=False) == settle(
+        _ROWS, goal_nok=150_000.0, goal_reached=False
+    )

tests/test_mandate_cli.py

@@ -0,0 +1,186 @@
+"""The CLI door onto the mandate (Trekk A6): ``--mandate <file.json>``.
+
+Krav 1 and 2 are only real if a domain expert can reach them from a command line. This pins the
+three visible halves:
+
+1. the commission is loaded FAIL-FAST — a missing or malformed mandate refuses the run (rc 1),
+   because a silently degraded commission would make the settlement describe work nobody ordered;
+2. the run ANNOUNCES what it will do BEFORE it does it, and the announcement precedes the outcome
+   line in the output (an after-the-fact statement of intent is not a statement of intent);
+3. the run SETTLES against that commission afterwards, naming every approach.
+
+The control asserts both blocks are absent without ``--mandate`` — so no assertion above can pass
+on a constant the CLI prints anyway.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+import pytest
+
+from portfolio_optimiser import run
+
+BUNDLE_DIR = Path(__file__).resolve().parents[1] / "shared" / "examples" / "bygg-energi-mikro"
+
+_VALID_PROPOSAL = (
+    '{"measure":"LED-retrofit av kontorbelysning","affected_items":'
+    '[{"code":"ENERGI-TOTAL-EL","quantity":300000,"unit_cost":1.0}],"claimed_saving_nok":30000}'
+)
+_CHECKER_APPROVE = "Tallene er innenfor feasibelt område og resonnementet holder. VERDICT: APPROVE"
+
+_MANDATE = {
+    "objective": "Kutt energikostnad uten ombygging i 2026.",
+    "approaches": [
+        {
+            "id": "led-retrofit",
+            "label": "LED-retrofit av kontorbelysning",
+            "description": "Drift mener armaturene er originale.",
+        }
+    ],
+    "allow_own_proposals": False,
+    "success_criteria": "Minst ett tiltak som passerer validatoren.",
+}
+
+
+@pytest.fixture(autouse=True)
+def _isolate_model_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("PORTFOLIO_MODEL_MAP", raising=False)
+    monkeypatch.delenv("PORTFOLIO_FOUNDRY_PROJECT_ENDPOINT", raising=False)
+
+
+@pytest.fixture()
+def bundle(tmp_path: Path) -> Path:
+    """A throwaway COPY — the commons-owned fixture is never mutated by a test."""
+    dst = tmp_path / "bundle"
+    shutil.copytree(BUNDLE_DIR, dst)
+    return dst
+
+
+@pytest.fixture()
+def replies_file(tmp_path: Path) -> Path:
+    path = tmp_path / "replies.json"
+    path.write_text(
+        json.dumps({"proposer": _VALID_PROPOSAL, "checker": _CHECKER_APPROVE}), encoding="utf-8"
+    )
+    return path
+
+
+@pytest.fixture()
+def mandate_file(tmp_path: Path) -> Path:
+    path = tmp_path / "mandate.json"
+    path.write_text(json.dumps(_MANDATE), encoding="utf-8")
+    return path
+
+
+def _argv(bundle: Path, replies: Path, *extra: str) -> list[str]:
+    return [
+        "BYGG-KONTOR-NORD",
+        "--docs-dir",
+        str(bundle),
+        "--bundle-dir",
+        str(bundle),
+        "--scripted-replies",
+        str(replies),
+        *extra,
+    ]
+
+
+def test_missing_mandate_refuses_the_run(bundle, replies_file, capsys) -> None:
+    """A mandate that is not there refuses — never treated as 'no mandate given'."""
+    rc = run.main(_argv(bundle, replies_file, "--mandate", str(bundle / "nope.json")))
+    assert rc == 1
+    assert "refused" in capsys.readouterr().err.lower()
+
+
+def test_malformed_mandate_refuses_the_run(bundle, replies_file, tmp_path, capsys) -> None:
+    """A malformed commission refuses too: authoritative startup config, not a tolerant inbox."""
+    bad = tmp_path / "bad.json"
+    bad.write_text('{"approaches": []}', encoding="utf-8")  # no objective
+    rc = run.main(_argv(bundle, replies_file, "--mandate", str(bad)))
+    assert rc == 1
+    assert "refused" in capsys.readouterr().err.lower()
+
+
+def test_run_announces_the_mandate_before_it_runs(
+    bundle, replies_file, mandate_file, capsys
+) -> None:
+    """The announcement names the objective and every commissioned approach, and it appears BEFORE
+    the run's outcome line — intent stated up front, not reported after the fact."""
+    rc = run.main(_argv(bundle, replies_file, "--mandate", str(mandate_file)))
+    out = capsys.readouterr().out
+    assert rc == 0, out
+    assert "Run mandate for BYGG-KONTOR-NORD" in out
+    assert "Kutt energikostnad uten ombygging i 2026." in out
+    assert "led-retrofit" in out
+    assert out.index("Run mandate for") < out.index("BYGG-KONTOR-NORD: ")
+
+
+def test_run_settles_against_the_mandate_afterwards(
+    bundle, replies_file, mandate_file, capsys
+) -> None:
+    """The settlement names every commissioned approach and its status, AFTER the run."""
+    rc = run.main(_argv(bundle, replies_file, "--mandate", str(mandate_file)))
+    out = capsys.readouterr().out
+    assert rc == 0, out
+    assert "Mandate outcome" in out
+    assert "led-retrofit" in out.split("Mandate outcome")[1]
+    assert out.index("Run mandate for") < out.index("Mandate outcome")
+
+
+def test_dry_run_announces_without_calling_a_model(bundle, mandate_file, capsys) -> None:
+    """``--live-dry-run`` shows what the run WOULD do — the announcement is offline by
+    construction, so an operator can inspect a commission before paying for it."""
+    rc = run.main(
+        [
+            "BYGG-KONTOR-NORD",
+            "--docs-dir",
+            str(bundle),
+            "--bundle-dir",
+            str(bundle),
+            "--mandate",
+            str(mandate_file),
+            "--live-dry-run",
+        ]
+    )
+    out = capsys.readouterr().out
+    assert rc == 0, out
+    assert "Run mandate for BYGG-KONTOR-NORD" in out
+    assert "LIVE-DRY-RUN OK" in out
+    # A dry run stops before the first model call, so there is nothing to settle.
+    assert "Mandate outcome" not in out
+
+
+def test_portfolio_mode_applies_the_mandate_to_every_project(
+    replies_file, mandate_file, capsys
+) -> None:
+    """The mandate applies to every project in a portfolio pass, and each project settles for it
+    separately — a threading line with no test of its own is the green-but-dead trap this repo
+    was bitten by in Fase 2."""
+    rc = run.main(
+        [
+            "--portfolio",
+            "--scripted-replies",
+            str(replies_file),
+            "--mandate",
+            str(mandate_file),
+        ]
+    )
+    out = capsys.readouterr().out
+    assert rc == 0, out
+    assert "Run mandate for the portfolio" in out
+    settlements = out.count("Mandate outcome")
+    assert settlements >= 2, f"expected one settlement per project, saw {settlements}"
+    assert "led-retrofit" in out.split("Mandate outcome")[1]
+
+
+def test_no_mandate_prints_neither_block(bundle, replies_file, capsys) -> None:
+    """CONTROL: without ``--mandate`` the CLI output is the pre-Trekk-A one — no announcement, no
+    settlement. Every assertion above would otherwise be able to pass on constant output."""
+    rc = run.main(_argv(bundle, replies_file))
+    out = capsys.readouterr().out
+    assert rc == 0, out
+    assert "Run mandate for" not in out
+    assert "Mandate outcome" not in out