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

docs(plan): D-B ankret, D-A#3s årsak er repo-avhengig, V1 utvidet med oppstrøms-evidens

Browse source 
Tre innkomne meldinger behandlet, alle premisser verifisert mot kilden.

amendment-underlag:
- §7.1 NY: D-B-substansen levert av portfolio-optimiser. D-B er en SCOPE-
  beslutning, ikke spec-tekst. S2.2 (mcp) + S2.3 (doc) krever kildefamilie-
  utvidelser; S2.4 trolig ingen. Den blanke raden er ikke lenger blank.
- FUNN i frossen tekst ingen har nevnt: :29-31 sier at http-typen MAY
  implementeres "via an MCP-based connector" UTEN spec-endring. Om mcp er en
  fjerde familie eller en transport under http avgjør om S2.2 er gated på oss
  i det hele tatt. Ingen stilling tatt.
- D-A#3s årsak er REPO-AVHENGIG: drift hos po-claude, målt okf.py-avvik hos
  portfolio-optimiser. Begge svarte, begge har rett om eget tre. Første utgave
  ga én universell årsak, korreksjonen ga en annen — begge for brede.

V1-underlag:
- Evidens FOR O1 tilført: oppstrøms referanseagent bruker selv
  by: reference_agent/gemini-2.5-pro. O1 er den idiomatiske, O2 det bevisste
  avviket. :29-funnet står uendret ved siden av.
- Akse-funnet empirisk bekreftet: generated: { by: human:jsmith@acme } på en
  håndskrevet fil oppstrøms → "generated finnes" kan aldri være eierskaps-
  predikat, uansett opsjon.
- §5-påstanden presisert: målt på generated ALENE. sources er blokkliste og
  bryter :158 — utenfor V1, men commons' å svare på.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XYkLsRfSBBUjULS219Fy8X
This commit is contained in:
Kjell Tore Guttormsen 2026-07-26 20:23:08 +02:00
commit e984d51a6c
2 changed files with 140 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

101
docs/plan/2026-07-25-amendment-underlag.md
View file

