docs(a2): differensiert lengde-tabell + revisjonslogg-sidecar per R-07

Erstatter den flate ≤500-ords-grensen med friksjon #14-tabellen (ni artefakt-typer, target + review-flagg + driver). Den flate grensen ble brutt av samtlige åtte artefakter Akashic-prototypen produserte, hver gang av en driver som ikke var seremoni. Operatør-beslutning (A2, alternativ a + full rekkevidde): revisjons- historikk flyttes ut av kilde-artefakten til en sidecar — <artefakt>.revisions.md for fase 1-6, features/{NN}-{slug}/revisions.md for fase 7. Driver: F-001 brief.md var 4523 ord der ~740 var kontrakten Voyage skal lese; resten var norsk beslutningshistorikk som ellers overleveres til planneren. Alternativene context.md og strip-ved- handover ble vurdert og forkastet (context.md overleveres også; strip gir to versjoner av samme kontraktsfil uten drift-fangst). 04-design-brief-raden er eksplisitt merket [anslag - ikke målt]: fase 4 ble hoppet over i prototypen, så tallet er ikke empirisk som de øvrige. § Hard lengde-grense er dermed låst; header-kommentarens IKKE LÅST-liste er redusert til § Fase 7 (A5) + state.json-schema (C2). Verifisering: grep "500 ord eller én skjerm" -> 0; gjenværende 500-treff er tabellverdier + den historiske omtalen. Domain-pack-filenes egen ~500-ords-grense (domain-pack-spec.md:38) er en annen regel med annen begrunnelse og er uendret. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TrpGFqhXDifptogGrGgVPC
2026-08-10 20:59:01 +02:00 · 2026-08-10 20:59:01 +02:00 · ba0e8a6d38
commit ba0e8a6d38
parent daaadb4a15
1 changed files with 45 additions and 9 deletions
--- a/docs/phase-design-draft.md
+++ b/docs/phase-design-draft.md
@ -4,7 +4,7 @@
 <!-- Revidert: 2026-05-10 — brief-pattern: hver fase produserer én eller flere briefer med konsistent grunnstruktur -->
 <!-- Revidert: 2026-05-11 (S5) — anvendt revisjons-mandat R1–R17 fra prototype-run/research/research-brief.md: features/{NN}-{slug}/-layout, 00-context/, domain-pack-konsumering per fase, flersesjons-notat, rapid mode, skippbare faser med begrunnelse, hard lengde-grense, fase 4 trigger-på-bruk, fase 3 spørsmål-ikke-spekulasjon, manglende eierfaser, fase 5 mot standarder, fase 1-justeringer fra friksjon #1–4, status-merking. -->
 <!-- Revidert: 2026-08-10 (A1, dok-resync mot docs/review-2026-07.md) — fjernet døde premisser: v4.3 Plugin Playground merket historisk (slettet i Voyage v5.0.0); Handover 8/`trekrevise` fjernet som gjeldende mønster; annotate-/kontrakt-stier flyttet til cache-sti-regel; § Flersesjons-protokoll omskrevet til STATE.md-konvensjonen; iOS-versjonseksempler gjort domene-nøytrale; max-3-regelen redefinert (snapshot = én lasting); fase 2s pack-input strøket; `phase_status`-enum samlet i én autoritativ tabell (+ `pending-review`); § Fase 7 merket STALE (2.0-pin, omskrives i A5); «6-tema» → «8-tema». Se docs/masterplan.md § Fase A. -->
-<!-- Status: ANDREUTKAST. Revidert mot design-research, ikke ennå mot reell pipeline-kjøring forbi fase 1. Innholdet låses ikke før Akashic-prototypen er drevet videre og friksjons-loggen viser hva som faktisk fungerte. IKKE LÅST: § Fase 7 (2.0-pin, A5), § Hard lengde-grense (flat 500-ords-grense empirisk motbevist, A2), state.json-schema (C2). -->
+<!-- Status: ANDREUTKAST. Revidert mot design-research, ikke ennå mot reell pipeline-kjøring forbi fase 1. Innholdet låses ikke før Akashic-prototypen er drevet videre og friksjons-loggen viser hva som faktisk fungerte. IKKE LÅST: § Fase 7 (2.0-pin, A5), state.json-schema (C2). § Hard lengde-grense er låst 2026-08-10 (A2): differensiert tabell + revisjonslogg-sidecar. -->

 ## Hvorfor dette dokumentet finnes

