open/portfolio-optimiser
1
0
Fork 0
Code Issues Releases 3 Activity

docs(s54): --report CLI surface + truthful costsim kost_mot_verdi seam note

Browse source
This commit is contained in:
Kjell Tore Guttormsen 2026-07-24 01:38:10 +02:00
commit 0343b42d88
3 changed files with 21 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

10
README.md
View file

@ -98,19 +98,27 @@ when the seam is detached, so the loop cannot silently degrade into theater.
extension point) via a deterministic, schema-validated manifest that runs *before* the loop is
implemented and exercised against committed fixtures — no bundle has yet been materialized from
a live source.
- **Run:** the `run.py` CLI has **two modes** — a documented partition, since one invocation
- **Run:** the `run.py` CLI has **three modes** — a documented partition, since one invocation
cannot exercise every flag:
- **Single-project** — `PROJECT_ID --docs-dir <dir>`, plus optional `--bundle-dir`,
`--verdict-dir`, `--outbox-dir` (which requires `--run-id`), `--dimension-config`,
`--decision`/`--rationale`, and `--live-dry-run`.
- **Portfolio** — `--portfolio`, plus optional `--goals`, `--ledger`, `--dimension-config`;
it stops early and prints a `goal reached: …` line when the accumulated ledger meets a goal.
- **Value report (S5.4, read-only)** — `--report --ledger <file>` rolls up the ledger's realized
savings to stdout: per-project totals, the portfolio total, flagged cross-dimension overlaps
(each counted once), and per-entry provenance. Add `--json` for deterministic JSON instead of
the human table. It makes **no model calls** and is mode-exclusive — only `--ledger`/`--json`
are permitted alongside `--report`; `--report` requires `--ledger`, and a stray `--json`
without `--report` is refused (rc 1, never silently ignored).
```bash
# Single-project, offline drill (builds contracts + clients, stops before the first model call):
uv run python -m portfolio_optimiser.run FV42-GSV-E1 --docs-dir <docs> --bundle-dir <bundle> --live-dry-run
# Portfolio run with a savings goal checked against an accumulated ledger:
uv run python -m portfolio_optimiser.run --portfolio --goals goals.json --ledger ledger.json
# Read-only value report over an accumulated ledger (human table; add --json for JSON):
uv run python -m portfolio_optimiser.run --report --ledger ledger.json
```
The **prior-verdict fold — the learning step — happens only on the `--bundle-dir` path**; a