portfolio-optimiser/.claude/projects/2026-07-04-i7-program-avslutning/plan.md

I7 — Program-avslutning (ingest): dokumentasjon + felles statusrapport

Plan quality: APPROVE_WITH_NOTES — plan-critic ga REVISE (73/C) pre-revisjon på 1 blocker (README real-source-overclaim); blocker + alle 2 major/4 minor adressert (se Revisions). Scope- guardian ALIGNED (0 creep). Post-revisjon utførbar.

Generated by trekplan v5.9.1 on 2026-07-04 — plan_version: 1.7

Context

Ingest-programmet (I1–I6) er levert: den framework-nøytrale spec-en i commons, file/CSV (I2/I3) og SQL (I4/I5) på begge stacker med bit-identiske golden-uttrekk, og HTTP demonstrert som extension point MAF-only mot lokal mock (I6). I7 er det planlagte avslutningssteget (sesjonsplan §I7): gjøre dokumentasjonen sannferdig og lukke programmet med én ærlig norsk statusrapport av hva som er bevist — og ikke bevist. Motivasjonen er tillit (brief Intent): rammeverket publiseres på Forgejo for alle som har MAF, og en artefakt som overselger eroderer tilliten. Bindende føring er ærlighets-regelen (målbilde §11 «Stack-mapping (ærlighets-avgrenset)» + §0). Ground-truth- utforsking avdekket at README-status er STALE («ingest specified but not yet implemented») og at en presis to-akset «live»-distinksjon må inn i rapporten (live data-kilde vs live modell-kjøring).

Architecture Diagram

graph TD
    subgraph "I7 — docs-only, MAF-repo + felles rapport"
        R[README.md<br/>fiks stale ingest-status] -->|honest status| OUT[Ingen overselgende artefakt]
        E[docs/extending.md<br/>skjerp D7-grense: CSV+SQL bygget,<br/>HTTP/MCP MAF-only + peker] -->|SC1 grep-gate| OUT
        REP[docs/rapport/2026-07-04-<br/>program-statusrapport-ingest.md<br/>NY: exec-sammendrag + bevist/ikke-bevist<br/>+ verifiseringslogg] -->|SC2/SC3| OUT
        EV[Evidens read-only:<br/>pytest/ruff/mypy MAF · D7-suite · D7 S10-live-run] -.cites.-> REP
    end
    style REP fill:#2d5,color:#000
    style EV fill:#eee,color:#000

Codebase Analysis

• Tech stack: Python ≥3.10, MAF, uv, pytest/ruff/mypy. Docs i markdown.
• Key patterns: ærlighets-avgrenset dokumentasjon (målbilde §0/§11); named markdown-lenker; norsk for leder-/forretningsdocs, engelsk for README/utviklerdocs (docs-språkregel).
• Relevant files (verifisert under utforsking):
  • README.md — Status-blokka (linje 9–13) sier «The ingest layer (real data sources) is specified but not yet implemented»; linje 90–92 sier «will materialize» (futurum). Begge STALE etter I1–I6.
  • docs/extending.md — har allerede http-familien (linje 55–101) + D7-MCP-peker (create_sdk_mcp_server, linje 92–101) fra I6. D7-grensa kan skjerpes (eksplisitt «CSV+SQL bygget; HTTP/MCP MAF-only demo, ikke shipped D7-connector»).
  • docs/rapport/2026-07-03-sammenligningsrapport.md — eksisterende stack-sammenligning (refereres, dupliseres ikke).
  • docs/plan/2026-07-03-sesjonsplan-ingest.md (§I7) + docs/plan/2026-07-03-maalbilde-ingest-lag.md (§0/§11) — kilder for scope + ærlighets-regel.
• Reusable code: ingen kode — docs-økt. Gjenbruker eksisterende rapport-mønster (sammenligningsrapporten) + verifiseringslogg-formen fra KTG-verifiseringsplikten.
• External tech (researched): ingen (brief: 0 research-topics).
• Recent git activity: I6 lukket på 72cb15f (review WARN akseptert). I1–I6-commits e4ee8bd..696f19a (CSV/SQL/HTTP + golden + load-bearing). Ren tree ved oppstart.

D7-søsken-fakta (read-only, grunner rapporten — INGEN skriving/commit der)

