51 lines
3.3 KiB
Markdown
51 lines
3.3 KiB
Markdown
# Decisions
|
|
|
|
Append-only. Never edit or delete an entry — supersede it with a new one that links back.
|
|
One entry per decision a future maintainer would otherwise have to reverse-engineer.
|
|
No index: `grep -n '^## ' docs/DECISIONS.md` lists every entry (date, title, line number).
|
|
|
|
## 2026-10-23 — Mockups are committed and served, not throwaway
|
|
**Status:** accepted
|
|
**Context:** The agent-repo playbook keeps mockups gitignored in `design/mockups/`, never wired into the app.
|
|
Spec 001 asks for 7 design-direction mockups that run in the Docker image for the maintainer to compare.
|
|
**Decision:** (maintainer decision) Mockups live in `src/mockups/NN-slug/`, are committed, served by the
|
|
Bun server and covered by route smoke tests. Mockup agents edit only their own folder.
|
|
**Alternatives:** Gitignored `design/mockups/` (can't ship in the image or be reviewed from the remote).
|
|
**Consequences:** Mockup code is in the bundle and the history; when a direction is chosen, the unused
|
|
mockups need an explicit removal decision (`docs/TODO.md`).
|
|
|
|
## 2026-10-23 — Production bundle runs from `dist/`
|
|
**Status:** accepted
|
|
**Context:** With Bun 1.3.14, a `--production` bundle of HTML imports resolves its assets relative to the
|
|
current working directory; `bun dist/server.js` from the repo root throws "Bundled file … not found".
|
|
**Decision:** `bun run start` is `cd dist && bun server.js`; the Docker runtime stage uses `WORKDIR /app/dist`.
|
|
**Alternatives:** Not recorded (e.g. `--asset-naming`/`naming` options were not explored).
|
|
**Consequences:** Any new run script or deploy target must set the cwd to `dist/`.
|
|
|
|
## 2026-10-23 — Bun only, self-contained assets
|
|
**Status:** accepted
|
|
**Context:** Spec 001 constraints.
|
|
**Decision:** Bun's own server, bundler and test runner with HTML imports; no Vite/Next. Fonts and three.js
|
|
bundled from npm, no CDN. YouTube as link cards, not embeds. three.js only in the 3D mockups (06, 07).
|
|
**Alternatives:** Not recorded.
|
|
**Consequences:** The image works offline apart from outbound links.
|
|
|
|
## 2026-10-23 — Placeholder lyrics, unverified facts marked
|
|
**Status:** accepted
|
|
**Context:** Lyrics recalled from memory risk inaccuracy, and their copyright question is open.
|
|
**Decision:** Sample data uses clearly marked placeholder lyric lines in the real data shape; any fact,
|
|
story time or Odyssey reference not confirmed carries `// TODO(verify)`.
|
|
**Alternatives:** Real lyrics (deferred by the maintainer).
|
|
**Consequences:** Nothing in `src/data/sample.ts` may be presented as fact-checked.
|
|
|
|
## 2026-10-23 — Adopt AGENTS.md as single source of truth
|
|
**Status:** accepted
|
|
**Context:** Agents had no durable project context and no consistent workflow between sessions.
|
|
**Decision:** `AGENTS.md` is canonical; `CLAUDE.md`/`GEMINI.md` are pointers. Specs are permanent in
|
|
`docs/specs/`. Plans live in `docs/plans/` only while work is in progress and are removed before the
|
|
merge request. Both override the superpowers default paths.
|
|
**Alternatives:** Per-tool rule files (drift, synchronisation debt); no rules file (agents re-explore
|
|
the repo every session — measurably slower and more tokens).
|
|
**Consequences:** Rule changes happen in one file; pointer files must stay thin. Plans are working
|
|
artefacts: kept after merge they go stale and contradict the code, so the spec is the record.
|