portfolio-optimiser/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

• Deterministic backbone: mandatory blocking validator (solver + Monte Carlo against the shared golden suite), budget meter with hard fail-fast caps, provenance stamping.
• Agentic learning loop wired end to end, one load-bearing seam at a time (target-picture steps 1, 3/4, 5, 7, 8): OKF-navigated bundle context with the gated ExpeL fold, maker-checker debate where the checker gates the reasoning, informed refinement (previous rejection reason fed into the next bounded attempt), async verdict file inbox, and gated wiki promotion (fail-closed).
• Offline end-to-end simulation proving the learning loop closes with a scripted client (uv run python -m portfolio_optimiser.simulation) — plumbing proof, not live-model proof.
• Framework-neutral shared core in shared/: OKF concept + example bundle, golden validator suite, and the expert-reviewer persona as an Agent Skill.
• CLI parity (S5.3): run.py drives the whole method from the command line in two modes — single-project (--dimension-config, --outbox-dir/--run-id, plus the already-wired --bundle-dir/--verdict-dir) and portfolio (--portfolio with --goals/--ledger), the latter printing an observable goal reached: … line when a savings goal is met. Adds a fail-fast load_dimension loader and structured refusals (rc 1, no traceback) for misuse and mode-exclusivity violations. The prior-verdict fold is on the --bundle-dir path only; a --docs-dir-only run is single-shot.
• Value report (S5.4): a read-only --report [--json] --ledger <file> surface on run.py that rolls up the accumulated SavingsLedger — per-project + portfolio totals (dimension-free-deduped integer øre), flagged cross-dimension overlaps (each counted once), and per-entry provenance — as a human table or deterministic JSON. Makes no model calls; mode-exclusive (only --ledger/--json permitted with --report, which requires --ledger). Honest scope boundary: the report core (value_report.py) now exists but is deliberately not wired into costsim's kost_mot_verdi placeholder — that cost-vs-value integration is a separate, deferred step. The costsim seam note was reworded from the stale "fylles av S5.4 verdirapport" to a truthful forward reference so costsim's own output no longer claims the wiring is done.
• Semantic retrieval seam (S3.1): a new MAF-free semretrieval.py adds an Embedder/Retriever pair and a HybridRanker blending a numpy cosine term over the embedded feature triple (sorted cost codes, measure type, magnitude bucket) with the existing structural score, exposed as --semantic-retrieval. What ships is the seam, not better retrieval quality: the bundled FakeEmbedder is a deterministic sha256 projection with no semantics, so over a structural tie the order is deterministic but arbitrary. A real embedder is selected from a CLOSED registry via --embedder-config / build_embedder — deliberately never an import path, so a config file can never name arbitrary code to load. Off by default and additive: with no retriever passed the store delegates to StructuralRetriever, which reproduces the pre-seam ranking exactly, so the text-excluded default and every existing test are unchanged. The embedding excludes description, matching similarity ("text is ignored by design") and the verdict-id hash — so a flag-on run reads no surface text either, and a genuine expert verdict can no longer be outranked by the framework's own echo of the query. The ranker is passed PER CALL, never assigned to the caller's store, so the opt-in cannot outlive the run that asked for it. Accepted in both run modes; in single-project mode it requires --bundle-dir and --verdict-dir and is refused — never silently ignored — without them. Determinism, precisely: ranking order rests on the total order (-round(score, 9), id); the BLAS thread pins set before numpy is imported (VECLIB_MAXIMUM_THREADS for Accelerate, OPENBLAS/MKL/OMP for other backends) defend the narrower claim that vector artifacts are byte-identical across environments. Ships an optional, rebuildable vectors.npy + vectors.jsonl store (byte-identical regardless of insertion order; fail-fast on a row/line mismatch; missing loads as None) — an authoring primitive with no caller in src/, offered to extenders like write_verdict and promote_verdict. numpy is confined to semretrieval.py and never enters okf.py, retrieval.py or shared/.
• Azure/Foundry offline preflight config gate (preflight.py, S4.1).
• Offline live-dry-run drill (--live-dry-run, S4.2): walks the whole path up to the eager client build and stops before the first model call — zero chat calls.
• Out-of-band HITL verdict routing CLI (hitl.py, S5.1): code-prefix routing on the candidate id.
• Expert-notification contract (notify.py, S5.2): the declared Notifier with ConsoleNotifier, FileNotifier (byte-deterministic JSONL), and WebhookNotifier, plus a fail-fast build_notifier; the webhook is the only egress point, fail-closed behind an explicit per-run allow_egress opt-in. Not auto-wired into run.py.
• docs/knowledge-base-recipe.md (S5.3, D-H item 1): the documented team process (technical + domain expert) for building a knowledge base, with the honest 1–2 week expectation.
• Test suite: 512 passing tests (4 skips are live-provider-only). Every wired seam is covered by a load-bearing test that goes red when the seam is detached — including, since the S3.1 review remediation, the --semantic-retrieval wiring at main() level. That claim did not hold for S3.1 as first shipped: the flag was covered only below the CLI, so hardcoding it off left the suite green. Each remediated seam now carries a recorded detach point, verified by mutation.

Notes

• Licensed under the MIT License (see LICENSE).