@ -19,7 +19,7 @@ Design-researchen avdekket en reell spenning: prior art (threads A, B) sier "str
 1. **Minimal-men-gyldig app-brief er obligatorisk anker.** Aldri hoppbar — uten den hallusinerer AI-en nedstrøms. Men "minimal" kan bety en kort fritekst-variant (`problem-statement + åpne spørsmål`), ikke det fulle 8-tema-intervjuet med kvalitets-sjekk.
 2. **Fase 2 / 4 / 5 er skippbare med eksplisitt én-setnings-begrunnelse loggført i `state.json`** — ikke bare "valgfri", men "Hopper over designsystem fordi: early stage, ingen andre brukere."
 3. **Fase 4 (designsystem) trigges på bruk, ikke plan** — aktiveres etter at første Voyage-kjøring har produsert faktiske UI-komponenter; ellers "bruk HIG/Material direkte" via domain-pack-default.
-4. **Hard lengde-grense per fase-artefakt** (≤500 ord / én skjerm der mulig). Lengde er det sterkeste seremoni-signalet.
+4. **Hard lengde-grense per fase-artefakt** — differensiert per artefakt-type, ikke ett flatt tall (se § Hard lengde-grense). Lengde er det sterkeste seremoni-signalet.
 5. **En "rapid mode"-sti finnes**: app-konsept → minimal-men-gyldig app-brief inline → fase 7 feature-brief, uten å passere 2–6. Den fulle pipelinen er eskalering, ikke default.
 6. **Fase 3 (arkitektur) produserer åpne spørsmål som lukkes etter hvert** — ikke en decisions-log skrevet før koden finnes. ADR-formatet beholdes, men ADR-er skrives/oppdateres *idet beslutningen faktisk tas*.

@ -60,9 +60,38 @@ Konsistensen gir én HTML-renderer, lik review-UX, og enkel kryss-referansing. F

 > **Sidecar-fila finnes ikke** *(korrigert 2026-08-10 — A1/R-05, M8)*. Normativ tekst i dette dokumentet omtalte en sidecar `<artefakt>.review.md` som bærer av annotasjonene. `annotate.mjs` skriver **kun** `<input>.html`; annotasjonene lever i nettleserens **localStorage** (nøklet på absolutt filsti), og et `find` over Akashic-instansen finner null `.review.md`-filer. `sidecar`/`ref`-feltene i `state.json`-eksemplene under er derfor **planlagte, ikke realiserte** — behandle dem som en peker til artefakten som skal annoteres, ikke som en fil som eksisterer. Konsekvensen er reell: annotasjonene overlever ikke maskinbytte eller nettleser-rydding. Å gjøre annotasjons-**eksport til fil** til del av gate-protokollen er masterplan **D7** (betinget utvidelse C), operatør-beslutning — ikke besluttet her.

-## Hard lengde-grense per artefakt (R7)
+## Hard lengde-grense per artefakt (R7) `[justert 2026-08-10 — A2/R-07: flat grense erstattet av per-artefakt-tabell]`

