# 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-30: Product design decisions recorded in spec 001
**Status:** accepted
**Context:** Brainstorming with the owner produced the v1 design.
**Decision:** See `docs/specs/001-sttracker-v1-design.md` §13 for the designer's calls. Owner decisions:
- Phase 1 is read-only.
- Write-back is opt-in per connection.
- Conflicts between sources go to the Changes inbox.
- Backloggd waits for its official export.
- The app UI is Hardcover-style; the public page is scrapbook + river.
**Alternatives:** Recorded in the spec.
**Consequences:** Phase 1 has no `push` implementations.

## 2026-10-30: Bun workspaces monorepo with Kysely for both databases
**Status:** accepted
**Context:** The owner requires Bun with SQLite and Postgres options.
**Decision:**
- Bun workspaces (`apps/*`, `packages/*`, `plugins/*`).
- Kysely is the single query layer, with portable migrations.
- SQLite runs through `bun:sqlite` and Postgres through `Bun.sql`.

**Alternatives:**
- Drizzle needs a separate schema per dialect.
- Prisma does not fit Bun-native drivers.
- Raw SQL would duplicate every query per dialect.

**Consequences:** We may need a small custom Kysely dialect for `Bun.sql` or `bun:sqlite`. Every DB test runs on both databases.

## 2026-10-30: 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` and `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 locations override the superpowers default paths.

**Alternatives:**
- Per-tool rule files: they drift and create synchronisation debt.
- No rules file: agents re-explore the repo every session, which is measurably slower and costs more tokens.

**Consequences:** Rule changes happen in one file, and the 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.