open/app-creator
1
0
Fork 0
Code Issues Releases Activity

design(app-creator): S13 oppdatering — adoptér Voyage annotate.mjs 1:1

Browse source 
Etter at operatør pekte på at Voyage allerede løser review-gate-mekanikken
i scripts/annotate.mjs (claude-code-100x-mønster — pencil-toggle, Fiks/Endre/
Spørsmål-intent, popover-form, localStorage-persistens, Copy Prompt-eksport):
forkastet egen-spec'd sidecar-format, adopterte Voyage 1:1.

phase-design-draft.md § Cross-cutting: Review-gate omskrevet:
- Forenklet fra fem-tier fast taksonomi (approved/revise/defer/drop/question)
  til Voyages tre-tier fri-form intent (Fiks/Endre/Spørsmål med fri kommentar).
- Mønsteret matcher hvordan operatør faktisk tenker — 'drop F-006' er en
  Endre-annotasjon med kommentar, ikke en separat drop-status.
- Konkret CLI-kall: node ~/.claude/.../voyage/scripts/annotate.mjs <brief.md>
  → produserer <brief>.html ved siden av kilde.
- Eksempel-flow for operatør (fase 6 review).
- Applisering-mekanikk på AI-side: parse Copy Prompt-format, applisere Fiks/
  Endre, svare på Spørsmål, bump revisjon, skriv revisjons-logg.

friksjon.md #15 utvidet med adopsjon-note:
- Bekrefter app-creator-invariant 'Voyage v4.3 er arkitektonisk forfar — gjenbruk
  disse 1:1' fra app-creator/CLAUDE.md.
- Pedagogisk friksjon: første utkast bygde egen-spec uten å sjekke Voyage først.
  Loggført som lærdom — sjekk Voyage-mønster FØR egen-spec for review-/audit-/
  annoterings-mekanikk.

Akashic-side (separat repo, separat commit): slettet sidecar-maler, generert
.html via annotate.mjs, oppdatert index.html med HTML-knapper, .gitignore,
state.json, attention-entries.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-05-14 10:55:54 +02:00
commit eba584515a
2 changed files with 45 additions and 49 deletions
Download patch file Download diff file Expand all files Collapse all files

92
docs/phase-design-draft.md
View file

@ -933,79 +933,73 @@ 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 | 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]`
## 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 strukturelt analogt med Voyages `/trekrevise` (Handover 8 — operatør-annotert brief/plan/review back into source artifact).
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 1:1 fra Voyage** (`scripts/annotate.mjs` + `/trekrevise`-flyten, Handover 8).
### 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
### Annoterings-mekanikk (Voyage-mønsteret)
Operatør annoterer i en sidecar-fil ved siden av hovedartefakten:
App-creator adopterer Voyage `scripts/annotate.mjs` direkte uten egen implementering. Mekanikken:
| 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` |
1. **AI-side:** etter at fase n-brief er skrevet, kjør Voyage-scriptet mot artefakten:
```
node ~/.claude/plugins/marketplaces/ktg-plugin-marketplace/plugins/voyage/scripts/annotate.mjs <brief.md>
```
Det produserer `<brief>.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.
Sidecar-fila committes sammen med revisjonen den driver (audit trail). Etter applisering kan sidecaren beholdes (audit) eller arkiveres til `archive/`-undermappe — operatør-valg.
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).
### Annoterings-vokabular
3. **Overlevering:** operatør klikker "Copy Prompt" — den genererer strukturert markdown med alle annotasjonene gruppert per seksjon, og kopierer til clipboard.
Fast vokabular per anker-element (per feature, ADR, constraint, success-kriterium, …):
4. **Applisering:** operatør limer prompt-en inn i Claude i neste sesjon. AI parserer annotasjons-blokker og applisere endringer i kilde-artefakten. Bumpe `revision: N → N+1`, oppdater `last_modified`, skriv ny `## Revisjons-logg`-seksjon på slutten av artefakten.
| 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) |
### Vokabular (arvet fra Voyage)
### Eksempel-entry (fase 6 sidecar)
| 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. |
```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.
```
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.
```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).
```
### Eksempel — operatør-flow (fase 6 review)
```markdown
### F-001 sun-position
status: approved
```
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, start neste sesjon med "Les og følg NEXT-SESSION-PROMPT.local.md nøyaktig". Lim inn prompten når Claude ber.
### Applisering
### Applisering — AI-side
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:
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`, oppdater `last_modified`, skriv `## Revisjons-logg`-seksjon på slutten av kilde-artefakten:
```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.
### 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).
```
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`.
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

2
prototype-run/friksjon.md
View file

@ -478,6 +478,8 @@ Prosess-/spec-merknader fra S12 (ikke nummererte friksjons-poeng):
**Drahjelp fra Voyage-mønster:** `~/.claude/plugins/marketplaces/ktg-plugin-marketplace/plugins/voyage/commands/trekrevise.md` (kommando-spec) og `voyage/docs/HANDOVER-CONTRACTS.md` § "operatør-annotert brief/plan/review back into source artifact" — bør leses og adopteres strukturelt. App-creator implementerer ikke `trekrevise`-kommando, men adopterer mønsteret (anchored comments + canonical annotation_digest + revision in-place).
**Adopsjon i S13 (oppdatert 2026-05-14):** Etter at operatør pekte på at Voyage `scripts/annotate.mjs` (921 linjer, claude-code-100x-mønster — pencil-toggle, Fiks/Endre/Spørsmål-intent, popover-form, localStorage-persistens, Copy Prompt-eksport) **allerede løser** review-gate-mekanikken: forkastet egen-spec'd sidecar-format (`<artefakt>.review.md` med approved/revise/defer/drop/question-vokabular per anker), adopterte Voyage `annotate.mjs` 1:1 i stedet. Konsekvens for `phase-design-draft.md` § Cross-cutting: Review-gate: forenklet fra fem-tier fast taksonomi til tre-tier fri-form intent (Fiks/Endre/Spørsmål med fri kommentar). Voyage-mønsteret matcher bedre hvordan operatør faktisk tenker — "drop F-006" er en Endre-annotasjon med kommentar "drop fra v1", ikke en separat `drop`-status. Generering: `node ~/.claude/.../voyage/scripts/annotate.mjs <brief.md>` produserer `<brief>.html` ved siden av kilde-fila. HTML-filer er gitignored i Akashic-repoet (regenererbare, annotasjoner lever i localStorage). Dette er konkret anvendelse av app-creator-invarianten "Voyage v4.3 Plugin Playground er arkitektonisk forfar — app-creator gjenbruker disse 1:1" fra `app-creator/CLAUDE.md`.
**Fase-overhead-implikasjon:** Hvert fase-overgang får +1 review-runde (estimert 20-40 min operatør-tid + 10-20 min applisering-tid). For Akashic: 6 ferdige fase-artefakter (1, 2, 3, 5, 6, 7 F-001) → ~2-3 t retroaktiv review-arbeid hvis alle skal gjennomgås. Fremover: hver ny fase 7-feature får én review-gate (~30-60 min ekstra per feature × 12 gjenværende = 6-12 t). Dette er reell kost — men feilen av å hoppe over review (bygge på u-validert backlog) er større.
---