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>
1.9 KiB
1.9 KiB
TODO
Durable backlog. Agents append here instead of leaving TODO comments in source.
Small, specific, independently actionable. Remove only when actually done.
Now
- Answer the six open design questions in
docs/ARCHITECTURE.md— closed 2026-09-18, reasoning indocs/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
Commandssection ofAGENTS.mdand delete itsTODO(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 inAGENTS.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.mdproperly 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.mdand thedocs/paths exist, and fail ifAGENTS.mdexceeds 150 lines.
Known issues
- None recorded yet.
Recurring
- Add an
AGENTS.mdrule only in response to a real, observed agent failure — one line, ideally with a code example. Never pre-empt hypothetical mistakes. - Update
AGENTS.mdin 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.