• /Users/ktg/repos/portfolio-optimiser-claude/README.md sier: programmets ene budsjetterte live modell-kjøring (S10) er utført + validert 2026-07-03 (linje 13, 76, 121–125), og at http-kilden er «an optional extension point, not built in [...] this repo ships no network connector and no live-source integration» (linje 114–118). D7 har CSV+SQL-connectorer (I3/I5).
• D7 har ingen docs/rapport/-mappe → bekrefter «én felles rapport her» (brief-valg).

Implementation Plan

Docs-økt: ingen tester (Test first utelatt), Verify er konkrete grep/kjør-kommandoer. TDD Iron Law gjelder produksjonskode, ikke dokumentasjon (brief Non-Goal).

Step 1: Fiks stale ingest-status i README (specified→implementert, uten overclaim)

• Files: README.md
• Changes: Oppdater Status-blokka (linje 9–13): erstatt «The ingest layer (real data sources) is specified but not yet implemented» med en formulering som skiller kapabilitet-implementert fra kjørt-mot-ekte-kilde: ingest-laget er implementert — file/CSV og SQL på begge stacker (bit-identiske golden-uttrekk fra delt spec), HTTP som MAF-only demonstrert extension point mot en lokal mock — og kun øvd mot committede fixtures/golden; ingen bundle er materialisert fra en live-kilde. Behold «no live-model run yet» for MAF-siden (fortsatt sant — offline skriptet sim). (BLOCKER-fiks, plan-critic): linje 90–92 — IKKE endre «will materialize» til et bart «materializes … today» (det ville motsi «hand-curated today» og overselge: bundelene er fortsatt hand-curated, connectorene har kun kjørt mot fixtures). Skriv i stedet en reconciled, ærlig setning: de medfølgende eksemplene er hand-curated; ingest-laget som materialiserer en bundle fra en kilde (file/CSV + SQL, HTTP som MAF-only demonstrert extension point) via et deterministisk, schema-validert manifest FØR loopen er implementert og øvd mot committede fixtures — ingen bundle er ennå materialisert fra en live-kilde. Ikke rør Karpathy/OKF-seksjonene. Ingen påstand om at D7 har HTTP/MCP. Sibling-presiseringen «file/CSV and SQL mirror the MAF stack» er valgfri — ta den KUN med hvis den ikke trigger Step 1s egen (claude).{0,40}(http|mcp)-grep (den gjør den ikke: ingen http/mcp-nærhet).
• Reuses: eksisterende Status-blockquote-stil i README.md; ærlighets-formuleringen fra docs/extending.md linje 88–90 («local mock — no live source»).
• Verify: grep -c "not yet implemented" README.md → 0; grep -c "local mock" README.md → ≥1; grep -niE '(d7|claude).{0,40}(http|mcp).{0,20}(support|støtte|built)' README.md → ingen treff som påstår D7 HTTP/MCP-støtte. Honesty-gate (major, plan-critic): grep -niE '(materializ|materialiser)[^.]{0,40}(real|live|ekte)[^.]{0,20}(source|kilde)' README.md → ingen treff som påstår materialisering fra ekte/live kilde som gjort; gjennomlesning bekrefter «no bundle … materialized from a live source»-klausulen er til stede (kapabilitet ≠ live-bruk).
• On failure: revert — git checkout -- README.md
• Checkpoint: git commit -m "docs(i7): refresh stale README ingest status — implemented (CSV+SQL both stacks, HTTP MAF-only demo)"
• Manifest:

  manifest:
    expected_paths:
      - README.md
    min_file_count: 1
    commit_message_pattern: "^docs\\(i7\\): refresh stale README ingest status"
    bash_syntax_check: []
    forbidden_paths:
      - docs/extending.md
    must_contain:
      - path: README.md
        pattern: "local mock"
  

Step 2: Skjerp D7-grensa i extending.md (CSV+SQL bygget; HTTP/MCP MAF-only + peker)

