design(app-creator): S13 — review-gate mellom faser (friksjon #15) + retroaktiv anvendelse

Operatør avslørte i S13 at app-creator-pipelinen mangler review-gate mellom faser.
Implementér mønsteret som spec + førstegangs-anvendelse på Akashic-prototypen.

phase-design-draft.md:
- Ny § Cross-cutting: Review-gate mellom faser (mellom state.json og brief-revisjon
  ved backtracking) — sidecar-format, annoterings-vokabular (approved/revise/defer/
  drop/question), applisering med revisjons-logg, oppstrøms-konsekvens-håndtering
  (backtrack vs revision-pending), nedstrøms for fase 7 (drop→slett mappa, revise→
  bump rev, defer→flytt), retroaktiv review, attention-entry-type, frekvens-regel
  (obligatorisk), all-approved-shortkutt, forhold til status-merking.
- phase_status-vokabular utvidet med pending-review | revision-in-progress
- state.json-eksempelet viser ny objekt-form med sidecar-peker
- § Brief-pattern fikk peker til review-gate som hard krav

friksjon.md:
- #15: Fase-til-fase går uten review-gate (prosess-friksjon, kritisk)
- Beskriver problemet, hva som mangler, 5 strukturelle krav, S13-handling,
  lærdom, anvendelse på allerede-fullførte faser, foreslått revisjon, drahjelp
  fra Voyage /trekrevise-mønster, fase-overhead-implikasjon.
- S13-bekreftelse på eksisterende friksjon + prosess-merknader (operatør-
  pedagogisk friksjon, omdefinert sesjons-omfang).

Akashic-side (separat repo): review-maler 06-features-brief.review.md +
features/01-sun-position/review.md, interim index.html, state.json oppdatert.
Committet i Akashic-repo separat (denne committen påvirker ikke ren instans).

Neste sesjon (S14): applisere review-annoteringer som revisjon 1, propagere
oppstrøms-konsekvenser, re-generere index.html, fortsette fase 7 hvis godkjent.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-05-14 07:09:39 +02:00
commit d66810a370
2 changed files with 179 additions and 2 deletions

View file

@ -55,6 +55,8 @@ Hver fase produserer én eller flere **briefer** — strukturerte markdown-dokum
Konsistensen gir én HTML-renderer, lik review-UX, og enkel kryss-referansing. Fase-spesifikk struktur lever inni hver brief, ikke som forskjellige format på tvers.
**Hver brief har en obligatorisk review-gate før neste fase starter** (se § Cross-cutting: Review-gate mellom faser). Brief-en er AI-skrevet; godkjenning gjøres via sidecar-fil `<artefakt>.review.md` med annoteringer per anker. `phase_status` skiller mellom `pending-review` (AI-skrevet, venter på operatør) og `complete` (operatør-godkjent). Neste fase blokkert til `complete`.
## Hard lengde-grense per artefakt (R7)
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.
@ -898,7 +900,7 @@ Hvis operatøren reviewer en `brief.md` og vil annotere før handover: bruk Voya
"3": "complete",
"4": { "status": "skipped", "reason": "early stage, ingen andre brukere — trigges på bruk hvis det blir behov" },
"5": "complete",
"6": "in-progress",
"6": { "status": "pending-review", "revision": 0, "sidecar": "06-features-brief.review.md", "blocking": [7] },
"7": "not-started"
},
"briefs": {
@ -921,6 +923,7 @@ Hvis operatøren reviewer en `brief.md` og vil annotere før handover: bruk Voya
]
},
"attention": [
{ "type": "review-pending", "phase": 6, "description": "06-features-brief.md venter på operatør-review per § Cross-cutting: Review-gate.", "ref": "06-features-brief.review.md" },
{ "type": "decision", "phase": 6, "description": "F-007 har ingen prioritet satt", "ref": "06-features-brief.md#F-007" },
{ "type": "review", "phase": 7, "description": "Voyage returnerte plan for F-002, venter på review", "ref": "features/02-onboarding/voyage_run.md" }
],
@ -928,7 +931,131 @@ Hvis operatøren reviewer en `brief.md` og vil annotere før handover: bruk Voya
}
```
`phase_status`-verdier er enten en string (`complete | in-progress | not-started | revised`) eller et objekt `{ "status": "skipped", "reason": "..." }` for skippede faser. `domain_pack` er `null` hvis ingen pack brukes. `session` er det lette flersesjons-feltet (ikke en innebygd orkestrator). Dette er filen app-factory leser for portefølje-aggregering.
`phase_status`-verdier er enten en string (`complete | in-progress | not-started | revised | pending-review | revision-in-progress`) eller et objekt med utvidet form. Skippede faser: `{ "status": "skipped", "reason": "..." }`. Review-gate-pending: `{ "status": "pending-review", "revision": 0, "sidecar": "<filsti>", "blocking": [<faser]> }` (se § Cross-cutting: Review-gate mellom faser). `domain_pack` er `null` hvis ingen pack brukes. `session` er det lette flersesjons-feltet (ikke en innebygd orkestrator). Dette er filen app-factory leser for portefølje-aggregering.
## Cross-cutting: Review-gate mellom faser `[justert 2026-05-13 — friksjon #15]`
Etter at en fase produserer sin brief (eller fase 7 sine feature-artefakter) er artefakten **AI-skrevet, ikke operatør-godkjent**. Neste fase kan ikke starte før operatør har gått gjennom artefakten og signert av. Mønsteret er strukturelt analogt med Voyages `/trekrevise` (Handover 8 — operatør-annotert brief/plan/review back into source artifact).
### Hvorfor
Pipelinen er operatør-styrt syntese, ikke autonom AI-prosessering. Hvis fase n+1 bygger på u-validert fase n-output, akkumulerer alle nedstrøms-artefakter feilantakelser. Friksjon #15 (Akashic S13) oppstod nettopp slik: S11 skrev features-brief med 13 features, S12 startet fase 7 på toppen, S13 stoppet med "F-006 ville jeg ikke godkjent" — F-001-brief (S12) var allerede bygget på u-validert backlog. `phase_status: "complete"` betydde "AI-skrevet", ikke "operatør-godkjent". Forskjellen er kritisk og må reflekteres i status-vokabularet.
### Sidecar-format
Operatør annoterer i en sidecar-fil ved siden av hovedartefakten:
| Fase | Hovedartefakt | Review-sidecar |
|------|---------------|----------------|
| 1 | `01-app-brief.md` | `01-app-brief.review.md` |
| 2 | `02-research-briefs/<NN>-*.md` | `02-research-briefs/<NN>-*.review.md` |
| 3 | `03-architecture-brief.md` | `03-architecture-brief.review.md` |
| 4 | `04-design-brief.md` | `04-design-brief.review.md` |
| 5 | `05-constraints-brief.md` | `05-constraints-brief.review.md` |
| 6 | `06-features-brief.md` | `06-features-brief.review.md` |
| 7 | `features/<NN>-<slug>/brief.md` + `context.md` | `features/<NN>-<slug>/review.md` |
Sidecar-fila committes sammen med revisjonen den driver (audit trail). Etter applisering kan sidecaren beholdes (audit) eller arkiveres til `archive/`-undermappe — operatør-valg.
### Annoterings-vokabular
Fast vokabular per anker-element (per feature, ADR, constraint, success-kriterium, …):
| Status | Betydning | Krever |
|--------|-----------|--------|
| `approved` | Anker beholdes uendret. | — |
| `revise` | Anker beholdes, men endres. | `reason` + `changes`-liste |
| `defer` | Anker flyttes til senere versjon (`to: v1.1+`). Fjernes fra denne revisjonen. | `reason` + `to` |
| `drop` | Anker fjernes permanent fra appen. | `reason` |
| `question` | Operatør har spørsmål; AI må svare. Driver en ekstra runde med oppdatert sidecar. | `question` (selve spørsmålet) |
### Eksempel-entry (fase 6 sidecar)
```markdown
### F-006 daily-why
status: drop
reason: Kuratert daglig YouTube-lenke føles som tvunget innhold, ikke organisk praksis-støtte. Trenger ny vinkling som ikke binder appen til Sadhguru-kilder.
```
```markdown
### F-002 notifications
status: revise
reason: `.timeSensitive`-entitlement-søknad er overkill for v1 — start med `.active` og oppgrader hvis funksjonen viser seg viktig.
changes:
- Drop `.timeSensitive`-entitlement-søknad fra v1.
- Sett `.active` som default; nevn `.timeSensitive` som v1.1+-kandidat.
- Constraints-brief § `.timeSensitive`-entitlement skal også re-revideres (revision-pending).
```
```markdown
### F-001 sun-position
status: approved
```
### Applisering
AI leser sidecar-fila, bumper hovedartefaktens `revision` (`0``1`), oppdaterer `last_modified`, og applisere endringer per anker. Endringer logges som ny § "Revisjons-logg" i hovedartefakten:
```markdown
## Revisjons-logg
### Revision 1 (2026-05-13, driver: 06-features-brief.review.md)
- F-006 daily-why: DROPPET. Begrunnelse: <fra sidecar>. Konsekvens oppstrøms: app-brief § Omfang #6 må re-revideres (revision-pending).
- F-002 notifications: REVIDERT. Drop `.timeSensitive`. Konsekvens oppstrøms: constraints-brief § `.timeSensitive`-entitlement må re-revideres.
- F-001..F-005, F-007, F-008, F-010, F-011, F-T01..F-T03: GODKJENT som-er.
```
Etter applisering: AI committer hovedartefakt-revisjonen + sidecar-fila samlet. Hvis ytterligere runde trengs: ny sidecar med suffix (`06-features-brief.review-2.md`), bumper til `revision: 2`.
### Konsekvens-håndtering oppstrøms
Hvis fase n-review avslører at fase n-1 må endres (f.eks. F-006-drop i fase 6 avslører at app-brief § Omfang #6 må re-revideres): operatør får eksplisitt valg i AI-tilbakemeldingen:
- **(a) Backtrack til fase n-1.** Bump n-1 til `revised`, propagér gjennom mellomliggende faser per § Cross-cutting: brief-revisjon ved backtracking.
- **(b) Registrer som `revision-pending` der.** Lavt-prioritet-flagging — ingen umiddelbar backtrack, men n-1-brief markeres for re-revision ved neste touch.
### Konsekvens-håndtering nedstrøms (fase 7)
Hvis review av fase 6 endrer eller dropper en feature som fase 7 allerede har skrevet brief.md for: nedstrøms-konsekvens er **destruktiv**.
- **`drop`** av feature med eksisterende `features/<NN>-<slug>/`: AI sletter mappen + bumper `feature_summary.brief_written` ned. Hvis Voyage allerede kjører på den: sett `voyage_run_status` til `obsolete`.
- **`revise`** av feature med eksisterende brief.md: bump brief.md `revision` og oppdater per `changes`-liste; sett `voyage_run_status` til `stale` hvis Voyage kjører.
- **`defer`** av feature med eksisterende brief.md: flytt mappen til `deferred/v1.1/<NN>-<slug>/`; sett `voyage_run_status` til `deferred`.
### Retroaktiv review
Hvis pipelinen har kjørt uten review-gate (som Akashic gjorde frem til S12): operatør kan kjøre retroaktiv review per fase. Sidecar-fila skrives mot eksisterende artefakt; applisering bumper revisjon fra `0``1`. Hvis retroaktiv review avslører at flere oppstrøms-faser også må revideres: backtracking-mekanikk § Cross-cutting: brief-revisjon ved backtracking håndterer propagering.
### Attention-entry
`state.json.attention[]` får ny type `review-pending`:
```json
{
"type": "review-pending",
"phase": 6,
"description": "06-features-brief.md venter på operatør-review. Annotér 06-features-brief.review.md per § Cross-cutting: Review-gate.",
"ref": "06-features-brief.review.md"
}
```
Attention-entry fjernes når sidecar applisert + `phase_status``complete`.
### Frekvens og lett anvendelse
Review-gate er **obligatorisk** mellom hver fase. Det er ikke valgfri "kvalitetskontroll" — uten review-gate kan operatør ikke kalibrere AI-output mot egen intuisjon, og pipelinen sklir mot "AI-skrevet → AI-konsumert" hvor operatør blir gummi-stempler.
For minimal-friksjon-faser (kort app-brief, ren research-brief uten kontroversielle funn) kan sidecar bestå av én linje:
```markdown
all-approved
```
AI applisere som tom revisjon: `phase_status``complete` uten `revision`-bump. Sidecar-fila committes som audit-spor selv ved `all-approved`.
### Forholdet til status-merking
Status-merkene fra § Status-merking (`[hypotese]`, `[testet]`, `[justert YYYY-MM-DD]`) er om **template-/spec-modenhet**. Review-gate-status er om **operatør-godkjenning av en konkret app-instans' brief**. De to er ortogonale: en fase kan ha `[testet]`-template og likevel kreve review-gate for hver kjøring.
## Cross-cutting: brief-revisjon ved backtracking `[hypotese]`