docs(truth): S1 truth maintenance — CHANGELOG, stack line, MCP claim, conflict semantics, 90% cut-list

Findings 4-7 from the 2026-07-02 status analysis, per the session plan (S1):
- CHANGELOG rewritten truthfully (was: 'Plan phase - no framework code yet')
- README stack line names the split GA packages, not the agent-framework meta-package
- CLAUDE.md: MCP downgraded to extension point (in-process FunctionTool is the default seam)
- Verdict conflict semantics documented as chosen (store first-write-wins per id,
  disk/wiki last-write-wins per file; full B10 taxonomy deliberately deferred)
- docs/extending.md: explicit 90%-principle cut-list (B10, B11, U12, U14, concurrent fan-out)
- .gitignore covers .trekexecute-progress-* (docs/.DS_Store was already untracked/ignored -
  the plan's git rm --cached assumption was stale; no-op)

No code behavior changed (docstring only in verdicts.py). Suite 152/4 green, mypy clean,
ruff format --check clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AaQCFnfsh3tfq1VfzdJpoi
This commit is contained in:
Kjell Tore Guttormsen 2026-07-03 00:34:56 +02:00
commit ae01127510
6 changed files with 54 additions and 5 deletions

View file

@ -51,3 +51,24 @@ Model choice is **config, not code** (B12): `src/portfolio_optimiser/data/model_
The role keys (`proposer`, `checker`, `default`) let you assign a distinct model per debate role;
`default` is the fallback when a role is unmapped.
## Bevisst ikke bygget (90 %-kuttlista)
Per the design philosophy (a ~90 % generic core with clear extension points — we do not chase
the last 10 %), the following are **deliberate cuts**, not roadmap debt. Each is extension
territory for a deployer, with the seam named:
- **B10 — full verdict-conflict taxonomy.** Chosen minimal semantics (documented in
`verdicts.py` + README): the in-memory store is first-write-wins per verdict id; the disk
layers (`write_verdict`, `promote_verdict`) are last-write-wins per file. The full taxonomy
(rejection categories + a rule for conflicting expert verdicts) is deferred until real experts
produce conflicting verdicts.
- **B11 — expert notification.** `run_project(notify=...)` is a stub seam (`run.py`): pass any
callable; no delivery mechanism (e-mail/Teams/webhook) ships with the core.
- **U12 — checkpointing / crash-survival of a run.** A run either completes or is re-run; the
async verdict inbox (step 7) is the resumable boundary, not intra-run state.
- **U14 — OpenTelemetry / observability.** Provenance stamping is the audit trail the core
ships; OTEL wiring is a deployer concern.
- **Concurrent fan-out.** `run_portfolio` iterates projects sequentially by design (fresh
per-project execution state; one threaded `VerdictStore`); parallel orchestration is left to
the deployer and would need budget-cap coordination.