• Files: docs/extending.md
• Changes: I «D7 sibling hook»-underseksjonen (linje 92–101), gjør grensa eksplisitt per målbilde §11: D7 bygde file/CSV og SQL-connectorene (speiler I3/I5); HTTP/MCP er demonstrert KUN på MAF-siden mot lokal mock, og create_sdk_mcp_server er en dokumentert krok en deployer ville brukt — ikke en shipped D7-connector; ingen D7-HTTP-økt planlagt. Legg til «MAF-only» eksplisitt der HTTP/MCP nevnes for D7. Ikke endre http-manifest-avsnittene (linje 55–90) — de er korrekte fra I6.
• Reuses: eksisterende D7-hook-avsnitt (linje 92–101); målbilde §11-formuleringen verbatim som kilde.
• Verify: grep -c "MAF-only" docs/extending.md → ≥1; grep -niE 'D7.{0,30}(built|shipped|implement).{0,20}(http|mcp)' docs/extending.md → ingen treff som påstår D7 bygde HTTP/MCP.
• On failure: revert — git checkout -- docs/extending.md
• Checkpoint: git commit -m "docs(i7): sharpen D7 boundary in extending.md — CSV+SQL built, HTTP/MCP MAF-only"
• Manifest:

  manifest:
    expected_paths:
      - docs/extending.md
    min_file_count: 1
    commit_message_pattern: "^docs\\(i7\\): sharpen D7 boundary"
    bash_syntax_check: []
    forbidden_paths:
      - README.md
    must_contain:
      - path: docs/extending.md
        pattern: "MAF-only"
      - path: docs/extending.md
        pattern: "create_sdk_mcp_server"
  

Step 3: Skriv felles norsk program-statusrapport (hybrid, verifiseringslogg)

• Files: docs/rapport/2026-07-04-program-statusrapport-ingest.md (new file)
• Changes: Skriv rapporten på norsk i hybrid form:
  1. Executive-sammendrag (KI-seksjon/ledelse): hva ble bygget (ingest-lag på begge stacker), hva er bevist, hva gjenstår — kort, uten salgsspråk.
  2. Bevist / ikke bevist (ærlighets-regel, målbilde §11). MÅ inneholde den to-aksede «live»-distinksjonen: (a) live data-KILDE (http mot ekte endpoint) — ALDRI gjort, ingen stack; «første live kilde»-gaten ukonsumert. (b) live MODELL-kjøring (ekte LLM) — IKKE på MAF (offline skriptet sim beviser plumbing + deterministisk ryggrad, ikke levende LLM-atferd), DONE én gang på D7 (S10, budsjettert, validert 2026-07-03). Per connector: CSV+SQL bevist begge stacker (golden bit-identisk); HTTP MAF-only demo mot mock; MCP kun dokumentert krok.
  3. Verifiseringslogg: tabell der HVER påstand → kjørbar kommando ELLER fil-/commit-sitering. Kjør og fang faktisk output for: MAF-suite (uv run pytest), uv run ruff check ., uv run mypy src, SC1-grep-gaten, og D7-suite read-only i søsknet (cd /Users/ktg/repos/portfolio-optimiser-claude && uv run pytest; skill «suite rød» fra «kunne ikke kjøres offline» hvis ikke uv sync-et). Siter D7 S10-live-run fra D7s egen README (read-only). Referér sammenligningsrapport.md (ikke dupliser).
  • Ingen salgsspråk (KTG-verifiseringsplikt): unngå «fullt ut», «uten unntak». Named markdown-lenker til lokale filer.
• Reuses: rapport-mønster fra docs/rapport/2026-07-03-sammenligningsrapport.md; verifiseringslogg-formen fra KTG-global «Verifiseringsplikt».
• Verify: fila finnes; grep -c "Verifiseringslogg" docs/rapport/2026-07-04-program-statusrapport-ingest.md → ≥1; grep -ciE "ikke bevist" docs/rapport/2026-07-04-program-statusrapport-ingest.md → ≥1; grep -niE '(live)[^.]{0,40}(kilde|source|integrasjon)' docs/rapport/2026-07-04-program-statusrapport-ingest.md → hvert treff er negasjon («ingen live-kilde»), ingen påstand om live-kilde-integrasjon; gjennomlesning: 0 rader i verifiseringsloggen uten kommando/kilde. SC5 per-steg (minor): kjør og fang uv run ruff check . (exit 0) + uv run mypy src (exit 0) her, siter faktiske exit-koder i loggen (ikke bare i ende-til-ende-sjekken).
• On failure: revert — git checkout -- docs/rapport/2026-07-04-program-statusrapport-ingest.md (slett fila hvis untracked). Circuit breaker (minor, plan-critic): hvis MAF-suiten (SC4) er RØD ved evidens-innsamling — STOPP og eskaler; skriv ALDRI en rapport som påstår «grønn offline» over en rød suite. (D7 rød/ ikke-kjørbar er derimot forventet-håndtert: rapporteres som «ikke bevist» per SC6, ikke en stopp.)
• Checkpoint: git commit -m "docs(i7): program status report — bevist/ikke-bevist + verifiseringslogg (I7)"
• Manifest:

  manifest:
    expected_paths:
      - docs/rapport/2026-07-04-program-statusrapport-ingest.md
    min_file_count: 1
    commit_message_pattern: "^docs\\(i7\\): program status report"
    bash_syntax_check: []
    forbidden_paths:
      - README.md
      - docs/extending.md
      - src/portfolio_optimiser/okf.py
    must_contain:
      - path: docs/rapport/2026-07-04-program-statusrapport-ingest.md
        pattern: "Verifiseringslogg"
      - path: docs/rapport/2026-07-04-program-statusrapport-ingest.md
        pattern: "S10"
  

