Create/update implementation plan using beads.

Source: `src/*`
Specs: `specs/*.md`
Goals: `README.md` (scope and non-goals)
Guidance: `docs/*` (non-spec examples)
Shared lib: `src/lib/*`
Issues: Use `bd` commands to manage tasks

## BLIBIO CONTEXT

- Go service + CLI (`cmd/blibio/main.go`).
- Most code in `internal/*`; public surface (if any) in `pkg/*`.
- Runtime concerns: config, database/migrations, queue/worker, HTTP server/handlers, preprocess, llm, qipu, otel.
- Frontend assets in `web/static/*`.
- Prefer `make test` / `go test ./...` for verification.

## TRUST HIERARCHY

1. Code is truth. Specs/docs may be stale or wrong.
2. Tests prove behavior. Read test files to verify claims.
3. Existing plan may be inaccurate. Validate every "complete" item.

## AUDIT PROCESS

For each spec:
1. Read spec requirements
2. Search code for implementation (grep patterns, function names)
3. Check test coverage exists, passes, and evaluate gaps (see TEST COVERAGE EVALUATION)
4. Compare actual behavior vs spec claims
5. Note gaps with file:line references

After auditing specs, evaluate ALL already-implemented functionality for test coverage gaps:
- Run `cargo test --coverage` or `cargo t` and analyze output
- Map every public function to its test coverage
- Create beads for missing unit, integration, and e2e tests
- Label by type: `test-unit`, `test-integration`, `test-e2e`

Before creating new issues, review blocked beads for stale dependencies:
- Run `bd list --label blocked --limit 0` and verify each is still truly blocked

Also review blocked work for stale deps:
- Run `bd blocked` and verify each blocker still exists and is the real constraint
- If a blocker is resolved or no longer relevant, remove/replace the dependency link and update labels/status

Only audit **active** specs (`docs/specs/*.md`). Skip `docs/specs/planned/` — those are drafts with open questions, not implementation targets. If a planned spec becomes actionable, move it to `docs/specs/` first.

Use subagents in parallel - one per active spec. Each must:
- Read the spec file
- Search src/ for implementation
- Search tests/ for coverage
- Report: implemented (with refs) | partial (what's missing) | not implemented

As you learn new facts during the audit, continuously maintain the backlog:
- Reprioritize when impact changes (`bd update <id> --priority ...`)
- Fix stale status/labels: unblock when deps resolved; block when real deps discovered
- Keep dependency graph current (add/remove blockers) so `bd ready` matches reality
- **Remove stale/invalid issues**: close with `bd close <id>` when a task is obsolete, duplicated, or no longer applies (spec removed, feature dropped, superseded by different approach). Add a brief reason.

## WHAT TO LOOK FOR

- TODO/FIXME/unimplemented! in code
- #[ignore] or skip in tests
- Hardcoded/simulated behavior (scaffolds that don't do real work)
- Spec says X, code does Y (mismatches)
- Flag defined in CLI but handler is no-op
- Strategy/option not wired through
- Empty match arms or unreachable branches
- Panics/unwraps hiding incomplete error handling

## TEST COVERAGE EVALUATION

For each implementation found during audit:
1. Identify what tests exist: unit (`*_test.go` in same package), integration (cross-package/component), e2e (full pipeline)
2. Check test coverage: run `cargo test` or check test output
3. Map functionality to test files - every public function should have tests
4. Create beads for missing coverage:
   - Unit tests: test individual functions/components in isolation
   - Integration tests: test component interactions (DB, queue, LLM, external APIs)
   - E2E tests: test full request flows through the system
5. Use `--priority 2` for all coverage gaps
6. Label by test type: `test-unit`, `test-integration`, `test-e2e`
7. Include function names and file refs in issue body

## PRIORITY DEFINITIONS

- **P1: Correctness bugs** - Code exists but doesn't match spec behavior
- **P2: Missing test coverage** - Feature works but lacks tests
- **P3: Feature work** - New capability / enhancement (impact-based; not about readiness)
- **P4: Idea / low-urgency** - Nice-to-have / polish / speculative

## STATUS VS PRIORITY (DON'T MIX)

Priority answers "how important/urgent?". Status/labels answer "can we do it now?".

- **blocked**: not actionable due to explicit dependency (human decision, external setup, infra).
- **P3/P4**: priority levels, not synonyms for blocked.

## CATEGORIZATION

Every spec item must be in exactly one place:
1. **Code** - Implemented and tested
2. **Beads (P1-P2)** - Ready to implement (use `bd create`)
3. **Beads (P3-P4)** - Anything not already shipped/tested

Sequencing/readiness lives in status/labels:
- Spec says optional/future/v2: label `future` + use dependencies if blocked (priority still P3/P4 by value)
- Spec ambiguous: label `design`/`clarify` and `blocked` (dependency: decision)
- Depends on infra/external: label `infra`/`external` and `blocked` with explicit deps

Default handling (separate concepts):
- **Blocked**: keep issue open, add explicit dependency (so it stays out of `bd ready`)
- Labels to express why: `design`, `clarify`, `draft`, `blocked`, `external`, `future`, `distribution`, `infra`
- When it becomes actionable: resolve/unblock deps and update labels as needed

## DEPENDENCY CLASSIFICATION

When filing issues, explicitly model blockers so `bd ready` stays clean.

- **Human decision** (design/UX/API): create a separate issue labeled `design`/`blocked` and link it as a blocker.
- **External setup** (accounts/credentials/infra): create a separate issue labeled `external`/`infra`/`blocked` and link it as a blocker.

Link with:

```bash
bd dep add <blocker-id> --blocks <impl-id>
```

If a dependency relationship is wrong/stale, update it (remove/replace blockers) so `bd ready` reflects reality.

## OUTPUT

Create beads issues using `bd create`:
- Use `--priority 1` for P1 correctness bugs
- Use `--priority 2` for P2 test coverage gaps
- Use `--priority 3` for P3 feature work
- Use `--priority 4` for P4 future/ideas (if unsupported, use priority 3 + label `future`)
- Use `--label blocked` for items with dependencies
- Use `--label design` for items needing design work
- Include file:line refs in issue body
- Use `bd dep add <issue-id> --blocks <blocked-issue-id>` for dependencies

For P3 items that should not be worked now: add a dependency that blocks them, or label them `future` to indicate they're not yet actionable.

Update @specs/README.md status table:
- Spec/Impl/Tests columns with ✅/⚠️/❌
- Notes column for key gaps
- Update "Last audited" date

Run `bd sync` to save changes to git.

## RULES

- Plan only. No code changes.
- Never trust docs. Always verify in code.
- Never assume missing; confirm with code search first.
- Include file:line refs for all claims.
- Use `bd create` to track all gaps found during audit.
- Check existing issues with `bd list` before creating duplicates.
- Close issues that are obsolete, duplicated, or no longer relevant (`bd close <id>`). Pruning stale work is as important as filing new work.
- If a needed feature has no spec, create specs/FILENAME.md first.
- Prefer shared utilities in `src/lib/` over ad-hoc implementations.
- Every spec requirement must be tracked: code or beads issue.
- Update issue priority/labels with `bd update` as readiness changes.
- Run `bd sync` after creating issues.

**COMPLETE**: Emit exactly one line: `COMPLETE` (uppercase, no punctuation, no surrounding text) ONLY when the audit finds zero gaps, zero stale issues, zero plan/backlog updates, and this run made zero file changes. Finishing a planning pass is a successful run, not COMPLETE.