@ -44,9 +44,10 @@ skrive før pakken lukkes:
teller fem *D-A-punkter*. Bare tre par binder (S2.7 = D-A#1, S3.2 = D-A#4, S4.0 = D-A#2).
De to gjenstående D-A-punktene har **ingen story-etikett** oppstrøms:
- **D-A#3 (ledende `/`)** — trenger ingen amendment i det hele tatt. Frossen tekst i
commons HEAD sier allerede det punktet ber om (§3 under). Årsaken er **drift over
pull-grensen**, ikke et konformitetsavvik: teksten landet i `9801d35`, som ikke er i
konsumentens subtre. Punktet var korrekt skrevet mot den spec-en de kan se.
commons HEAD sier allerede det punktet ber om (§3 under). **Årsaken er repo-avhengig**
(begge konsumenter svarte, med hver sin — begge er sanne): drift over pull-grensen hos
`portfolio-optimiser-claude`, målt konformitetsgap i `okf.py` hos `portfolio-optimiser`.
Anbefalingen er den samme uansett hvilken som gjelder hvor.
- **D-A#5 (hovedbok-projeksjoner)** — er reell og har ingen tekst å endre (§6 under), men
mangler story-etikett. Ratifiserer operatøren «pakken» slik `portfolio-optimiser`
beskriver den, faller D-A#5 utenfor.
@ -55,8 +56,11 @@ skrive før pakken lukkes:
ratifiserbare punkter**, med D-A#3 strøket som amendment. B1 utenfor, som avtalt.
Tallet er ikke poenget — membership er.
**S2.2–2.4 (D-B)** er det ene punktet commons ikke kan ankre: substansen er aldri meldt hit
(§7 under). Ingen gjetning føres her.
**S2.2–2.4 (D-B)** var det ene punktet commons ikke kunne ankre. **Substansen kom 2026-07-26**
og er ført i §7.1: D-B er en *scope*-beslutning, ikke spec-tekst, og av de tre gatede storiene
er det S2.2 + S2.3 som krever kildefamilie-utvidelser — mens `:29-31` allerede sier at en
MCP-basert konnektor under `http` **ikke** krever spec-endring. Den motsetningen må avgjøres
før S2.2 føres opp som blokkert på oss.
---
@ -188,6 +192,26 @@ oppstrøms.**
> Lærdommen generaliserer og er derfor løftet til leseanvisningen øverst: **samme felle venter
> på ethvert punkt målt mot en bevegelig frossen tekst mens konsumentene er pinnet.**
> **Andre korreksjon, samme dag — årsaken er REPO-AVHENGIG, og begge svar er sanne.**
> `portfolio-optimiser` svarte kort etter og klassifiserte D-A#3 som **«et KONFORMITETSGAP i
> implementasjonen vår — ikke et spec-hull»**, med en konkret årsak: *«okf.py hopper over enhver
> lenke med `/`»*. Det er den motsatte klassifiseringen av den `portfolio-optimiser-claude` ga.
>
> **Ingen av dem tar feil.** De beskriver to forskjellige repo:
>
> | Repo | Har `9801d35`? | Årsak der |
> |---|---|---|
> | `portfolio-optimiser-claude` | nei (pinnet `7aa53fc`) | **drift** — regelen finnes ikke i teksten de har |
> | `portfolio-optimiser` | nei (pinnet `7aa53fc`) | **konformitetsgap** — de har målt eget avvik i `okf.py` og har det på operatørkøen som implementasjonssak |
>
> Begge konsumenter står på samme commons-commit (`7aa53fc`, bekreftet av begge uavhengig), så
> pullen er én koordinert handling, ikke en opprydding etter usynk.
>
> **Dette avsnittets egen historie er poenget:** første utgave ga én universell årsak, korreksjonen
> ga en annen universell årsak, og begge var for brede. «Årsaken til D-A#3» er ikke én ting når
> konsumentene er pinnet og har ulik implementasjonstilstand. Anbefalingen har vært uendret hele
> veien — punktet ut av pakken — og den avhenger ikke av hvilken årsak som gjelder hvor.
---
## 4. S4.0 / D-A#2 — kostbaseline-forankring (`cost-baseline.json`)
@ -308,6 +332,63 @@ Commons kan derfor ikke si hvilken seksjon det rører. **Ingen antakelse føres.
ene raden i underlaget som er blank av en grunn — og den blir stående blank til substansen
kommer. **Etterspurt oppstrøms.**
### 7.1 Substansen ER LEVERT (2026-07-26) — raden er ikke lenger blank
`portfolio-optimiser` leverte D-B-substansen på direkte forespørsel. Kilde:
`docs/plan/2026-07-10-sesjonsplan-fase2-6.md` **i deres repo, ikke commons** — gjengitt her som
mottatt, ikke verifisert av oss (vi har ikke lesetilgang til premisset, og fører det som
*rapportert*, ikke *målt*).
**D-B er en SCOPE-beslutning, ikke en spec-tekst.** Det er den avklaringen som gjør raden
meningsfull: vi lette etter hvilken seksjon den rører, og svaret er at *den selv* ikke rører
noen — den avgjør om tre andre stories gjør det. Fire delbeslutninger (`:56-62`): (1) amender
ingest-målbildet bevisst vs. nedskopér roadmap-B til mock-herding *(deres anbefaling: nedskopér
nå)*; (2) første live-kilde *(anbefaling: SQL — `read_sql` er mest herdet, read-only by
construction)*; (3) dokument-konnektor-avgrensning *(PDF via `pypdf` nå, DOCX utsatt)*;
(4) MCP-kildefamiliens nettverks-/subprosess-grant-form.
**Konsekvensen for commons — hvilke av de tre gatede storiene som faktisk krever amendment:**
| Story | Krever ingest-spec-amendment? | Hva |
|---|---|---|
| **S2.2** MCP-konnektor | **JA** — ny kildefamilie | `{type: "mcp", id, server_ref, tool}` i manifestet. `server_ref` = navn på env-var med kommando, **speiler `connection_ref`** (§4). Datainntak, ALDRI kjøresti. Ikke fjern-servere, ingen auth utover env-ref |
| **S2.3** Dokument-konnektor | **JA** — ny kildefamilie | `{type: "doc"}`. PDF→OKF-konseptfil med provenance, deterministisk mot committede fixtures |
| **S2.4** Konnektor-herding | **Trolig NEI** i nedskopert form | Timeout-parameter, feilkategorisering, beriket §8-logg (kilde/tidspunkt/radantall — aldri innhold). Retry KUN hvis D-B sier ja (default nei, av hensyn til determinisme). Inkrementell re-ingest: **ikke**, med mindre D-B amender §8 |
**Commons' observasjon, ikke et forslag:** §4 har i dag tre kildetyper (`file`, `sql`, `http`),
og §1 (`:27-31`) binder konformans til `file` + `sql` som påkrevde med `http` som eksplisitt
OPTIONAL utvidelsespunkt. To nye familier reiser derfor et spørsmål ingen av meldingene har
stilt: **blir `mcp` og `doc` påkrevde for konformans, eller valgfrie som `http`?** Svaret
avgjør om `:27-31` må skrives om i samme amendment. Vi fører ingen antakelse om hvilket.
**⚠️ Og frossen tekst sier allerede noe om MCP som ingen av meldingene har nevnt.** Ordrett,
`ingest-spec.md:29-31`:
> The `http` source type is an OPTIONAL extension point: implementing it (e.g. against a local
> mock, **or via an MCP-based connector**) does not require any change to this spec, and NOT
> implementing it does not break conformance.
Specen forutser altså eksplisitt at MCP kan være **transporten under `http`**, og sier at den
veien **ikke krever noen spec-endring**. Det gjør S2.2s premiss — «krever ingest-spec-amendment
i commons FØRST» — til noe som må avgjøres, ikke antas:
- Er `mcp` en **fjerde kildefamilie** (nytt `{type: "mcp"}`-skjema, amendment nødvendig), eller
en **transport for den eksisterende `http`-familien** (allerede dekket, ingen amendment)?
- Distinksjonen er ikke akademisk: den avgjør om S2.2 er blokkert på commons i det hele tatt.
Under den andre lesningen er S2.2 **ugated** og kan bygges nå, mot `http` + opt-in-flagget (§8).
Argumentet for at det likevel er en egen familie: en MCP-server er ikke en URL-henting, og
`server_ref` (env-var med **kommando**) er en subprosess-grant, ikke en nettverks-grant — §8s
opt-in-flagg er formulert for «network sources … and any other non-local transport», som
dekker det, men manifestets `base_url`/`credential_ref`-felter passer dårlig på en kommando.
**Vi tar ikke stilling.** Vi sier bare at `:29-31` gjør dette til et reelt valg med to
forsvarlige svar, og at det bør avgjøres før S2.2 føres opp som gated på oss.
Merk også at S2.4s «beriket ingest-logg» ligger mot §8, som allerede sier *«Source calls are
logged (which source, when, row count)»* — en berikelse innenfor de tre feltene er neppe en
tekstendring; en berikelse *utover* dem er det. Grensen går ved «aldri innhold», som deres egen
formulering allerede respekterer.
---
## 8. B1 — nav-golden-klassen (utenfor pakken, commons-eid)
@ -354,7 +435,7 @@ method-spec navngir aldri en repo-sti (`grep -c 'examples/' method-spec.md` →
| 4 | S4.0 / D-A#2 kostbaseline | method §7 `:332-333`, §7.1 `:345-346` | ekte hull | **endrer fasit hvis ubetinget** |
| 5 | S3.5 / D-F tittel-whitespace | ingest §4 `:125`, §5 `:158-161`, §6 `:194-197`, §11 `:278` | ekte, smal søm | ingen |
| 6 | D-A#5 hovedbok-projeksjoner | ingen tekst; naboer method §7.2 `:367-372`, §12 `:436-464` | **ny seksjon** | ingen direkte; §12 må utvides |
| 7 | S2.2–2.4 / D-B | ukjent | **ikke ankret** | ukjent |
| 7 | S2.2–2.4 / D-B | **ANKRET** (§7.1): S2.2 + S2.3 = nye kildefamilier §4/§1; S2.4 trolig ingen | **scope-beslutning, ikke spec-tekst** | ingen |
| 8 | B1 / D4 nav-golden | levert `b641741`; 0 spec-referanser | commons-eget, utenfor pakken | — |
Commons' rolle er uendret: vi forbereder underlaget, operatøren ratifiserer, og frossen tekst
@ -383,4 +464,10 @@ endres ikke uten den ratifiseringen.
| B1 = D4, ikke okf-eid | `~/.claude/coord/portfolio-optimiser/archive/20260725T041948Z-*` | okf: «never owned here; it is D4» |
| nav-golden levert | `git log -- examples/nav-golden-*` | `b641741`, 2026-07-21 |
| nav-golden ikke normativt referert | `grep -c 'nav-golden'` i de fem normative filene | 0 i alle fem |
| D-B ikke ankret hos commons | `grep -rn 'D-B'` | 0 treff utenfor STATE |
| D-B ikke ankret hos commons (per 07-25) | `grep -rn 'D-B'` | 0 treff utenfor STATE |
| D-B-substansen levert 07-26 | coord fra `portfolio-optimiser` | rapportert fra deres `sesjonsplan-fase2-6.md:56-62`, ikke målt av oss |
| §1 gjør `http` OPTIONAL, `file`+`sql` påkrevd | `ingest-spec.md:27-31` | ordrett sitert i §7.1 |
| …og nevner MCP som `http`-transport | `ingest-spec.md:29-31` | «or via an MCP-based connector … does not require any change to this spec» |
| §8 logger tre felter | `ingest-spec.md:230` | «which source, when, row count» |
| `connection_ref` er env-var-NAVN | `ingest-spec.md:109`, `:117` | «the NAME of a runtime-resolved …», secret resolved at run time |
| Begge konsumenter står på `7aa53fc` | coord fra begge, uavhengig | po: `git log --grep=git-subtree-split` → `ef1a2c5`; po-claude: egen måling |

51
docs/plan/2026-07-26-v1-generated-felt-okf-v0.2.md
View file

@ -68,6 +68,17 @@ oppstrøms i noen versjon — bærer fortsatt uforfalskbarhet-mot-uhell, så ste
ikke. Men `:82`s «permitting either field alone» må omformuleres: under v0.2 vil *kurert*
innhold legitimt kunne bære en `generated`-mapping med en helt annen `by`.
> **Empirisk bekreftet 2026-07-26, ikke lenger bare utledet.** Oppstrøms skriver `generated` på
> **håndskrevet** innhold. Verifisert her:
> `generated: { by: human:jsmith@acme, at: 2024-01-15T10:00:00Z }`
> (`okf/bundles/acme_retail/metrics/gross-margin-legacy.md`, en menneskeskrevet metrikkdefinisjon).
>
> **Konsekvensen gjelder uansett hvilken opsjon som vedtas:** en implementasjon som utleder «er
> dette maskingenerert?» eller «eier vi denne fila?» fra at `generated` **finnes**, er feil under
> v0.2. Under O1/O2 må predikatet derfor være `generated.by == <vår aktør>` **og**
> `ingest_manifest` — aldri nøkkelens tilstedeværelse. Under O0 og O3 er poenget uten virkning,
> siden markøren vår da ikke deler navn med et oppstrømsfelt som brukes slik.
## 4. Spørsmålet
> Skal `generated` i ingest-spec §5/§7 forbli den literale `true`, anta v0.2-formen
@ -79,11 +90,26 @@ innhold legitimt kunne bære en `generated`-mapping med en helt annen `by`.
Kostnad er talt som **kontraktslinjer som må skrives om** av de 7 (`:34`, `:70`, `:82`, `:152`,
`:214`, `:275`, `:309`).
**Det som ikke koster noe i noen opsjon:** §5s formkrav overlever uendret. Prefikset er «OKF
line-oriented `key: value`» (`:150`) og «All values MUST be single-line» (`:158`) — v0.2s
kanoniske form for `generated` er en **inline flow mapping** på én linje, så den er single-line
og line-oriented allerede. `:153` («additional frontmatter keys MAY follow») er heller ikke i
veien. Ingen opsjon tvinger fram en rikere frontmatter-modell i *specen*.
**Det som ikke koster noe i noen opsjon:** §5s formkrav overlever uendret **for `generated`**.
Prefikset er «OKF line-oriented `key: value`» (`:150`) og «All values MUST be single-line»
(`:158`) — v0.2s kanoniske form for `generated` er en **inline flow mapping** på én linje, så den
er single-line og line-oriented allerede (verifisert oppstrøms:
`generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-30T14:00:00Z }`). `:153`
(«additional frontmatter keys MAY follow») er heller ikke i veien. Ingen opsjon tvinger fram en
rikere frontmatter-modell i *specen*.
> **Presisering 2026-07-26** (`llm-ingestion-okf`): setningen over er målt på `generated` **alene**,
> og skal ikke leses som at `:158` overlever v0.2 i sin helhet. Det gjør den ikke. `sources` —
> et annet nytt v0.2-felt — er kanonisk en **blokkliste**, verifisert oppstrøms:
> ```yaml
> sources:
> - id: margin-standard
> resource: policies/margin-standard.md
> author: human:jsmith@acme
> ```
> Den formen bryter `:158` direkte. Det er **utenfor V1**, som bare gjelder `generated`, og
> DEFAULT-profilen emitterer ikke `sources` — men det er et reelt §5-spørsmål den dagen noen vil
> emittere v0.2s øvrige felter, og det er commons' å svare på. Ikke i køen, ikke meldt videre.
### O0 — la `generated: true` stå, dokumentér avviket
@ -106,6 +132,17 @@ og overlever.
**Denne opsjonen kolliderer med en eksisterende normativ setning — se §6.** Kostnaden er ikke
bare fikstur-regenerering.
> **Evidens FOR O1, tilført 2026-07-26.** `llm-ingestion-okf` korrigerte sin egen anbefaling da de
> hadde lest oppstrøms' *bundles* og ikke bare SPEC.md: **oppstrøms referanseimplementasjon bruker
> selv produsent/versjon-formen.** Verifisert her, uavhengig:
> `generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-30T14:00:00Z }`
> (`okf/bundles/acme_retail/metrics/gross-margin.md`). `<produsent>/<versjon>` er altså ikke en
> avvikende lesning av §7 — det er den **kanoniske formen for et verktøy**, brukt av spec-eieren.
> O1 er dermed den v0.2-*idiomatiske* opsjonen, og O2 er det bevisste avviket fra idiomet.
> Funnet i §6 står uendret ved siden av dette: oppstrøms' bundles er utdata fra én agent, ikke
> delte konformansfiksturer, så de to fakta er ikke i motstrid. **Det er nettopp byttet
> operatøren skal ta stilling til:** v0.2-idiomatikk mot reproduserbar delt fasit.
**Reverserbar.** Nei — frossen normativ tekst.
### O2 — v0.2-form med produsent-nøytral aktør
@ -251,5 +288,9 @@ line-oriented-krav, og `ingest_manifest` som stempelets andre halvdel. Ingen ops
| To disjunkte fasitsett finnes | `comm -12` over begge trærs `expected-bundle/*.md` | kun `index.md`-navn felles |
| …og de felles `index.md` er ulike | `cmp` på `ingest-golden-file/.../index.md` | ULIKE |
| §1 sier «**the shared** golden extractions» | `ingest-spec.md:29` | bestemt form, én mengde forutsatt |
| Oppstrøms bruker selv `<produsent>/<versjon>` | `okf/bundles/acme_retail/metrics/gross-margin.md` | `by: reference_agent/gemini-2.5-pro` |
| Oppstrøms skriver `generated` på HÅNDSKREVET fil | `…/gross-margin-legacy.md` | `by: human:jsmith@acme` |
| `sources` er blokkliste, ikke inline flow | samme fil, `sources:` | `- id:` + 4 nøkler, flerlinjes → bryter `:158` |
| SPEC.md er endret ETTER v0.2-migreringen | okf-melding, deres pin `3fcbb9f` | «v0.2-commiten» ≠ «dagens spec-tekst» — uverifisert av oss |
| `ingested_at` har ingen wall-clock-default | `ingest-spec.md:141` | «there is NO wall-clock default» |
| Spec-tekst uendret siden 07-21 | `git log --oneline -- ingest-spec.md` | `bfa5a9b`, forrige `7aa53fc` — ingen commit etter |