Alternatives Considered

Approach	Pros	Cons	Why rejected
Full 7-agent exploration-swarm	Prosess-symmetri	Analyserer Python-arkitektur irrelevant for docs; token-sløsing	/trekplan hard rule «Adaptive/Honesty» — docs-økt, målrettet utforsking i stedet
Egen D7-lokal rapport + MAF-rapport	Polyrepo-symmetri	Dupliserer «bevist»-narrativ, tråding mellom to	Operatør valgte «én felles rapport her» (brief)
Slå README+extending sammen til én commit	Færre commits	Blander to distinkte finpuss; svakere headless-revert	To steg = to rene reverts + tydeligere manifest-gate
Skriv rapport FØR docs-fiks	—	Rapporten ville sitert ustabile/stale docs	Rapport sist (Step 3): siterer ferdig-finpusset README/extending

Test Strategy

• Framework: ingen nye tester — docs-økt. Eksisterende suite er regresjonsvernet.
• Existing patterns: load-bearing-tester (I1–I6) forblir grønne; I7 rører ikke src/, okf.py eller shared/.
• New tests in this plan: 0. Verifikasjon er grep-gater + suite-grønn-sjekk (brief SC1–SC6).
• Manuell verifisering: SC1/SC3 har en menneskelig klassifiseringssteg (docs-prosa) med bundet objektiv proxy (grep + hver logg-rad har kilde) — akseptert av brief-reviewer.

Risks and Mitigations

Priority	Risk	Location	Impact	Mitigation
Medium	D7-suite ikke uv sync-et → pytest feiler av miljøgrunn	søsken-repo	«D7 rød» feilrapporteres	SC6: skill «rød» fra «kunne ikke kjøres offline» eksplisitt i rapporten
Medium	Conflate live-kilde vs live-modell-kjøring	rapport §bevist	Ærlighets-brudd (over- eller under-claim)	Eksplisitt to-akset distinksjon påkrevd i Step 3; D7 S10 sitert fra D7-README
Low	Utilsiktet endring i søsken-repo	D7	Polyrepo-grensebrudd	Hard rule: D7 er READ-ONLY; ingen commit/write der; forbidden i scope-fence
Low	README-edit rører OKF/Karpathy-prosa	README.md	Scope-drift	Step 1 Changes avgrenser eksakt til Status-blokk + linje 90–92
Low	Premiss «237/4» sitert uverifisert	rapport	Feil tall i logg	Step 3 kjører uv run pytest og fanger FAKTISK output (premiss-verifisering)

Assumptions

#	Assumption	Why unverifiable	Impact if wrong
1	D7-suiten er grønn offline (uv-synced)	Ikke kjørt ennå (execute-tid)	SC6 rapporterer «ikke bevist» framfor å fikse — dekket
2	Sammenligningsrapporten dekker stack-sammenligning	Antatt fra tittel/størrelse	Rapport må evt. si mer selv; leses i execute før referanse
3	README/extending trenger finpuss, ikke omskriving	Bekreftet: I6 la http+D7-peker	Ingen — begge filer lest, delta bekreftet

Verification

Ende-til-ende integrasjonssjekker på tvers av steg (per-steg manifest kjøres av trekexecute).

