Archived
Lucas WintherandClaude Opus 5
def811bab4
Records the outcome of the 001 brainstorm and the Recoll spike that backed it. Decisions: Python + FastAPI managed with uv; the product split into four specs built in order; collections managed at runtime through the API with SQLite as the store of record; indexing as an in-process job queue; search scope as an explicit required parameter; results carrying metadata and snippets; real authentication in 001 with user administration deferred to 004. The load-bearing one is collection membership. A collection cannot be a directory, because files sharing a directory must be able to belong to different collections, so every document is indexed once into a single Recoll index and membership is a user.collection extended attribute mapped to a queryable field. Verified against Recoll 1.43.0 in a throwaway container: the tag must be an opaque single-token ID rather than the collection name, because Recoll tokenises the field value and matches case-insensitively, so a tag of cook-books is also matched by collection:cook and collection:books. Names as tags would let collections silently bleed into each other. Opaque IDs also make renaming free, since the index is never touched. Two operational consequences are recorded in docs/TODO.md: documents must live on a volume with extended-attribute support, checked loudly at startup, and a plain incremental recollindex does not notice xattr-only changes, so retagging must go through recollindex -i on the affected file. uv 0.12.16 was installed on this host as part of the stack decision; AGENTS.md is corrected in the same commit, since it previously listed uv as absent. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
36 lines
1.9 KiB
Markdown
36 lines
1.9 KiB
Markdown
# TODO
|
|
|
|
Durable backlog. Agents append here instead of leaving `TODO` comments in source.
|
|
Small, specific, independently actionable. Remove only when actually done.
|
|
|
|
## Now
|
|
- [x] Answer the six open design questions in `docs/ARCHITECTURE.md` — closed 2026-09-18, reasoning in
|
|
`docs/DECISIONS.md`.
|
|
- [ ] Finish the 001 design: component boundaries and SQLite schema, API surface and error semantics,
|
|
test strategy. Then write `docs/specs/001-search-engine-api.md`.
|
|
- [ ] Fill the `Commands` section of `AGENTS.md` and delete its `TODO(maintainer)` line — must happen in
|
|
the same commit that scaffolds the app, with every command actually run.
|
|
|
|
## Next
|
|
- [ ] Scaffold Python + FastAPI with `uv`; verify install/dev/test/lint/typecheck/build by running them,
|
|
then record the verified ones in `AGENTS.md`.
|
|
- [ ] Dockerfile + compose: Recoll in the image, volumes for documents and indexes.
|
|
- [ ] Startup check: refuse to start, loudly, if the document volume does not support extended
|
|
attributes — without them every scoped search silently returns nothing.
|
|
- [ ] Recover interrupted indexing jobs at startup; they do not survive a process restart on their own.
|
|
- [ ] Write `PRODUCT.md` properly via `/impeccable init` — the current file is a stub from the initial
|
|
brief, not an interview. Blocks spec 002.
|
|
|
|
## Someday
|
|
- [ ] Propose a CI check (Gitea Actions): assert `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` and the `docs/`
|
|
paths exist, and fail if `AGENTS.md` exceeds 150 lines.
|
|
|
|
## Known issues
|
|
- None recorded yet.
|
|
|
|
## Recurring
|
|
- [ ] Add an `AGENTS.md` rule only in response to a real, observed agent failure — one line, ideally with
|
|
a code example. Never pre-empt hypothetical mistakes.
|
|
- [ ] Update `AGENTS.md` in the same commit as the convention it describes. A stale rules file misleads.
|
|
- [ ] Prune quarterly: delete rules whose convention changed or whose mistake no longer occurs.
|