# Common instructions for every STTracker implementer (binding)

You implement one task of the STTracker Phase 1 plan. STTracker is a Bun 1.3 + TypeScript self-hosted media tracker.

## Read first
1. Your task brief, whose path is given in your dispatch. It is your requirements; use its exact values verbatim.
2. `AGENTS.md` at the repo root (rules).
3. The "Global constraints" section of `docs/plans/001-phase1-own-your-data.md`. Read only that section, not the whole plan.
4. Only the spec sections your brief cites: `docs/specs/001-sttracker-v1-design.md`.

## Workspace
- If you were started in a git worktree, work there. First run `bun install --frozen-lockfile`. Never modify `package.json` or `bun.lock`: every approved dependency is already installed. If you truly need another one, report NEEDS_CONTEXT.
- If not in a worktree, work in `/home/user/STTracker` on branch `feat/phase1`.
- Never commit to `main`. Commit messages use Conventional Commits and end with the line:
  `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>`

## Facts from earlier tasks
- `@sttracker/db/db`: `createDb(url)` → `Db { k: Kysely<Database>; dialect: "sqlite"|"postgres"; close() }`.
- `@sttracker/db/ids`: `newId()` (UUIDv7) and `nowIso()`.
- `@sttracker/db/json`: `toJson()` and `fromJson(s, fallback)`.
- `@sttracker/db/migrate`: `migrateToLatest(db)`.
- `@sttracker/db/testing`: `forEachDialect(name, getDb => …)` gives each test a fresh, migrated DB.
- `@sttracker/core/errors`: `AuthError(code)`, `ValidationError(field, reason)` (code "validation"), `CryptoError`, `ImportError(code)`, `NotFoundError(what)` (code "not_found").
- Kysely 0.29: import `Migration`/`Migrator` from `kysely/migration`.
- **Inside a transaction always use the `tx` handle, never `db.k`.** SQLite runs on one connection behind a mutex, so calling `db.k` inside a transaction deadlocks.
- Packages import each other by path (`@sttracker/core/entries`). There are no barrel `index.ts` files.

## Testing
- TDD: failing test first, watch it fail (RED), minimal code, watch it pass (GREEN).
- DB tests must pass on both databases:
  - `bun test <path>` (SQLite);
  - `TEST_POSTGRES_URL=postgres://postgres:postgres@127.0.0.1:55432/postgres bun test <path>` (Postgres; the server is running).
- Tests never touch the network.
- `bun run typecheck` must be clean before your final commit.
- Output must be pristine (no stray warnings or logs).

## You do not dispatch subagents
Do all the work yourself. Never spawn helpers or reviewers. Review happens after you report.

## If stuck
Report BLOCKED or NEEDS_CONTEXT with specifics. Bad work is worse than no work. If something in the brief contradicts these instructions or the spec, ask rather than guess.

## Report
Write the full report to the report path given in your dispatch. Include:
- what you built;
- files changed;
- TDD evidence: the RED command and output, and the GREEN command and output, on both DBs where relevant;
- typecheck output;
- self-review findings;
- concerns.

Your final reply must be ONLY (under 15 lines):
- **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT;
- commits (short SHA + subject);
- the branch name you committed on;
- a one-line test summary;
- concerns;
- the report path.