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:
parent
725113cc00
commit
d66810a370
2 changed files with 179 additions and 2 deletions
|
|
@ -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]`
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue