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

docs(s53): README two-mode CLI matrix + honesty-scoped learning-loop claims + CHANGELOG catch-up

Browse source 
README: the stale one-line CLI mention replaced by the two-mode flag matrix (single-project vs
--portfolio), runnable 'uv run python -m portfolio_optimiser.run ...' examples, the --outbox-dir
!= --verdict-dir self-contamination warning (documented, not enforced), and the --decision/
--rationale inert-in-portfolio note. Honesty scoping: the prior-verdict fold (the learning step)
is stated to happen ONLY on the --bundle-dir path; a --docs-dir-only run is single-shot (no fold).
CHANGELOG [Unreleased]/Added: S5.3 CLI-parity entry (six flags + portfolio mode + load_dimension +
recipe doc) plus catch-up for the shipped-but-undocumented S4.1 (preflight), S4.2 (--live-dry-run),
S5.1 (hitl CLI), S5.2 (notify); stale test count 237 -> 431. extending.md verified accurate (B11
notifier note stands verbatim — main() auto-wires no notifier; no CLI section to sync), left
unchanged.

SC4 honesty grep clean (each hit in bundle-path context, none on a fold-less path):
  grep -rniE 'learning loop|learns from|self-improv' README.md docs/extending.md CHANGELOG.md
  README:11 (system-level) :56 (wiki substrate) :67 (8-step bundle loop);
  CHANGELOG:13 (gated ExpeL fold) :17 (offline simulation). Full suite 431 passed (no code touched).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KNNiJRk1sSwxgVLS5AobT1
This commit is contained in:
Kjell Tore Guttormsen 2026-07-23 21:51:00 +02:00
commit c0d3ba4459
2 changed files with 40 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

25
README.md
View file

@ -98,9 +98,28 @@ 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 CLI takes a bundle directory and a verdict inbox directory; stop criteria and
budget caps are required at startup. Try the offline end-to-end proof (no model, no network):
`uv run python -m portfolio_optimiser.simulation`
- **Run:** the `run.py` CLI has **two 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.
```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
```
The **prior-verdict fold — the learning step — happens only on the `--bundle-dir` path**; a
plain `--docs-dir`-only run is single-shot (no fold). `--decision`/`--rationale` apply to the
single-project path only and are inert in portfolio mode. **`--outbox-dir` must differ from
`--verdict-dir`**: writing the raw outbox into a folder later read as an inbox would re-ingest
raw agent output past the promotion gate (self-contamination) — documented here, deliberately
not CLI-enforced. Stop criteria and budget caps are required at startup. Try the offline
end-to-end proof (no model, no network): `uv run python -m portfolio_optimiser.simulation`.
## What this enables