-Hvert fase-dokument har et maksimum: **≤500 ord eller én skjerm** (det som er strengest), per artefakt. Lange artefakter er det sterkeste seremoni-signalet og spiser kontekst-budsjett nedstrøms-faser trenger. Unntak: `01-interview-transcript.md` (råform, ikke en brief — ingen grense) og `06-features-brief.md` (backlog skalerer med feature-antall — men hver feature-entry ≤8 linjer). Hvis en brief sprenger grensen: kandidat for å flytte detalj til domain-pack eller for å droppe innholdet. Lengde-overskridelse er et eksplisitt review-flagg, ikke en formalitet.
+Lengde er fortsatt det sterkeste seremoni-signalet, og lange artefakter spiser kontekst-budsjett nedstrøms-faser trenger. Men den opprinnelige **flate ≤500-ords-grensen er empirisk motbevist** — den ble brutt av samtlige åtte artefakter Akashic-prototypen produserte, hver gang av en driver som ikke var seremoni (friksjon #10/#12/#13/#14). Regelen er derfor differensiert per artefakt-type. Tallene er **observerte** lengder på bevisst-stramme artefakter, ikke ambisjoner — med ett unntak, merket i tabellen: fase 4 ble hoppet over i prototypen, så dens tall er anslått og ikke empirisk.
+
+| Artefakt | Target | Review-flagg ved | Driver (hvorfor akkurat dette tallet) |
+|----------|--------|------------------|----------------------------------------|
+| `01-app-brief.md` | ~2000 ord | >2500 | Bredde: intent + scope + feature-signaler + rabbit holes + antakelser |
+| `02-research-briefs/{NN}-*.md` | ~1500 ord | >2000 | Dybde per tema; skalerer per tema-fil, ikke samlet |
+| `03-architecture-brief.md` | ~2000 ord | >2500 | Dybde; ~250–300 ord per ADR ved 4+ ADR-er |
+| `04-design-brief.md` **[anslag — ikke målt]** | ~1200 ord | >1800 | Token-tabeller teller mildt; implementasjons-skjeletter holdes minimale. Fase 4 ble hoppet over i Akashic-prototypen — justér mot første reelle kjøring |
+| `05-constraints-brief.md` | ~3500 ord | >4500 | Bredde: ISO 25010 + WCAG 2.2 + MASVS + plattform + governance + test |
+| `06-features-brief.md` | ~3000 ord ved ~13 entries | >4000 | Skalerer **~200 ord/entry** (Voyage-handover-1-klar entry-struktur) + grafer + readiness-check |
+| `features/{NN}-{slug}/brief.md` | ~750 ord | >1000 | Voyage strict-mode: frontmatter (21 linjer) + 8 body-seksjoner inkl. falsifiserbare Success Criteria |
+| `features/{NN}-{slug}/context.md` | ~650 ord | >900 | Materialisert upstream (BMAD: embedding > linking) — agenten har ingen ambient kontekst |
+| `features/{NN}-{slug}/research.md` | ~600 ord | >800 | Research-plan langform: kandidat-tabell + kriterier + beslutnings-prosess |
+
+**Unntatt fra grense:** `01-interview-transcript.md` (råform, ikke en brief), `00-context/domain-pack-*.md` (materialisert snapshot — lengden eies av packen), `examples/*`, og **`*.revisions.md`** (audit-trail, se under).
+
+Typologien bak tallene: **bredde-faser** (1, 5, 6 — tverrsnitt av hele appen) lander ~2000–3500 ord; **dybde-faser** (2, 3 — få spørsmål, grundig besvart) ~1300–1800; **fokus-per-feature** (7) ~600–750 per fil. At fase 7 ligger lavest i absolutte tall og likevel over den gamle grensen, er ikke slapphet — det er Voyage-strict-mode-løftet som koster.
+
+Hvis et artefakt sprenger sitt review-flagg: kandidat for å flytte detalj til domain-pack, splitte ut en egen fil (slik `research.md` ble splittet fra `brief.md` i S12), eller droppe innholdet. Overskridelse er et eksplisitt review-flagg med skriftlig begrunnelse, ikke en formalitet — og ikke en automatisk feil.
+
+### Revisjonshistorikk teller ikke mot grensen — den bor i en sidecar `[besluttet 2026-08-10 — A2/R-07, operatør]`
+
+`## Revisjons-logg`-seksjonen skrives **ikke** inn i artefakten den beskriver. Hver revidert artefakt får en sidecar:
+
+- Fase 1–6: `<artefakt>.revisions.md` (f.eks. `06-features-brief.revisions.md`)
+- Fase 7: **én** `features/{NN}-{slug}/revisions.md` for hele feature-mappa (brief/context/research deler logg — de revideres i samme runde)
+
+**Begrunnelse:** revisjonshistorikk er app-creator-intern state, ikke kontrakt. Da konvensjonen var «logg på slutten av kilde-artefakten», vokste Akashics `features/01-sun-position/brief.md` til **4523 ord over seks runder** — hvorav ~740 var kontrakten Voyage skal lese og ~3800 var norsk beslutningshistorikk, inkludert forkastede alternativer. Den historikken overleveres da til Voyages planner og kan feilvekte planleggingen. Alternativene «flytt til `context.md`» og «strip ved handover» ble vurdert og forkastet: `context.md` overleveres også, og strip-varianten produserer to versjoner av samme kontraktsfil uten maskinell drift-fangst (jf. R-03).
+
+Sidecaren er ikke unntatt fordi den er uviktig, men fordi den er append-only per definisjon: å sette tak på den ville bety å slette historikk.

 ## Domain-pack-konsumering (R4 — krysshenviser til `domain-pack-spec.md`)

@ -180,6 +209,7 @@ Konservativ regel: kun det som faktisk er kjørt får `[testet]`. Per S5 har bar
 │   ├── domain-pack-{name}.md           # Snapshot av pakken appen bruker (versjon innskrevet)
 │   └── pack-overrides.md               # Escape hatch — per-app-overstyringer av pack-felt
 ├── 01-app-brief.md                     # Output fra fase 1 (minimal- eller full-variant)
+├── 01-app-brief.revisions.md           # Valgfri — audit-trail, finnes først ved revision ≥ 1
 ├── 01-interview-transcript.md          # Råform fra fase 1 — kun hvis full-variant (kontekst, ikke brief)
 ├── 02-research-briefs/                 # Skippbar — mappen finnes kun hvis brukt
 │   └── NN-{topic-slug}.md
@ -193,11 +223,13 @@ Konservativ regel: kun det som faktisk er kjørt får `[testet]`. Per S5 har bar
        ├── context.md                  # Embedder upstream (fase 1–5-utdrag + domain-pack-utdrag)
        ├── research.md                 # Valgfri — feature-spesifikk research
        ├── design-ref.md               # Valgfri — UX-sketch, token-referanser, HIG-pekere
+        ├── revisions.md                # Valgfri — audit-trail for hele mappa, finnes først ved revision ≥ 1
        └── voyage_run.md               # Valgfri — peker til Voyage-run-dir + run-status (skrevet av state-eksport)
 ```

 - `{NN}`-prefiks på feature-mapper håndhever dependency-rekkefølgen fra fase 6: lavere NN avhenger ikke av høyere NN innen samme app.
 - `brief.md` + `context.md` er obligatoriske per feature; resten kun når innhold finnes.
+- **`*.revisions.md` er audit-trail, aldri kontrakt** *(A2, 2026-08-10)*: hver revidert fase 1–6-artefakt får `<artefakt>.revisions.md` ved siden av seg; fase 7 samler én `revisions.md` per feature-mappe. Filene overleveres aldri til Voyage og teller ikke mot lengde-grensene. Er `revision: 0`, finnes de ikke.
 - En Voyage-kjøring skriver sine egne artefakter (`plan.md`, `progress.json`, `review.md`, …) i SIN `{project_dir}` = `.claude/projects/{date}-{slug}/`. app-creator linker dit via `voyage_run_dir` i `brief.md`-frontmatter og leser `progress.json`/`review.md` derfra for status-eksport — den kopierer dem ikke inn i `features/{NN}/`. (Operatøren kan velge å peke Voyages `--project` til `features/{NN}-{slug}/voyage/` — det er en operatør-beslutning, ikke noe app-creator dikterer.)
 - `{app-creator-instance-dir}`-plassering er `[åpent]` — kan være under `~/.claude/projects/`, under en konkret repo, eller egen mappe (Akashic-instansen ligger i eget repo, `/Users/ktg/repos/akashic-intelligence/` — én gyldig variant).

@ -216,7 +248,8 @@ created: 2026-05-10
 last_modified: 2026-05-10
 revision: 0                          # bumps ved backtracking
 revision_reason: null                # fylles ved revisjon
-length_words: {N}                    # ordtelling — review-flagg hvis > 500
+length_words: {N}                    # ordtelling — review-flagg mot artefaktets eget tak, se § Hard lengde-grense
+                                     # (teller IKKE sidecar-en <artefakt>.revisions.md)
 ---
 ```

@ -610,7 +643,7 @@ length_words: {N}
 3. Operatør justerer brand-spesifikke valg.
 4. AI definerer gjenbrukbare komponenter basert på det som allerede er bygget mer enn én gang.

-**Output: `04-design-brief.md`** `[hypotese]` — samme struktur som førsteutkastet (frontmatter `brief_type: design`, `base_system: hig | material | custom`, `component_count`; body: Base-system / Tokens (Farger light+dark / Typografi / Spacing / Motion) / Interaksjons-prinsipper / Komponent-bibliotek med token-bruk per komponent / Referanser), men under ≤500-ords-grensen (eller én skjerm — token-tabeller teller mildt). Eksempel-implementasjons-skjeletter holdes minimale.
+**Output: `04-design-brief.md`** `[hypotese]` — samme struktur som førsteutkastet (frontmatter `brief_type: design`, `base_system: hig | material | custom`, `component_count`; body: Base-system / Tokens (Farger light+dark / Typografi / Spacing / Motion) / Interaksjons-prinsipper / Komponent-bibliotek med token-bruk per komponent / Referanser), men innenfor artefaktets lengde-target (~1200 ord, review-flagg >1800 — token-tabeller teller mildt). Eksempel-implementasjons-skjeletter holdes minimale.

 **Transisjon:** Når brief er approvert, fase complete. Nedstrøms feature-briefer kan nå referere navngitte tokens; tidligere feature-briefer oppdateres kun ved revisjon.

@ -809,6 +842,8 @@ Før den første feature-briefen overleveres til Voyage: en lett koherens-sjekk
 5. Operatør kjører Voyage manuelt: `/trekplan --brief features/{NN}-{slug}/brief.md` (eller `--project features/{NN}-{slug}/voyage/` hvis operatøren vil ha Voyages artefakter der).
 6. AI/operatør oppdaterer F-XXX-status til `voyage-running` i features-brief; `voyage_run_dir` fylles i `brief.md`-frontmatter.

+**Lengde og revisjonshistorikk i fase 7** *(A2-beslutning 2026-08-10, operatør — full begrunnelse i § Hard lengde-grense)*: `brief.md` ~750 ord (flagg >1000), `context.md` ~650 (>900), `research.md` ~600 (>800). Revisjonshistorikk skrives i **`features/{NN}-{slug}/revisions.md`**, aldri som `## Revisjons-logg`-seksjon i `brief.md` — kontraktsfila skal bære kontrakten, ikke audit-trailen. Driveren er målt: da loggen lå i fila, vokste F-001 `brief.md` til 4523 ord der ~740 var kontrakt.
+
 ### `brief.md` — Voyage Handover-1-kontrakt `[STALE — pinnet til brief_version 2.0; omskrives i A5, testes i B1]`

 > **Verifikasjons-status (oppdatert 2026-08-10, A1):** blokken under ble verifisert mot Voyage-kildekode **2026-05-11** og er **ikke re-verifisert siden**. Gjeldende Handover 1 er **brief_version 2.2** (v5.1 innførte 2.1 med sequencing-gate; v5.5 innførte 2.2 med `framing` + `## TL;DR`). 2.0 er fortsatt *gyldig* under kontraktens N-1-vindu — en papir-gjennomgang av F-001 rev 6 mot 5.9.1-validatoren passerte, også i strict — men templaten sitter i kontraktens eget dokumenterte forsvars-hull, og kontrakten adresserer «a Tier-2 per-app producer» direkte med kravet om å emittere 2.2.
@ -994,7 +1029,7 @@ App-creator adopterer Voyage `scripts/annotate.mjs` direkte uten egen implemente

 3. **Overlevering:** operatør klikker "Copy Prompt" — den genererer strukturert markdown med alle annotasjonene gruppert per seksjon, og kopierer til clipboard.

-4. **Applisering:** operatør limer prompt-en inn i Claude i neste sesjon. AI parserer annotasjons-blokker og applisere endringer i kilde-artefakten. Bumpe `revision: N → N+1`, oppdater `last_modified`, skriv ny `## Revisjons-logg`-seksjon på slutten av artefakten.
+4. **Applisering:** operatør limer prompt-en inn i Claude i neste sesjon. AI parserer annotasjons-blokker og applisere endringer i kilde-artefakten. Bumpe `revision: N → N+1`, oppdater `last_modified`, og skriv ny revisjons-entry i **sidecaren** `<artefakt>.revisions.md` (fase 7: `features/{NN}-{slug}/revisions.md`) — ikke i artefakten selv.

 ### Vokabular (arvet fra Voyage)

@ -1026,10 +1061,11 @@ AI parserer annotasjons-prompten (Voyage-format: H2-overskrifter per seksjon, bu
 - **Fiks**: punktuell endring (typo, formulerings-trim) uten å diskutere.
 - **Spørsmål**: ikke applisere. Skriv AI-svar i annoterings-respons; trigge ny runde (operatør re-annoterer med ferdig info).

-Etter applisering: bump `revision: N → N+1`, oppdater `last_modified`, skriv `## Revisjons-logg`-seksjon på slutten av kilde-artefakten:
+Etter applisering: bump `revision: N → N+1` og oppdater `last_modified` i kilde-artefakten, og skriv revisjons-entryen i **sidecaren** — `<artefakt>.revisions.md` for fase 1–6, `features/{NN}-{slug}/revisions.md` for fase 7 *(A2-beslutning 2026-08-10; se § Hard lengde-grense for begrunnelsen)*. Kilde-artefakten får ingen `## Revisjons-logg`-seksjon. Sidecaren er append-only, nyeste entry øverst under H1-en:

 ```markdown
-## Revisjons-logg
+<!-- 06-features-brief.revisions.md — audit-trail for 06-features-brief.md. Ikke en kontrakt; overleveres aldri. -->
+# Revisjons-logg — 06-features-brief.md

 ### Revision 1 (2026-05-14, driver: operatør-annotasjoner fra 06-features-brief.html)
 - F-006 daily-why: DROPPET. Endre-annotasjon: "drop fra v1, trenger ny vinkling som ikke binder appen til Sadhguru-kilder". Konsekvens oppstrøms: app-brief § Omfang #6 må re-revideres (lagt til revision-pending).