• grep -c "not yet implemented" README.md → 0 (SC1: stale-status fjernet)
• SC1-grep (a), briefens fulle scope grep -rniE '(d7|claude[- ]?sdk).{0,60}(http|mcp)' README.md docs/ → manuell klassifisering: HVERT treff er enten (i) eksplisitt «MAF-only / demonstrert extension point», (ii) ren D7-krok-peker (create_sdk_mcp_server), eller (iii) plan-/målbilde-prosa som FORBYR/negerer D7-HTTP (§11, sesjonsplan) — INGEN treff påstår D7 HTTP/MCP-støtte som bygget
• SC1-grep (b), live-source, briefens verbatim grep -rniE '(live|produksjon|production).{0,30}(kilde|source|integrasjon|integration)' README.md docs/rapport/ docs/extending.md → hvert treff er negasjon/forbud («ingen live-kilde», «no live source», «not built in»), INGEN påstand om live-kilde-integrasjon (dekker README + de to ed.-filene, ikke bare rapporten)
• test -f docs/rapport/2026-07-04-program-statusrapport-ingest.md → fila finnes med exec-sammendrag + «bevist/ikke bevist» + «Verifiseringslogg» (SC2)
• Gjennomlesning: 0 rader i verifiseringsloggen uten kjørbar kommando eller fil-/commit-sitering (SC3)
• uv run pytest → exit 0, 0 failed (uten nøkkel/nettverk) (SC4)
• uv run ruff check . exit 0 og uv run mypy src exit 0 (SC5)
• cd /Users/ktg/repos/portfolio-optimiser-claude && uv run pytest → exit 0 offline, sitert read-only, INGEN commit der (SC6)

Estimated Scope

• Files to modify: 2 (README.md, docs/extending.md)
• Files to create: 1 (docs/rapport/2026-07-04-program-statusrapport-ingest.md)
• Complexity: low (docs-økt; ingen kode, ingen nye tester; hovedrisiko = ærlighets-presisjon)

Plan Quality Score

Dimension	Weight	Score	Notes
Structural integrity	0.15	92	3 steg, ren avhengighet (1,2 → 3), ≤5 så ingen Execution Strategy
Step quality	0.20	90	Kirurgiske changes, eksakte linjer, manifest per steg
Coverage completeness	0.20	94	SC1–SC6 alle sporet til steg + Verification
Specification quality	0.15	90	Konkrete grep/kjør-kommandoer, ingen placeholders
Risk & pre-mortem	0.15	90	Live-akse-conflate + D7-miljø fanget
Headless readiness	0.10	90	On failure + Checkpoint per steg
Manifest quality	0.05	88	Gyldige manifester; innholds-absens dekkes av Verify (grep -c 0)
Weighted total	1.00	91	Grade: A

Adversarial review:

• Plan critic: REVISE (pre-revisjon 73/C) — 1 blocker, 2 major, 4 minor. Blocker (README real-source-overclaim) + alle major/minor adressert i Revisions under. Post-revisjon: blocker lukket.
• Scope guardian: ALIGNED — 0 creep, 2 minor (SC1-dekning). Adressert (Rev 3). Polyrepo-grense (D7 read-only) bekreftet respektert.

Revisions

#	Finding (severity)	Kilde	Resolution
1	README linje 90–92 «materializes today» overselger real-source, motsier «hand-curated» (blocker)	plan-critic	Step 1 Changes omskrevet: skill kapabilitet-implementert fra kjørt-mot-ekte-kilde; reconciled setning «implementert og øvd mot committede fixtures — ingen bundle materialisert fra live-kilde». Ikke bar nåtid.
2	Grep-gater dekker ikke live-bruk-overclaim-vektoren (major)	plan-critic	Step 1 Verify: ny honesty-gate-grep (materializ…real/live…source → 0) + gjennomlesnings-sjekk på «no live source»-klausul.
3	SC1 narrowet fra briefens docs/ til 3 filer; live-source-grep manglet i top-level Verification (major/minor ×3)	plan-critic + scope-guardian	Verification: begge SC1-grep gjenopprettet verbatim fra brief (hele docs/-treet + live-source over README/extending/rapport), med manuell klassifiserings-regel.
4	Step 3 Verify <fil>-placeholder ikke headless-kjørbar (minor)	plan-critic	Erstattet med literal sti i alle tre grep.
5	Ingen circuit breaker hvis MAF-suite rød ved Step 3 (minor)	plan-critic	Step 3 On failure: STOPP+eskaler hvis MAF-suite rød; aldri «grønn»-rapport over rød suite.
6	SC5 (ruff/mypy) kun ende-til-ende, ikke per-steg (minor)	plan-critic	Step 3 Verify: kjør + siter faktiske exit-koder i loggen.
7	Step 1 valgfri sibling-CSV+SQL-claim = scope-nudge (minor)	plan-critic	Step 1 Changes: markert valgfri, betinget av at den ikke trigger egen http/mcp-grep.