# Phase-design-utkast: app-creators pipeline ## Hvorfor dette dokumentet finnes Den manuelle iOS-prototypen (Akashic Intelligence) trenger et startpunkt. Uten skisse av faser, artefakter og transisjoner blir hver fase ad-hoc improvisert, og friksjons-loggen mister konsistens på tvers av sesjoner. Dette dokumentet er **arbeidshypoteser**, ikke spesifikasjon. Hver brief-template her er et utgangspunkt prototypen skal stress-teste. Andreutkastet (S5) er revidert mot design-research (threads A–E, syntetisert i `prototype-run/research/research-brief.md`) — men kun fase 1 har faktisk friksjons-belegg fra Akashic-kjøringen. Resten er fortsatt hypotese. ## Den sentrale design-spenningen (S5-stillingstaken) Design-researchen avdekket en reell spenning: prior art (threads A, B) sier "strukturen er riktig — fyll gapene"; den contrarian tråden (E) sier "default-retningen er feil — for en solo-dev som bygger en liten app for seg selv er fem av syv faser spekulativ infrastruktur, brief-first ikke full-pipeline-first." S5-stillingstaken (operatør kan overstyre): 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** — 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*. Konsekvensen: pipelinen presenteres heretter som **eskalerings-stige**, ikke som standard-løype. Default er kort. Hver ekstra fase er et bevisst valg med begrunnelse. ## Scope-lås app-creator dekker **utviklings-prosessen** — fra app-konsept til app-bygget (feature-briefer overlevert til Voyage). Eksplisitt utenfor scope: - **Pre-decision:** markedsanalyse, business case, om appen i det hele tatt skal lages. - **Post-shipping:** TestFlight-feedback-loops, marketing, App Store-optimization (ASO), reell-bruk-analyse av shipped app. ### Release/ops-grensen (R10 — gjort eksplisitt) Mellom "app-bygget" og "post-shipping" ligger en gråsone. Grensen: - **App-brief (fase 1) eier de release-beslutningene som er reelle scope-valg:** distribusjons-modell (paid app / freemium / gratis), om det er en bevisst versjonerings-strategi, om appen har analytics-stack i det hele tatt (ja/nei + hvilken type — ikke konfigurasjon). Disse påvirker arkitektur og features, så de hører i app-rammen. - **Domain-pack-checklists eier de operasjonelle submission-artefaktene:** App Store-submission-checklist, `NSUsageDescription`-inventar, privacy-manifest-mal, eksport-compliance-spørsmål, region-krav, screenshot-spec, App Store Connect-metadata-mal. En `ios-app`-pack bærer disse; appen gjenoppfinner dem ikke. Se `domain-pack-spec.md`. - **Eksplisitt utenfor app-creator:** force-upgrade-policy-implementasjon, TestFlight-loops, ASO, marketing, analytics-dashboard-oppsett, reell retention-analyse. Brief-templater i dette utkastet skal ikke utvides for å dekke disse. Test-strategi: ikke en dedikert fase. Test-*infrastruktur* er features i backlogen (fase 6 — se `F-T`-konvensjonen); test-*strategi-beslutninger* (dekningsmål, crash-free-rate, device/OS-matrise) hører som constraints i fase 5, strukturert mot domain-pack-checklisten — ikke som egen fase. ## Brief-pattern som unifisert artefakt-form Hver fase produserer én eller flere **briefer** — strukturerte markdown-dokumenter med YAML-frontmatter og fase-spesifikt innhold i seksjoner: - **App brief** (fase 1) — én per app. Minimal-variant eller full-variant. - **Research briefs** (fase 2, skippbar) — én per research-tema. - **Arkitektur brief** (fase 3, skippbar for trivielle apper) — én per app. - **Design brief** (fase 4, trigges på bruk) — én per app. - **Constraints brief** (fase 5, skippbar) — én per app. - **Features brief** (fase 6) — én per app (backlog + dependency-graf). - **Feature-artefakter** (fase 7) — `brief.md` (Voyage-kompatibel) + `context.md` (embedder upstream) per feature. 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 ved at operatøren annoterer artefaktens `annotate.mjs`-genererte HTML og leverer annotasjonene tilbake via «Copy Prompt». `phase_status` skiller mellom `pending-review` (AI-skrevet, venter på operatør) og `complete` (operatør-godkjent). Neste fase blokkert til `complete`. > **Sidecar-fila finnes ikke** *(korrigert 2026-08-10 — A1/R-05, M8)*. Normativ tekst i dette dokumentet omtalte en sidecar `.review.md` som bærer av annotasjonene. `annotate.mjs` skriver **kun** `.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) `[justert 2026-08-10 — A2/R-07: flat grense erstattet av per-artefakt-tabell]` 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: `.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`) En **domain pack** er en gjenbrukbar kunnskaps-bunt (conventions, patterns, gotchas, checklists, guardrails, scaffolding, reference-impl, glossary) som fasene 1/3–7 konsumerer for å realisere en app i et bestemt domene. Den ligger mellom app-spesifikk (fase 3–5) og task-spesifikk (fase 7). app-creator shipper referanse-pakker (`ios-app`, `claude-code-plugin`) i `domain-packs/` i plugin-roten; fork-and-own-brukere lager egne. Full spec: `domain-pack-spec.md`. **Lasting:** eksplisitt fil-sti per fase — ingen always-on injeksjon, ingen glob-magi. **Max-3-regel** *(redefinert 2026-08-10, A1 — R-15)*: regelen beskytter kontekstbudsjettet, ikke filtellingen. **`00-context/`-snapshotet teller som ÉN lasting** (det er én fil, uansett hvor mange pack-komponenter det bærer); utover snapshotet laster en fase maks **3 supplementary pack-filer** ved oppstart. Den gamle formuleringen («aldri mer enn 3 pack-filer») var både brutt på papir (fase 5 krever 3 checklists + `gotchas.md`) og omgått i praksis (Akashic leste snapshotet med alle fem core-filene gjennom ett filhandle) — den målte antall filhandles, ikke kontekst. Hver fase-seksjon under lister hvilke pack-filer den `Read`-er. `state.json` registrerer `domain_pack: "ios-app@0.1.0"`; app-artefaktenes frontmatter skriver samme verdi. Ved init av appen materialiseres et **snapshot** av pakken (versjonen appen bruker) inn i `00-context/`; ethvert pack-felt kan overrides per-app via `00-context/pack-overrides.md`. | Fase | Pack-filer den typisk `Read`-er | |------|----------------------------------| | 1 (intervju) | `conventions.md` (domene-rammer som farger spørsmålene), `glossary.md` (valgfri, ved behov) | | 3 (arkitektur) | `conventions.md`, `patterns/{relevant}.md` (max 1–2), evt. `gotchas.md` | | 4 (designsystem) | `conventions.md` (HIG/Material-default), `patterns/{ui-relevant}.md` | | 5 (constraints) | `00-context/`-snapshotet (bærer alle `checklist*.md` + `gotchas.md`; App Store / MASVS / WCAG / privacy-manifest). Uten snapshot: checklist-filene + `gotchas.md` — se max-3-regelen over | | 6 (feature-derivasjon) | `checklist.md` (for å identifisere test-infra-features), `examples/` (eksempel-backlog, valgfri) | | 7 (feature-brief) | `checklist.md` (brief-validerings-items), `examples/` (eksempel-feature-brief), `scaffold/` (når artefakter materialiseres) | ## Flersesjons-protokoll (R3) Å drive en reell app gjennom pipelinen tar mange sesjoner — kontekstvindu-grenser, naturlige pauser, research-avstikkere. Design-research (thread A: BMAD Discussion #74 / Issue #1343 — agent-kontekst degraderer etter 3–4 runder; store mellomdokumenter spiser budsjettet) bekrefter at dette er hard teknisk nødvendighet, ikke pynt. **Mønsteret** *(omskrevet 2026-08-10, A1 — R-09; erstatter det opprinnelige `SESSION-ROADMAP`/`NEXT-SESSION-PROMPT`/`SESSION-LOG`-mønsteret)*: - **Én `STATE.md` per app-creator-instans**, i instans-repoets rot. Den bærer current state-of-play og starter ALLTID med en «👉 NESTE — START HER»-blokk øverst: hvor vi er, neste konkrete steg, og pekere til det som må leses. Den **overskrives** ved hver sesjonsslutt (maks ~60 linjer) — historikk går til git, ikke til fila. - **`git log` er langtidsloggen.** Ingen egen sesjons-logg-fil. - **Sesjonskøen bor ved siden av staten** (i app-creator selv: `docs/masterplan.md`; i en instans: backlogen i `06-features-brief.md` + `state.json`). - Operatør kjører `/clear` eller starter ny sesjon; re-entry er STATE.md-ens NESTE-blokk, som injiseres automatisk. Ingen «les og følg X nøyaktig»-prompt skrives. - Faser som produserer store mellomdokumenter (arkitektur, design-tokens, full backlog) MÅ kunne kjøres i egen sesjon. - Domain-packs lastes selektivt (max-3-regelen over) for å holde nedstrøms-budsjett ledig. **Hvorfor omskrivingen:** det opprinnelige tre-fils-mønsteret var improvisert i prototype-runet (friksjon #6/S5) og er siden avviklet i praksis — filene finnes ikke på disk, og operatørens globale konvensjon forbyr eksplisitt lokale kontinuitets-/handover-mekanismer av den typen. Strekker de globale lagene (`STATE.md` + auto-memory + `CLAUDE.md` + git) ikke til, utvides de **globalt**, aldri lokalt i en app-creator-instans. **Lett `state.json`-felt** (maskinlesbart speil, ikke egen mekanikk): `session.current` (kort tag), `session.next_action` (én linje), `session.log` (liste av korte sesjons-noter). Dette er det app-factory leser for «hvor i prosessen er appen, hva er neste handling» — `STATE.md` er menneske-flaten, `state.json.session` er maskin-flaten, og de skal si det samme. **Beslutning (S5, opprettholdt):** ingen innebygd orkestrator (à la Voyages `trekcontinue`/`trekendsession`) før behovet er bevist (YAGNI, thread E). ## Status-merking Hver brief-skisse er merket med ett av: - **`[hypotese]`** — utkast basert på pre-design-resonering, ikke testet. - **`[arvet]`** — direkte hentet fra Voyage eller annen kjent kilde, lavere endrings-sannsynlighet. - **`[åpent]`** — bevisst uavklart inntil prototypen viser hvordan. - **`[testet]`** — overlevd reell pipeline-kjøring. - **`[justert YYYY-MM-DD]`** — endret basert på friksjons-belegg; dato + kort begrunnelse. Konservativ regel: kun det som faktisk er kjørt får `[testet]`. Per S5 har bare fase 1 friksjons-belegg (Akashic-kjøringen, friksjon #1–4); cross-cutting-revisjonene er `[justert 2026-05-11]` der research ga belegg, ellers `[hypotese]`. ## Workflow-oversikt (eskalerings-stige) ``` ┌─────────────────────────────────┐ │ Pre-pipeline: init (identitet) │ app.md (slug, navn, plattform, dato) └─────────────────────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ 1. Intervju → app brief │ default: minimal-variant │ (minimal | full) │ opt-in: full 8-tema-intervju └─────────────────────────────────┘ │ │ rapid mode │ │ full pipeline (eskalering) ▼ ▼ ┌───────────────────┐ ┌─────────────────────────────────┐ │ 7. feature-brief │ │ 2. Research → research briefer │ SKIPPBAR (begrunnelse i state.json) │ (uten 2–6) │ └─────────────────────────────────┘ └───────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ 3. Arkitektur → arkitektur brief│ SKIPPBAR for trivielle apper │ (åpne spørsmål → ADR ved valg)│ └─────────────────────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ 5. Constraints → constraints br.│ SKIPPBAR (bæres av domain-pack-checklists) │ (mot ISO 25010 / WCAG 2.2 / │ │ MASVS 2.1 / privacy manifest) │ └─────────────────────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ 6. Feature-derivasjon → features│ │ brief (backlog + deps) │ └─────────────────────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ [readiness check: PASS/CONCERNS/│ │ FAIL — koherens fase 1–6] │ └─────────────────────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ 7. Feature-briefer (per feature)│ brief.md + context.md │ → handover til Voyage (filer) │ Voyage strict-mode-kompatibel └─────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────────┐ │ 4. Designsystem → design brief — TRIGGES PÅ BRUK, ikke plan. │ │ Aktiveres etter første Voyage-kjøring har produsert faktiske UI-komp.; │ │ ellers: "bruk HIG/Material direkte" (domain-pack-default). │ └──────────────────────────────────────────────────────────────────────────┘ ``` **Sekvenseringen er lineær med backtracking, ikke streng pipeline.** Fase 6 kan avsløre arkitektur-gap → tilbake til 3. Fase 7 brief-skriving kan avsløre constraint-konflikt → tilbake til 5. Backtracking er læring, ikke feil. **Eksplisitte fase-transisjoner = operatør-handling (R15).** Hver fase-grense krysses ved at operatøren oppdaterer `phase_status` i brief-frontmatter og `state.json` — ikke ved at AI-en "går videre". Design-research (A-P2: spec-kit #1011 — agenten implementerte uten å stoppe ved fase-grensen) viser hvorfor dette ikke kan være kun en prompt-instruksjon. AI-en stopper og venter på operatør-handlingen. **Rapid mode (R5):** for en liten app forfatteren bygger for seg selv: app-konsept → minimal-men-gyldig app-brief inline → ett eller flere fase 7-feature-briefer, uten 2–6. Minimal-men-gyldig app-brief = problem & motivasjon + målgruppe + minst ett suksess-kriterium + ikke-tom utenfor-liste + plattform (en delmengde av kvalitets-sjekk-spørsmålene; se fase 1). Det er nok til at nedstrøms ikke hallusinerer (anker-prinsippet, A-P5), uten å passere de fem mellomliggende fasene. Den fulle pipelinen er eskalering når operatøren genuint er usikker eller appen er stor nok til at koordinering mellom fase-artefakter lønner seg. ## Filsystem-layout `[justert 2026-05-11 — R1: features/{NN}-{slug}/, 00-context/]` ``` {app-creator-instance-dir}/ ├── app.md # App-identitet (slug, navn, plattform, dato, domain_packs) ├── state.json # Live status (fase-progress, attention, domain_pack, session) ├── 00-context/ # Materialiserte domain-pack-snapshots + per-app-overrides │ ├── 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 ├── 03-architecture-brief.md # Output fra fase 3 (skippbar) ├── 04-design-brief.md # Output fra fase 4 (trigges på bruk) ├── 05-constraints-brief.md # Output fra fase 5 (skippbar) ├── 06-features-brief.md # Output fra fase 6 (backlog + dependency-graf) └── features/ # Output fra fase 7 — én mappe per feature └── {NN}-{feature-slug}/ ├── brief.md # Voyage strict-mode-kompatibel — implementerers primær-input ├── 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 `.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). ## Felles brief-frontmatter-felter `[hypotese]` Alle interne briefer i app-creator (fase 1–6) har disse felles felter: ```yaml --- brief_type: app | research | architecture | design | constraints | features phase: 1-6 phase_status: not-started | in-progress | pending-review | revision-in-progress | revised | complete | skipped parent_app: {app-slug} domain_pack: "ios-app@{version}" # null hvis ingen pack brukt; pin til den versjonen appen faktisk bruker 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 mot artefaktets eget tak, se § Hard lengde-grense # (teller IKKE sidecar-en .revisions.md) --- ``` Fase 7-feature-briefer (`features/{NN}-{slug}/brief.md`) bruker Voyages frontmatter-skjema, ikke dette — se Fase 7. ### `phase_status` — én autoritativ enum `[justert 2026-08-10 — A1/R-06]` Vokabularet lå tidligere i tre innbyrdes uforenlige varianter (frontmatter-spec, `state.json`-spec, og en tredje form Akashic bruker i praksis). Dette er **den ene** listen; alle andre steder viser hit. | Verdi | Betyr | Neste fase blokkert? | |---|---|---| | `not-started` | Fasen er ikke begynt. | ja | | `in-progress` | AI arbeider på artefakten. | ja | | `pending-review` | Artefakten er **AI-skrevet, ikke operatør-godkjent**. Review-gaten står åpen. | ja | | `revision-in-progress` | Annotasjoner mottatt, AI reviderer. | ja | | `revised` | Revidert etter annotasjoner; venter på ny gate-passering. | ja | | `complete` | **Operatør-godkjent.** Eneste verdi som slipper neste fase gjennom. | nei | | `skipped` | Bevisst hoppet over, med `reason`. | nei | Kritisk skille (friksjon #15 / Akashic S13): `complete` betyr *operatør-godkjent*, aldri «AI ble ferdig». Det er `pending-review` som betyr sistnevnte. Den gamle frontmatter-enumen manglet `pending-review` helt, så en sesjon som fulgte spec-en bokstavelig kunne bare skrive `complete` når den mente `pending-review` — nøyaktig forvekslingen som utløste operatør-stoppen i S13. **Objektformer** (i `state.json`, der en skalar ikke er nok): - Skippet fase: `{ "status": "skipped", "reason": "..." }` - Review-gate åpen: `{ "status": "pending-review", "revision": 0, "sidecar": "", "blocking": [] }` **Kjent avvik, ikke løst her:** Akashic-instansen bruker i praksis to objektformer ingen spec dekker (`revised` med `revision`/`revised_at`/`driver`/`open_questions`, og `complete` med `completed`/`total`/`completed_at`/`completed_note`), og fase 7 er modellert som en skalar selv om den er en **kontinuerlig aktivitet** (`"7": "complete"` ved 1 av 12 briefer er villedende for en aggregator). Begge er utsatt til **C2** (state-schema med per-feature fase 7-semantikk + normalisering av instansen) — A1 samler bare vokabularet, den redesigner det ikke. **Attention-typene** har samme sprik: spec-en nevnte `review-pending`/`decision`/`review`, mens virkeligheten bruker `decision-pending`, `action-pending`, `environment-blocker`, `revision-pending`, og `phase`-feltet er udefinert fritekst. Lukket enum + `phase`-domene defineres i **C2**. ## Pre-pipeline: init `[justert 2026-05-11 — R12 / friksjon #1: identitet only]` **Formål:** Opprette en app-creator-instans og registrere den i state. **Workflow `[hypotese]`:** 1. Operatøren kjører `/app-creator init {slug}` (eller tilsvarende). 2. AI oppretter `{app-creator-instance-dir}/`. 3. AI ber om **kun identitets-data**: app-navn, plattform-mål, dato. Eventuelt hvilken domain-pack appen skal bruke (`ios-app`, `claude-code-plugin`, ingen) — eller dette settes i fase 1. 4. Materialiserer `00-context/domain-pack-{name}.md`-snapshot hvis en pack er valgt. 5. Skriver `app.md` (identitets-fil) og initial `state.json` (fase 0, ingen attention). **Output: `app.md`** `[justert 2026-05-11 — R12: "Hvorfor" + "Pre-fase-notater" droppet fra init]` ```yaml --- slug: fitness-tracker name: "Fitness Tracker" created: 2026-05-10 platform: ios domain_packs: ["ios-app@0.1.0"] status: active --- # {Navn} ## Hvorfor denne appen ``` `app.md` er identitets-fil, ikke en brief. Intent-fila er `01-app-brief.md`. `app.md` er rot-fila app-factory bruker for app-discovery. **Endring fra førsteutkastet:** "Hvorfor denne appen" og "Pre-fase-notater" er fjernet fra init-spørsmålene — fase 1 sin Anchor for Problem & motivasjon spør i praksis det samme, bare grundigere, og to versjoner som ikke matcher er ren friksjon. "Hvorfor"-avsnittet skrives etter fase 1 som destillering. --- ## Fase 1 — Intervju → App brief `[delvis testet 2026-05-11 — Akashic-kjøring; justert per friksjon #1–4]` **Formål:** Hente ut app-intent klart nok til å bygge resten på. **To varianter:** - **Minimal-variant (default).** En kort fritekst-runde: operatør skriver/dikterer problem & motivasjon + målgruppe + minst ett suksess-kriterium + ikke-tom utenfor-liste + plattform; AI strukturerer det til en `01-app-brief.md` i minimal form. Ingen weakest-section-loop, ingen 6 kvalitets-sjekk-spørsmål, ingen transkript-fil. Dette er nok for rapid mode og for små apper. (Thread E: å intervjue seg selv er rituell nedskriving — den lette varianten respekterer det.) - **Full-variant (opt-in).** Det strukturerte 8-tema-intervjuet (sjekkliste-temaene under) med trekbrief-disiplinene. Velges når operatøren genuint er usikker på app-intent og trenger AI til å presse fram presisjon. Produserer `01-interview-transcript.md` i tillegg til `01-app-brief.md`. **Input (begge varianter):** - `app.md` (fra pre-pipeline). - Operatørens åpne ideer/skisser. - Domain-pack: `conventions.md` (domene-rammer som farger spørsmålene — f.eks. "dette er en iOS-app, så plattform-spørsmålet inkluderer widgets/extensions"), evt. `glossary.md`. **Tidlig eierskaps-spørsmål (begge varianter, R12 / friksjon #4):** Som ett av de første spørsmålene (tur 1–2 i full-variant; del av minimal-prompten): *"Hvem er dette egentlig for: deg selv, andre, eller begge? Hvis du må velge én — hvilken vinner når de er i konflikt?"* Dette rammer alle påfølgende svar riktig fra start. (I Akashic-kjøringen kom denne rekalibreringen i tur 9 og endret tolkningen av tur 4 betydelig.) **Appetite / scope-budsjett (begge varianter, R13):** Tidlig i fase 1: *"Hvor mye er du villig til å bruke på dette — en helg, et par uker, måneder?"* Appetite er ikke et estimat, det er et budsjett som dobler som scope-constraint (Shape Up). Skrives inn i app-brief. ### Workflow — full-variant `[hypotese]` 1. AI starter strukturert intervju. 2. Sjekkliste-tema (kategorier, ikke fast rekkefølge): - Eierskap & intensjon (tidlig — se over) - Problem & motivasjon - Brukere - Suksess-kriterier - Omfang - Appetite / scope-budsjett - Plattform-spesifikt - Tidshorisont 3. AI følger opp på tvetydighet, summerer underveis. 4. Operatør korrigerer. 5. Avsluttes når sjekkliste er dekket, pre-draft-kvalitets-sjekken passerer, app-brief er skrevet, post-draft-sjekken passerer, og operatør sier OK. ### Kjøre-disiplin (importert fra Voyage trekbrief) `[importert fra trekbrief, justert for per-app, hypotese — kun full-variant]` Voyages `/trekbrief` har fem disipliner som per-task-intervjuet hviler på. Full-varianten importerer dem her som *kjøre-disiplin* (ikke kode), justert for at app-scope er bredere og mykere enn task-scope. **1. Weakest-section-first-loop.** Gå ikke gjennom temaene kronologisk. Velg svakeste tema mellom hvert svar. Standard prioritering: ``` Eierskap & intensjon → Problem & motivasjon → Brukere → Suksess-kriterier → Omfang → Appetite → Plattform → Tidshorisont ``` Begrunnelse: Eierskap rammer alt annet (friksjon #4); Suksess-kriterier kan ikke skrives før Brukere er konkret; Omfang kan ikke skrives før Problem er tydelig. **2. Anchor / Sharpen-mønster.** Per tema starter med en *Anchor* — åpent spørsmål uten å lede. Hvis svaret er vagt, bruk *Sharpen* — krev konkretisering. **For Omfang spesifikt (R12 / friksjon #3):** skill eksplisitt: - *"Hva appen GJØR"* — funksjonelle features (det som hører i fase 1-brief og driver fase 6 feature-derivasjon). - *"Hvordan appen ER"* — kvalitative egenskaper (visuelt, brukervennlig, ytelse — hører i fase 4 designsystem og fase 5 constraints). Hvis operatør svarer på Omfang med produkt-kvaliteter ("visuelt innbydende", "brukervennlig"), er det fint — det er fase 4/5-input. Følg så opp med en **AI-foreslått funksjonell-features-hypotese** som standard neste steg ("Basert på dette: appen MÅ kanskje kunne X, Y, Z — stemmer det?"), ikke en ad-hoc redning. (I Akashic tok dette en ekstra runde fordi det ikke var planlagt.) Aldri repeter samme Sharpen-variant på samme tema. Hvis Sharpen ikke gir mer presisjon: marker som `[ANTAKELSE]` (disiplin 4) og gå videre. **3. Aktiv research-tema-uthenting under dialog.** Lytt etter signaler som krever research før arkitektur (fase 3): ukjent teknologi, ny iOS-versjon/framework-API, security-valg, arkitektur-valg, opphavsrett/juridiske spørsmål. Fang med struktur i transkript: ``` [RESEARCH-TEMA] Question: ... ? # slutter med ?, spesifikt nok til at noen kan svare Confidence needed: high # high (driver arkitektur-beslutning) | medium | low Scope hint: ekstern docs # lokal kode-research | ekstern docs | begge ``` Disse bæres til fase 2-research-plan. Hvis operatør sier "jeg vet svaret", strykes temaet — svaret skrives kort i transkript som referanse. **4. `[ANTAKELSE]`-markører.** Når operatør sier "ikke vet" om noe materielt, skriv det eksplisitt: `[ANTAKELSE] {plattform-min-versjon} er minimum — ikke verifisert mot målgruppens enhets-park.` Forskjellen fra et research-tema: en antakelse er en bevisst pause vi bærer risiko-en for; et research-tema er et åpent svar vi planlegger å hente. Antakelser legges i app-brief sin "Åpne spørsmål"-seksjon med `[ANTAKELSE]`-prefiks, bæres til fase 3 hvor de aktivt resolveres eller eksplisitt aksepteres. **5. Kvalitets-sjekk — splittet i to (R12 / friksjon #2).** Ikke en agent, ikke scoring. Det opprinnelige spørsmål #1 ("Er problem & motivasjon skrevet i 1–2 avsnitt operatør står bak?") forutsatte artefakten den skulle validere — kylling-og-egg. Løsning: splitt. *Pre-draft-sjekk (5 ja/nei, besvarbare fra transkriptet — kjøres FØR app-brief skrives):* 1. Har vi nok materiale i transkriptet til å skrive et problem & motivasjon-avsnitt operatør vil stå bak? 2. Er primær målgruppe konkret nok til å peke på én person eller persona med kontekst? 3. Finnes minst ett suksess-kriterium med konkret målbarhet — selv om målingen først kan gjøres post-shipping? 4. Er omfang-utenfor-listen ikke-tom? (Ingen ærlig app har tomt utenfor-omfang.) 5. Er åpne spørsmål kategorisert som *research-tema* / *arkitektur-beslutning* / *`[ANTAKELSE]` bæres videre*? Og er plattform-detaljer (target, min-versjon, extensions/widgets) eksplisitte? *Post-draft-sjekk (1 ja/nei — kjøres ETTER app-brief er skrevet og operatør har lest den):* 6. Står operatør bak problem & motivasjon-avsnittet slik AI formulerte det? Hvis ett eller flere svar er nei: gå tilbake til svakeste tema og kjør en runde til. Maks 3 runder før operatør tar eksplisitt beslutning om å eksitere med kjent svakhet (dokumenteres i brief sin "Åpne spørsmål"-seksjon). ### Det som IKKE oversettes fra trekbrief trekbrief har mekanisk 1–5-scoring og dedikert reviewer-agent. Disse hører i per-task-kontekst der suksess-kriterier kan være command-checkable. Per-app-intervjuet skal IKKE importere dette — det blir premature lock-down. Hvis prototypen viser at en lett reviewer-pass faktisk hjelper, vurderes det i v0.5.0+. **Output 1: `01-interview-transcript.md`** `[hypotese — kun full-variant]` — full samtale, råform, tidsstempel-merket per spørsmål-svar. Ingen frontmatter krevd. Ingen lengde-grense. Råmateriale for senere referanse, ikke en brief. **Output 2: `01-app-brief.md`** `[delvis testet 2026-05-11]` ```yaml --- brief_type: app phase: 1 phase_status: complete parent_app: fitness-tracker domain_pack: "ios-app@0.1.0" variant: minimal | full created: 2026-05-10 last_modified: 2026-05-10 revision: 0 revision_reason: null length_words: {N} --- # App brief: {Navn} ## Problem og motivasjon {1-2 avsnitt — hva løser appen, for hvem, hvorfor nå} ## Eierskap & intensjon {For hvem: deg selv / andre / begge. Hvilken vinner ved konflikt.} ## Målgruppe - **Primær:** {beskrivelse, kontekst, ferdighetsnivå} - **Sekundær:** {beskrivelse hvis aktuelt — ellers "ingen"} ## Suksess-kriterier - {konkret, helst målbart kriterium} - {konkret, helst målbart kriterium} ## Omfang ### Innenfor (funksjonelle features — "hva appen GJØR") - {punkt} ### Utenfor (eksplisitt — no-gos) - {punkt} ### Rabbit holes (ting som ser små ut men kan eksplodere — distinkt fra no-gos) - {punkt — f.eks. "opphavsrett på tredjepart-innhold: kan bli en juridisk avgrunn"} ## Appetite / scope-budsjett - {en helg / et par uker / måneder — budsjettet som også er scope-constraint} ## Plattform - **Mål:** {iOS-only / universal / watch+phone / etc.} - **Min-versjon:** {min-versjon — verifiser mot domain-pack `conventions.md`, ikke mot hukommelse} - **Andre plattform-detaljer:** {widgets / extensions / shortcuts / Live Activities / etc.} ## Tidshorisont - **MVP / v1:** {beskrivelse} - **v1.1+:** {beskrivelse hvis relevant} - **Lengre sikt:** {beskrivelse hvis relevant} ## Release-modell (de scope-relevante valgene — se scope-lås) - **Distribusjon:** {paid app / freemium / gratis — og hvorfor} - **Analytics:** {ja/nei + type hvis ja — ikke konfigurasjon} - **Versjonerings-strategi:** {kun hvis det er en bevisst beslutning, ellers "standard"} ## Åpne spørsmål etter intervju - {[RESEARCH-TEMA] ... — fase 2 håndterer} - {[ANTAKELSE] ... — fase 3 resolverer eller aksepterer} - {arkitektur-beslutning ... — fase 3 håndterer} ## Referanser - `01-interview-transcript.md` — full samtale (kun full-variant) ``` (I minimal-variant droppes Eierskap-, Appetite- og Rabbit-holes-seksjonen til egne overskrifter hvis de blir tomme — men eierskaps-spørsmålet stilles uansett, og svaret går inn i Problem & motivasjon-avsnittet.) **Transisjon:** Operatør markerer fasen complete ved å oppdatere `phase_status: complete` i app-brief og `state.json`. Skriv "Hvorfor denne appen"-avsnittet i `app.md` som destillering. Hvis åpne research-temaer finnes og operatøren vil ha dem løst først → fase 2 (eskalering). Hvis ikke → fase 3, eller rapid mode → fase 7. --- ## Fase 2 — Research → Research briefer `[hypotese — SKIPPBAR]` **Skippbar.** Hopp er gyldig hvis det ikke finnes høy-confidence research-temaer som driver arkitektur-beslutninger. Et hopp loggføres i `state.json`: `"2": {"status": "skipped", "reason": "ingen research-temaer som driver arkitektur"}`. Ikke bare "valgfri" — et bevisst, begrunnet hopp. **Formål:** Validere antakelser, finne presedens, identifisere gotchas før arkitektur låses. **Input:** - `01-app-brief.md`. - Liste over åpne research-temaer (fra app-brief). - **Ingen domain-pack-input.** *(Justert 2026-08-10 — A1/R-14: pack-input for fase 2 er strøket.)* Fase 2 står ikke i noen pack-manifests `phases`-liste (`ios-app/pack.json` lister `[1,3,4,5,6,7]`), står ikke i pack-tabellen over, og er utelatt i `domain-pack-spec.md`. Akashic-kjøringens fase 2 klarte seg uten pack-filer. Den gamle linjen (`gotchas.md` + `patterns/`) var derfor en selvmotsigelse en implementasjon ville måttet velge side i — og hadde den valgt linjen, ville den brutt pack-manifestets kontrakt. Trenger et research-tema domene-kunnskap, kommer den via `01-app-brief.md` (skrevet med pack-input i fase 1) eller via `00-context/`-snapshotet. **Workflow `[hypotese]`:** 1. AI foreslår research-plan basert på åpne temaer. 2. Operatør approver eller justerer. 3. Per tema: AI gjennomfører research (web, docs, kjente kilder), produserer brief. 4. Hvert tema lagres som egen brief. 5. Avsluttes når alle planlagte temaer er undersøkt. **Output: `02-research-briefs/NN-{topic-slug}.md`** `[hypotese, arvet fra Voyages research-format]` ```yaml --- brief_type: research phase: 2 phase_status: complete parent_app: fitness-tracker domain_pack: "ios-app@0.1.0" created: 2026-05-10 last_modified: 2026-05-10 revision: 0 topic: {kort tittel} question: {opprinnelig spørsmål} confidence: high | medium | low sources_count: {antall} length_words: {N} --- # Research brief: {Tittel} ## Spørsmål {Det vi prøver å svare på, med kontekst fra app-brief} ## Funn {Strukturerte funn med inline-kilder} ## Konsekvens for senere faser - **Arkitektur (fase 3):** {hva dette betyr} - **Designsystem (fase 4):** {hvis relevant} - **Constraints (fase 5):** {hvis relevant} - **Features (fase 6):** {hvis relevant} ## Kilder - {URL eller referanse} ## Restrisiko / åpne spørsmål - {hva som fortsatt ikke er sikkert} ``` **Transisjon:** Når alle planlagte temaer er complete, fase markeres complete. Til fase 3. --- ## Fase 3 — Arkitekturavklaringer → Arkitektur brief `[justert 2026-05-11 — R9: spørsmål før spekulasjon; R14: requirements-first/design-first + problem-gate]` **Skippbar for trivielle apper.** Hvis app-en er liten nok til at arkitektur-valgene er åpenbare (én plattform, ingen backend, standard-stack), kan fasen hoppes med begrunnelse i `state.json`. For Akashic er den ikke skippbar — ANTAKELSE #2–5 er reelle arkitektur-beslutninger. **Formål:** Velge tech-stack, deployment-modell, integrasjoner, sentrale mønstre — og avklare hvilke spørsmål som fortsatt er åpne. **To gate-spørsmål før fasen starter (R14):** 1. **Problem-gate:** *"Er dette fortsatt riktig problem å løse?"* (PR/FAQ-stil — ett kort avsnitt: hvis vi shippet dette i morgen, hva ville pressemeldingen sagt, og holder den fortsatt?) Hvis svaret vakler: tilbake til fase 1, ikke videre. 2. **Requirements-first vs design-first:** *"Vet vi hva appen skal gjøre og lar arkitektur følge, eller er det en arkitektur-/teknologi-beslutning som former hva appen kan være?"* (Kiro-distinksjonen.) For Akashic: requirements-first — men ANTAKELSE #2–5 grenser mot design-first og må behandles som arkitektur-constraints. **Input:** - `01-app-brief.md`. - `02-research-briefs/*.md` (hvis fase 2 ble brukt). - Domain-pack: `conventions.md`, max 1–2 `patterns/{relevant}.md`, evt. `gotchas.md`. **Workflow `[hypotese]`:** 1. AI foreslår arkitektur-alternativer (typisk 2–3 sammenligning) basert på intent + research. 2. Per beslutnings-punkt: AI gir anbefaling med begrunnelse. **ADR-en skrives idet beslutningen tas** — ikke en full decisions-log opp front. Hvis beslutningen ikke kan tas ennå: den havner i "Uavklarte arkitektur-spørsmål", ikke som en spekulativ ADR. 3. Operatør approver, foreslår alternativ, eller stiller spørsmål. 4. Avsluttes når de beslutningene som *kan* tas er tatt, og resten er eksplisitt listet som åpne. **Output: `03-architecture-brief.md`** `[hypotese]` ```yaml --- brief_type: architecture phase: 3 phase_status: complete parent_app: fitness-tracker domain_pack: "ios-app@0.1.0" created: 2026-05-10 last_modified: 2026-05-10 revision: 0 decision_count: {N} open_question_count: {N} length_words: {N} --- # Arkitektur brief ## Problem-gate (PR/FAQ — ett avsnitt) {Hvis vi shippet dette i morgen: hva ville pressemeldingen sagt, og holder den?} ## Requirements-first eller design-first? {Hvilken — og hvilke arkitektur-constraints fra app-brief som låser hva.} ## Stack-sammendrag - **Språk/runtime:** {f.eks. Swift 6 + SwiftUI} - **Plattform-target:** {deployment-target — verifiser mot domain-pack `conventions.md`} - **State-management:** {f.eks. Observation framework + SwiftData} - **Persistens:** {f.eks. SwiftData, ingen backend} - **Nettverk:** {f.eks. URLSession + actor isolation — eller "ingen"} - **Test-strategi-baseline:** {f.eks. Swift Testing + XCUITest — strategi-detaljer i fase 5} ## Vedtatte beslutninger (ADR-style — skrevet idet beslutningen ble tatt) ### ADR-001: {Beslutnings-tittel} **Status:** Vedtatt {YYYY-MM-DD} **Kontekst:** {Problem som krevde beslutning} **Vurderte alternativer:** 1. **{A}** — pros: {...}, cons: {...} 2. **{B}** — pros: {...}, cons: {...} **Beslutning:** {Valgt alternativ med begrunnelse} **Konsekvenser:** {hva dette gjør lett / vanskelig / låser oss til} **Revisjons-trigger:** {Når denne burde re-vurderes} --- ## Uavklarte arkitektur-spørsmål (lukkes etter hvert — ikke spekuler nå) - **AQ-001:** {spørsmål} — blokkerer: {hva}; forventet lukket: {fase / hendelse} - **AQ-002:** {[ANTAKELSE] fra fase 1 som må resolveres her} ## Sentrale patterns (kun de som faktisk er besluttet) - **{Pattern A}:** {hvorfor og hvor brukt} ## Integrasjoner - **{Tredjepart eller Apple-API}:** {bruks-formål} ## Referanser - `01-app-brief.md` - `02-research-briefs/NN-*.md` (hvis brukt) ``` **Transisjon:** Når de mulige beslutningene er tatt og resten er listet som åpne, fase complete. Til fase 5 (fase 4 trigges separat på bruk). --- ## Fase 4 — Designsystem → Design brief `[justert 2026-05-11 — R8: trigges på bruk, ikke plan]` **Trigges på bruk, ikke plan.** Et designsystem kodifisert før det finnes UI-komponenter er prematur abstraksjon (YAGNI, thread E — den mest sårbare fasen). Fasen aktiveres **etter at første Voyage-kjøring har produsert faktiske UI-komponenter** og feature-settet er stabilt nok til at det lønner seg å kodifisere tokens. Inntil da: "bruk HIG (iOS) / Material (Android) direkte" — domain-pack `conventions.md` bærer base-systemets regler, og hver feature-brief refererer dem. For mange små apper utløses fase 4 aldri, og det er riktig. **Når den utløses — formål:** kodifisere tokens og gjenbrukbare komponenter når feature-settet er stabilt nok til at konsistens-gevinsten overstiger kostnaden. **Input:** - `01-app-brief.md` (målgruppe, tone). - `03-architecture-brief.md` (plattform-target — begrenser tilgjengelige design-API). - Faktiske UI-komponenter fra første Voyage-kjøring(er). - Domain-pack: `conventions.md` (HIG/Material-default), `patterns/{ui-relevant}.md`. **Workflow `[hypotese]`:** 1. AI ekstraherer tokens fra de UI-komponentene som faktisk er bygget (farger, typografi, spacing, motion, interaksjons-mønstre som har dukket opp). 2. AI foreslår konsolidering: hvilke ad-hoc-verdier som bør bli navngitte tokens. 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 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. --- ## Fase 5 — Constraints → Constraints brief `[justert 2026-05-11 — R11: strukturert mot ISO 25010:2023 / WCAG 2.2 / MASVS 2.1 / privacy manifest; SKIPPBAR]` **Skippbar.** Mye av denne fasens innhold bæres av domain-pack `checklist.md` (App Store-submission-checklist, MASVS 2.1, WCAG 2.2 AA, privacy-manifest-mal) — for en liten app som følger domain-pack-defaults kan fasen hoppes med begrunnelse i `state.json`. Constraints som faktisk avviker fra pack-defaults, eller app-spesifikke krav (Akashic: ingen-effekt-claims, ikke-affiliering-disclaimer), MÅ skrives ned — da er ikke fasen skippbar. **Formål:** Cross-feature regler som gjelder for alle features uavhengig av deres egen logikk — strukturert mot de standardene den implisitt refererer, slik at gap er synlige. **Input:** - `01-app-brief.md` (suksess-kriterier, constraint-signaler, release-modell). - `03-architecture-brief.md` (plattform-target gir baseline). - Domain-pack: `00-context/`-snapshotet (én lasting — bærer alle core-filene, inkl. samtlige `checklist*.md` og `gotchas.md`; standardenes innhold lever der — referanse, ikke kopi). Uten snapshot: checklist-filene (`ios-app` har dem splittet i tre) + `gotchas.md` lastes direkte — det er >3 filer og derfor **kun** gyldig via snapshotet eller ved å laste dem i to omganger. *(Justert 2026-08-10 — A1/R-15: den gamle linjen sprengte max-3-regelen på papir mens praksis leste snapshotet.)* **Workflow `[hypotese]`:** 1. AI går gjennom domain-pack `checklist.md` og lister hvilke punkter som gjelder denne appen. 2. AI lister app-spesifikke constraints som ikke er i checklisten. 3. Hver constraint klassifiseres: `[enforce]` (hard krav) eller `[aspire]` (mål). 4. Operatør approver eller utvider. **Output: `05-constraints-brief.md`** `[hypotese]` — body strukturert mot standardene (referanse, ikke uttømmende inline — checklisten i domain-pack-en er det uttømmende): ```yaml --- brief_type: constraints phase: 5 phase_status: complete parent_app: fitness-tracker domain_pack: "ios-app@0.1.0" created: 2026-05-10 last_modified: 2026-05-10 revision: 0 constraint_count: {N} length_words: {N} --- # Constraints brief ## Kvalitet (mot ISO/IEC 25010:2023 — 9 karakteristikker) *Per relevant karakteristikk: hva gjelder. Særlig de nye i 2023-revisjonen: Safety, Flexibility/Scalability.* - **Performance efficiency:** **[enforce]** App launch < 1.5s på iPhone 13. **[aspire]** 60fps på alle interaksjoner. - **Compatibility / Portability:** **[enforce]** {baseline-versjon} som baseline; API-er fra nyere versjoner degraderer ikke baseline-funksjonalitet. (Konkrete versjonstall hentes fra domain-pack `conventions.md` — templaten skal ikke bære dem, jf. friksjon #9.) - **Reliability:** **[aspire]** Crash-free-rate > 99.5%. - **Security:** se egen seksjon (MASVS). - **Maintainability / Flexibility:** {hvis relevant} - ... (kun de karakteristikkene som faktisk har constraints) ## Tilgjengelighet (mot WCAG 2.2 AA — inkl. de 4 nye 2.2-kriteriene) - **[enforce]** WCAG 2.2 AA-kontrast i alle synlige elementer (1.4.3 / 1.4.11). - **[enforce]** VoiceOver-labels på alle interaktive elementer. - **[enforce]** Target Size (Minimum) 2.5.8 — interaktive mål ≥ 24×24pt (Apple anbefaler 44×44). - **[enforce]** Focus Not Obscured (Minimum) 2.4.11. - **[enforce]** Accessible Authentication (Minimum) 3.3.8 — hvis appen har innlogging. - **[aspire]** Focus Appearance 2.4.13; Dynamic Type opp til AX5. ## Sikkerhet & personvern (mot OWASP MASVS 2.1 — 8 kontroll-grupper + privacy manifest) - **[enforce]** MASVS-STORAGE: sensitiv data i Keychain, ikke UserDefaults. - **[enforce]** MASVS-NETWORK: ATS på, ingen unntak uten begrunnelse. - **[enforce]** MASVS-PRIVACY: required-reason-API-deklarasjon i `PrivacyInfo.xcprivacy` (template i domain-pack `scaffold/`); per-SDK privacy-manifest-krav; App Privacy Details "nutrition label" utfylt. - **[enforce]** Ingen tracking uten ATT-permission. - ... (kun de MASVS-gruppene som har constraints) ## Plattform-regler (App Store) - **[enforce]** App Store Review Guidelines compliance — se domain-pack `checklist.md` for full submission-checklist. - **[enforce]** HIG-konformt navigation-mønster. - **[enforce]** Eksport-compliance-deklarasjon; region-krav (DSA / aldersmerking) der relevant. ## Governance / juridisk (app-spesifikt) - {f.eks. Akashic: **[enforce]** ingen vitenskaplig udokumenterte effekt-claims; **[enforce]** eksplisitt ikke-affiliering med Isha i App Store-beskrivelse.} - **[aspire]** GDPR-klar for europeiske brukere. ## Test-strategi (strategi-beslutninger — infrastruktur er features i fase 6) - **[enforce]** Per-feature: unit-tester for forretnings-logikk; UI-tester for primær-flow; Voyage `/trekreview`-pass uten BLOCKERS før feature regnes complete. - **[enforce]** App-nivå (bygges som `F-T`-features i fase 6): E2E for kritisk sti; A11Y-compliance-suite; performance-regresjon for launch + navigasjon. - **[aspire]** Visuell regresjon (screenshot-sammenligning); cross-feature-regresjons-suite ved hver ny feature. - **Dekningsmål:** {konkret tall hvis besluttet}. **Device/OS-matrise:** {hvilke}. ## Konflikt-håndtering [enforce] over [aspire] → eldste over nyeste → operatør-beslutning. ## Referanser - `01-app-brief.md`, `03-architecture-brief.md` - domain-pack `checklist.md` — det uttømmende submission-/standard-grunnlaget ``` **Transisjon:** Når constraints er listet og kategorisert, fase complete. Til fase 6. --- ## Fase 6 — Feature-derivasjon → Features brief `[hypotese]` **Formål:** Avlede feature-backlog fra fasene 1–5, identifisere avhengigheter, prioritere — inkludert test-infrastruktur-features avledet fra fase 5-test-strategien. **Input:** - Alle briefer fra fasene 1–5 (fase 4 kan være tom — da brukes domain-pack `conventions.md` for UI-konvensjoner). - Domain-pack: `checklist.md` (for å identifisere hvilke test-infra-/submission-features backlogen trenger), evt. `examples/` (eksempel-backlog). **Workflow `[hypotese]`:** 1. AI foreslår feature-liste basert på intent + arkitektur + constraints. 2. Per feature: navn, formål, suksess-kriterium, avhengigheter, antatt størrelse, prioritet. 3. AI legger til `F-T`-features for app-nivå-test-infrastruktur (driver: fase 5 § Test-strategi). 4. Operatør approver, omprioriterer, flytter ting til "later". 5. AI tegner dependency-graf og identifiserer kritisk sti + parallelliserbare grupper. **Output: `06-features-brief.md`** `[hypotese]` — samme struktur som førsteutkastet, men feature-mapping oppdatert til `features/{NN}-{slug}/`: ```yaml --- brief_type: features phase: 6 phase_status: complete parent_app: fitness-tracker domain_pack: "ios-app@0.1.0" created: 2026-05-10 last_modified: 2026-05-10 revision: 0 feature_count: {N} --- # Features brief ## Backlog ### F-001: {Feature-navn} - **Slug:** {feature-slug} → mappe: `features/01-{feature-slug}/` - **Formål:** {én setning} - **Suksess-kriterium:** {hvordan vet vi at den virker — helst command-checkable} - **Avhengigheter:** F-002, F-003 (eller "ingen") - **Antatt størrelse:** XS / S / M / L - **Prioritet:** P0 / P1 / P2 / P3 - **Status:** brief-pending | brief-written | voyage-running | voyage-complete | shipped ### F-T01: E2E test framework setup *(test-infra-feature)* - **Slug:** test-e2e-framework → mappe: `features/T01-test-e2e-framework/` - **Formål:** XCUITest-suite for kritisk bruker-flow (driver: `05-constraints-brief.md` § Test-strategi) - **Suksess-kriterium:** Login → core-action-flow har grønn E2E-test som kjører i CI - **Avhengigheter:** F-001, F-002, F-003 — alle må være shipped - **Antatt størrelse:** M · **Prioritet:** P1 · **Status:** brief-pending > **Mønster:** Test-infrastruktur er features i backlogen, ikke et separat lag. Voyage bygger dem som hvilken som helst feature ved at de får sin egen `brief.md` i fase 7. `F-T`-prefiks er en konvensjon for visuelt skille — ikke en arkitektur-grense. Krav til disse driverne fra `05-constraints-brief.md` § Test-strategi (eller domain-pack `checklist.md` hvis fase 5 ble hoppet). ## Dependency-graf ```mermaid graph TD F-001[Login flow] --> F-002[Onboarding] F-002 --> F-003[Main feed] F-002 --> F-004[Profile] F-003 --> F-005[Detail view] ``` ## Kritisk sti F-001 → F-002 → F-003 → F-005 ## Parallelliserbare grupper **Gruppe A (etter F-002):** F-003, F-004 — kan utvikles samtidig. ## Referanser - `01-app-brief.md`, `03-architecture-brief.md`, `04-design-brief.md` (hvis finnes), `05-constraints-brief.md` ``` `{NN}`-prefiks på feature-mappene tildeles i topologisk rekkefølge fra dependency-grafen: en feature uten avhengigheter får lavt NN, en som avhenger av andre får høyere. Innen samme app: lavere NN avhenger aldri av høyere NN. **Transisjon:** Når brief er approvert, fase complete. Til readiness-check, så fase 7 (kontinuerlig). --- ## Implementation-readiness-check (R14 — før fase 7-handover) Før den første feature-briefen overleveres til Voyage: en lett koherens-sjekk på tvers av fase 1–6-briefene (inspirert av BMAD `bmad-check-implementation-readiness`). Ikke en agent, en operatør-gjennomgang med PASS / CONCERNS / FAIL: - Sporbarhet: hver feature i fase 6-backloggen sporer til et behov i fase 1-brief? Ingen orphan-features? - Constraint-dekning: fase 5-constraints (eller domain-pack-checklist) er reflektert i de feature-briefene som berøres? - Arkitektur-konsistens: ingen feature forutsetter noe som motsier en vedtatt ADR i fase 3? Åpne arkitektur-spørsmål (AQ-NNN) som blokkerer en feature er fortsatt åpne — er featuren da klar? - Dependency-koherens: dependency-grafen er asyklisk, og `{NN}`-rekkefølgen respekterer den? **FAIL** → tilbake til den fasen som mangler. **CONCERNS** → operatør beslutter eksplisitt om handover skjer likevel, og hva risikoen er. **PASS** → fase 7 kan starte. (For rapid mode: en mini-versjon — bare "sporer feature-briefen til den minimal-men-gyldige app-briefen, og er app-briefen ikke-tom på de fem feltene?") --- ## Fase 7 — Brief per feature → Feature-artefakter `[justert 2026-05-11 — R2: mot Voyages faktiske Handover-1-kontrakt, strict mode; brief.md + context.md-splitt]` **Formål:** Produsere Voyage-kompatible feature-artefakter per feature, on-demand når operatør er klar for handover. **Input:** - `06-features-brief.md` (eller, i rapid mode: den minimal-men-gyldige app-briefen). - Alle briefer fra fasene 1–5 (kontekst per feature — fase 4 kan være tom). - Domain-pack: `checklist.md` (brief-validerings-items), `examples/` (eksempel-feature-brief), `scaffold/` (når artefakter materialiseres). **Workflow `[hypotese]`:** 1. Operatør velger neste feature å briefe (typisk topp av prioritet, ingen aktive avhengigheter). 2. AI genererer `brief.md` (Voyage strict-mode-kompatibel) + `context.md` (embedder upstream) i `features/{NN}-{slug}/`. 3. Operatør reviewer, approver eller annoterer (samme review-gate som for interne briefer — se under). 4. Approvert: filene er klare for Voyage-handover. 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. > > **Ingen reell round-trip har noensinne kjørt** (`voyage_running: 0`). «Round-trip-test PASS» i friksjon #14 og i Akashic-loggen er en **mental simulering**, ikke en kjøring — behandle den som papir. Omskriving til 2.2 med `framing`-avledning, TL;DR-generering og `phase_signals`-strategi er masterplan **A5**; første reelle kjøring er **B1**. Ikke bygg videre på blokken under før A5 er kjørt. **Frontmatter** — alle 8 Voyage-påkrevde felter + state-machine-constraint + app-creator-interne felter: ```yaml --- # --- Voyage-påkrevde (Handover 1, brief_version 2.0) --- type: trekbrief brief_version: "2.0" created: 2026-05-10 task: "{én-linjes task-beskrivelse — typisk feature-formålet}" slug: {feature-slug} project_dir: .claude/projects/{YYYY-MM-DD}-{feature-slug}/ research_topics: {N} # ≥ 0 research_status: pending # pending | in_progress | complete | skipped # State-machine: hvis research_topics > 0 OG research_status === "skipped" → brief_quality: partial PÅKREVD brief_quality: complete # complete | partial — sett "partial" hvis ovenstående gjelder # Valgfrie Voyage-felter: source: manual # interview | manual — app-creator-genererte er "manual" # --- app-creator-interne (Voyage ignorerer, eller app-creator stripper ved handover) --- brief_type: feature phase: 7 parent_app: {app-slug} parent_feature: F-001 domain_pack: "ios-app@{version}" # pin til den versjonen appen faktisk bruker revision: 0 voyage_run_dir: null # fylles når Voyage kjøres — peker til Voyages {project_dir} voyage_run_status: null # fylles av app-creator state-eksport fra Voyages progress.json/review.md --- ``` **Body** — de tre PÅKREVDE seksjonene (`## Intent`, `## Goal`, `## Success Criteria`) + standard-seksjonene. Generer for **strict mode**, ikke soft: ```markdown # Task: {feature-tittel} > Generert av app-creator fase 7 på {YYYY-MM-DD} fra {app-slug} feature {F-XXX}. ## Intent ← PÅKREVD {Hvorfor denne featuren — fra feature-formål + relevant del av app-brief Problem & motivasjon. 3-5 setninger. Load-bearing.} ## Goal ← PÅKREVD {Hva success ser ut som konkret når featuren er ferdig. Ett avsnitt. Spesifikt nok til å være uenig i.} ## Non-Goals - {feature-no-gos + relevant subset av app-brief utenfor-liste} ## Constraints - {relevant subset fra fase 5-constraints — IKKE hele constraints-brief-en, kun det som gjelder denne featuren} ## Preferences - {preferte mønstre/biblioteker — fra fase 3 ADRer der relevant} ## Non-Functional Requirements - {relevante NFRs, kvantifisert — f.eks. "ingen nye npm-deps", "60fps på scroll"} ## Success Criteria ← PÅKREVD - {falsifiserbart, command-checkable kriterium — helst Given-When-Then} - {f.eks. "Alle eksisterende tester passerer: `swift test` exit 0"} - IKKE vage kriterier ("det skal fungere", "featuren er implementert") ## Research Plan {Hvis research_topics = 0: én linje — "No external research needed — the codebase and this brief contain sufficient context for planning."} ### Topic 1: {Kort tittel} - **Why this matters:** {hvordan planen avhenger av svaret} - **Research question:** "{ett spørsmål, slutter med ?}" - **Suggested invocation:** `/trekresearch --project {project_dir} --external "{spørsmål}"` - **Required for plan steps:** {hvilke slags steg konsumerer dette} - **Confidence needed:** {high | medium | low} - **Estimated cost:** {quick | standard | deep} - **Scope hint:** {local | external | both} ## Open Questions / Assumptions - {[ANTAKELSE] som fortsatt gjelder for denne featuren} ## How to continue ```bash /trekresearch --project {project_dir} --external "{Topic 1-spørsmål}" # hvis research_topics > 0 /trekplan --project {project_dir} /trekexecute --project {project_dir} ``` ``` **Round-trip-test (krav før formatet låses):** skriv en faktisk Akashic-feature-brief → kjør `/trekplan --brief features/{NN}-{slug}/brief.md` → bekreft at Voyages brief-validator passerer den i **strict mode uten endring**. Gjøres når Akashic når fase 7; formatet over låses ikke før da. **Re-verifiser Voyage-kontrakten fra kildekode** rett før omskrivingen — Voyage er en levende plugin. Kanonisk sti (samme cache-regel som for `annotate.mjs`, A1/R-05): `~/.claude/plugins/cache/ktg-plugin-marketplace/voyage//docs/HANDOVER-CONTRACTS.md` og `templates/trekbrief-template.md`. Slå opp nyeste versjon med `ls` — hardkod ikke versjonsnummeret, og bruk ikke den gamle `plugins/marketplaces/…`-stien (den finnes ikke). ### `context.md` — embedder upstream (BMAD-prinsippet: embedding slår linking) Implementerers sekundær-input. Materialiserer (ikke bare refererer) det relevante utdraget — Voyage-agenten har ingen ambient kontekst å trekke på. Seksjoner: 1. **Dependencies** — features dette avhenger av (`{NN}-{slug}`-referanser) + features som avhenger av dette. 2. **Cross-cutting constraints** — relevant subset fra fase 5 (kun det som gjelder denne featuren). 3. **Architecture context** — relevant utdrag fra fase 3 ADRer (datamodell, API-kontrakt, mønster å følge). **Maks ~10–15 linjer** — ikke lim inn hele arkitektur-brief-en. 4. **Design-system tokens** — relevant subset fra fase 4 for denne featurens UI-overflate (eller, hvis fase 4 er tom: relevante HIG/Material-pekere fra domain-pack `conventions.md`). 5. **Domain-pack-utdrag** — relevante deler av `00-context/domain-pack-{name}.md`-snapshotet (iOS-konvensjoner, App Store-checklist-items, gotchas) som gjelder denne featuren. **Aldri merket "domain-pack-generert"** — det er bare kontekst. 6. **Research signals** — 2–3 mest relevante punkter fra fase 2-research (hvis relevant). To-fil-splittet speiler BMAD: `brief.md` er det Voyage MÅ honorere (kontrakten); `context.md` er det Voyage trenger for å forstå kontrakten. Voyage leser begge, men er bundet kun av Success Criteria i `brief.md`. Avviker Voyage fra dem, er det en handover-feil sporbar til briefen. ### Annotering før handover (R-restpunkt 2 — lett variant) Hvis operatøren reviewer en `brief.md` og vil annotere før handover: bruk **samme review-gate som for interne briefer** — `annotate.mjs` mot artefakten, annoter i HTML-en, Copy Prompt, AI applisere, `revision` bumps (se § Cross-cutting: Review-gate mellom faser). *(Justert 2026-08-10 — A1/R-01.)* Den tidligere teksten foreskrev **Voyages anchor-format (Handover 8)** for fase 7-briefer spesifikt: ``-kommentarer, `ANN-NNNN`-IDer og `annotation_digest` (16-hex SHA-256 over sortert `source_annotations`). **Handover 8, `/trekrevise` og anchor-/revisjonsbibliotekene ble slettet i Voyage v5.0.0** (2026-05-12). Ingen Voyage-versjon konsumerer lenger de kommentarene eller den digesten — å produsere dem er ren støy i en fil som overleveres. S5-beslutningen om «to nivåer» (lett internt, Voyage-presist på fase 7) faller derfor bort: det er **én** gate-mekanikk, den lette, for alle briefer. **Transisjon:** Brief overleveres til Voyage. app-creators fase 7 er ferdig for den featuren. Voyage tar over. Når Voyage returnerer (plan/review), oppdateres feature-status i features-brief; `voyage_run.md` i feature-mappa skrives av state-eksport. Hvis review avslører behov for arkitektur-/constraint-endringer → backtrack til fase 3 eller 5 (revision-bump). --- ## Cross-cutting: state.json `[justert 2026-05-11 — domain_pack, skipped-reasons, session-felt]` ```json { "app_slug": "fitness-tracker", "created": "2026-05-10", "domain_pack": "ios-app@0.1.0", "mode": "full", "current_phase": 6, "phase_status": { "1": "complete", "2": { "status": "skipped", "reason": "ingen research-temaer som driver arkitektur" }, "3": "complete", "4": { "status": "skipped", "reason": "early stage, ingen andre brukere — trigges på bruk hvis det blir behov" }, "5": "complete", "6": { "status": "pending-review", "revision": 0, "sidecar": "06-features-brief.review.md", "blocking": [7] }, "7": "not-started" }, "briefs": { "01-app-brief.md": "complete", "03-architecture-brief.md": "complete", "05-constraints-brief.md": "complete", "06-features-brief.md": "in-progress" }, "feature_summary": { "total": 12, "brief_pending": 8, "brief_written": 2, "voyage_running": 1, "voyage_complete": 1, "shipped": 0 }, "session": { "current": "S12-fase6-backlog", "next_action": "Operatør approver F-007-prioritet, så generer feature-briefer for F-001..F-003", "log": [ "S10: fase 3 arkitektur — 4 ADRer vedtatt, 2 åpne AQ", "S11: fase 5 constraints mot domain-pack-checklist", "S12: fase 6 backlog — 12 features + 2 F-T, dependency-graf tegnet" ] }, "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" } ], "last_activity": "2026-05-10T14:32:00Z" } ``` `phase_status`-verdier er enten en string eller et objekt med utvidet form — **enum og objektformer står i § `phase_status` — én autoritativ enum**, som er eneste kilde. Gjenta dem ikke her. `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-14 — friksjon #15; Voyage annotate.mjs adoptert 1:1]` 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 **gjenbrukt fra Voyage** (`scripts/annotate.mjs` — per-artefakt annoterings-HTML). *(Justert 2026-08-10 — A1/R-01: den tidligere formuleringen viste til `/trekrevise` og Handover 8. Begge ble **slettet i Voyage v5.0.0** (2026-05-12) sammen med `playground/`; `annotate.mjs` er erstatningen og det eneste som finnes. Merk at annotate.mjs er en Voyage-**intern** fil utenfor Handover 1 — se sti-regelen under, og vendoring-beslutningen i masterplan D7.)* ### 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. ### Annoterings-mekanikk (Voyage-mønsteret) App-creator adopterer Voyage `scripts/annotate.mjs` direkte uten egen implementering. Mekanikken: 1. **AI-side:** etter at fase n-brief er skrevet, kjør Voyage-scriptet mot artefakten: ``` node ~/.claude/plugins/cache/ktg-plugin-marketplace/voyage//scripts/annotate.mjs ``` **Sti-regel** *(A1/R-05, 2026-08-10)*: installerte plugins ligger under `~/.claude/plugins/**cache**////`. Den tidligere dokumenterte stien (`…/plugins/marketplaces/ktg-plugin-marketplace/plugins/voyage/…`) **finnes ikke** — den ga `ENOENT`. Slå opp nyeste versjon før bruk (`ls ~/.claude/plugins/cache/ktg-plugin-marketplace/voyage/`) i stedet for å hardkode et versjonsnummer; katalogen inneholder flere versjoner samtidig. Dette er en Voyage-intern fil uten kontraktsvern — Voyage har slettet interne flater med én dags varsel før. Strukturell fiks (vendore en kopi inn i app-creator) er masterplan **D7**, operatør-beslutning. Det produserer `.html` ved siden av kilde-fila (single-file, zero deps, lokal). HTML-en rendrer markdown som en ordentlig artikkel (overskrifter, lister, kodeblokker — ikke rå-tekst), med `data-anchor-id` på hvert annotérbart element. 2. **Operatør-side:** operatør åpner HTML-en i nettleser (`file://`-lenke), velger tekst eller klikker et element, velger intent (Fiks / Endre / Spørsmål), skriver kommentar, lagrer. Annotasjoner persisterer i nettleserens localStorage (keyed på absolutt fil-sti). 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`, og skriv ny revisjons-entry i **sidecaren** `.revisions.md` (fase 7: `features/{NN}-{slug}/revisions.md`) — ikke i artefakten selv. ### Vokabular (arvet fra Voyage) | Intent | Norsk | Når brukes | |--------|-------|------------| | **Fiks** | direkte korrigering | Faktafeil, typo, dårlig formulering. AI fikser uten ny diskusjon. | | **Endre** | struktur-/innholds-endring | Featuren skal endres, droppes, utsettes; arkitektur-beslutning revurderes. AI applisere; konsekvenser oppstrøms/nedstrøms flagges. | | **Spørsmål** | klargjøring trengs | Operatør trenger AI-svar før beslutning. AI svarer i neste sesjon; ny annoterings-runde for endelig beslutning. | Vokabularet er **tre-tier** (lavnivå-Fiks → mellomnivå-Endre → høynivå-Spørsmål), ikke fem-tier fast taksonomi (approved/revise/defer/drop/question). Forskjellen er bevisst: Voyage-vokabularet er fri-form innenfor intent (kommentar bestemmer hva endringen er), ikke type-strukturert. Det matcher hvordan operatør faktisk tenker — "drop F-006" er en Endre-annotasjon med kommentar "drop fra v1", ikke en separat `drop`-status. ### Eksempel — operatør-flow (fase 6 review) 1. Åpne `06-features-brief.html` (file://-lenke fra app-instansens `index.html`). 2. Bla til F-006-seksjonen. Klikk overskriften "F-006: Daglig HVORFOR-forsterkning". 3. Popover åpnes. Velg **Endre**. Skriv: "Drop denne featuren fra v1. Kuratert daglig YouTube-lenke føles som tvunget innhold; trenger ny vinkling som ikke binder appen til Sadhguru-kilder." 4. Klikk Lagre. Annotasjonen vises i sidebar gruppert under "Backlog". 5. Bla til F-002. Velg `.timeSensitive`-setningen i Goal-paragrafen. Velg **Endre**. Skriv: "Trim til `.active` for v1. `.timeSensitive`-entitlement-søknad er overkill — flytt til v1.1+-kandidat." 6. Bla til F-001. Klikk Goal-paragrafen. Velg **Spørsmål**. Skriv: "Skal AQ-001-research-arbeidet skje i app-creator's `research.md` eller flyttes til Voyage `/trekresearch`?" 7. Klikk **Copy Prompt** i topbar. Strukturert markdown kopieres til clipboard. 8. `/clear` i Claude (eller start ny sesjon). Re-entry er instansens `STATE.md` § «👉 NESTE — START HER», som injiseres automatisk — ingen prompt-fil å peke på. Lim inn den kopierte annoterings-prompten når sesjonen er i gang. ### Applisering — AI-side AI parserer annotasjons-prompten (Voyage-format: H2-overskrifter per seksjon, bullet-entries med intent + sitat + kommentar). For hver Endre/Fiks: - **Endre på element**: erstatt element i kilde-artefakten per kommentar. Bumpe revisjon. - **Endre på seksjon**: omskriv hele seksjonen per kommentar. - **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` og oppdater `last_modified` i kilde-artefakten, og skriv revisjons-entryen i **sidecaren** — `.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.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). - F-002 notifications: REVIDERT. Endre-annotasjon: ".timeSensitive trim til .active for v1". Endring: Goal-seksjon + Preferences-seksjon. Konsekvens oppstrøms: constraints-brief § .timeSensitive-entitlement re-revideres. - F-001 sun-position: SPØRSMÅL. AQ-001-handling-spørsmål mottatt; svar gitt i [responsfila]. Avventer ny annotasjons-runde. - Andre features: GODKJENT (ingen annotasjoner mottatt). ``` Hvis ytterligere runder trengs: ingen ny sidecar — operatør re-åpner samme HTML, gjør nye annotasjoner (localStorage husker forrige runde, men kan ryddes). Copy Prompt → ny runde. ### 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/-/`: 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/-/`; 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]` Når en senere fase avdekker behov for endring i en tidligere brief: 1. Bump `revision` i brief-frontmatter (`0` → `1`). 2. Sett `revision_reason` til kort beskrivelse. 3. Oppdater `last_modified`. 4. Oppdater referanser i nedstrøms briefer hvis kontrakter har endret seg. 5. Hvis features-brief har features avhengig av forrige form: marker dem `revision-pending` til de er reviderte. For allerede-skrevne fase 7-`brief.md`/`context.md`: bump deres `revision`, sett `voyage_run_status` til `stale` hvis Voyage allerede kjører på den. Den eksakte backtracking-propagerings-mekanikken (hvordan en fase 3-endring forplanter seg til allerede-skrevne feature-briefer) er fortsatt `[åpent]` — Akashic vil avsløre den når en backtrack faktisk skjer. Mønsteret er inspirert av Voyages annoterings-revisjons-mekanisme (`annotate.mjs`), ikke en kopi. ## Cross-cutting: attention-generering `[hypotese]` Heuristikker for "trenger oppmerksomhet": fase incomplete uten aktivitet siste 7 dager; brief uten `phase_status: complete` etter at fasen burde være ferdig; feature uten prioritet etter at features-brief er complete; brief-written feature uten Voyage-run startet; Voyage-run-status `review-pending` / `blocked`; constraint-konflikt avdekket senere; dependency-konflikt i features-brief; brief revisjon-pending; skippet fase uten begrunnelse (manglende `reason`-felt). Låses ikke nå — prototypen avslører hvilke heuristikker som er nyttige vs støy. ## Hva dette utkastet IKKE dekker - **Eksakte AI-prompts.** Hvilke spørsmål AI stiller i fase 1, hvordan AI rammer arkitektur-alternativer i fase 3 — låses ikke før prototypen viser hva som virker. - **Implementasjons-detaljer.** Hooks, scripts, HTML-rendering, en eventuell `/app-creator`-command — separate dokumenter etter prototype. - **Backtracking-propagerings-mekanikk i detalj.** Hvordan fase 3-endringer forplanter seg til allerede-skrevne feature-briefer — `[åpent]`. - **Innebygd flersesjons-orkestrator.** Mønsteret er dokumentert + lett state-felt; en innebygd `trekcontinue`-aktig mekanikk vurderes først hvis prototypen viser at den manuelle protokollen ikke holder. - **Multi-platform-apps.** Utkastet antar én plattform per app-creator-instans (= én domain-pack). Universal apps eller iOS+watchOS er `[åpent]`. - **Branching i feature-derivasjon.** Hva skjer hvis en feature spinnes opp basert på A/B-test eller eksperiment — `[åpent]`. - **Versjonering av app-creator-instans.** "v2 av samme app" / redesign-faser — `[åpent]`. - **Domain-pack-spec i detalj.** Egen fil: `domain-pack-spec.md`. - **Andre brief-typer.** Eventuelle deployment- eller validation-briefer som senere viser seg verdt å ha — `[åpent]` for v0.5.0+. ## Når dette utkastet skal oppdateres - **Etter Akashic fase 2–6:** revisjons-merking på hver fase som faktisk kjøres; `[hypotese]` → `[testet]` eller `[justert YYYY-MM-DD]`. - **Etter første feature-brief gjennom Voyage:** låsing av fase 7-formatet mot Handover 1 (forutsetter round-trip-test som passerer strict mode). - **Etter at fase-overhead-tid er målt i Akashic-kjøringen (R17):** faser som tar timer og produserer artefakter ingen Voyage-brief refererer = bevist seremoni → kandidater for å bli skippbare-by-default eller fjernes. - **Etter første feature shipped:** end-to-end-validering av hele pipelinen. - **v0.4.0 lock:** alt som har overlevd reell bruk får `[testet]`-merking; resterende `[hypotese]`/`[åpent]`-felt forblir åpne for v0.5.0+. Dette utkastet er starten. Prototypen er testen.