Curation v2: progress handoff and per-step agent briefs

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A1rCLQeKBgnBo3oTgHuTMe
2026-09-02 04:16:59 +00:00
parent 8b51454c20
commit 76527e3821
9 changed files with 653 additions and 0 deletions
@@ -0,0 +1,52 @@
+# Implementation agent brief — The Daily EPUB, "Personalized Curation v2"
+
+You are implementing ONE step of a multi-step plan in the Rust repository at
+`/home/thallada/workspace/the-daily-epub` (branch `curation-v2`, already checked out).
+
+The orchestrator hands you `docs/plans/curation-v2-briefs/00-preamble.md` (this file) followed by one
+`stepN.md` from the same directory; `docs/plans/2026-09-02-curation-v2-progress.md` records what has
+landed so far.
+
+The plan is `docs/plans/2026-09-02-personalized-curation-v2.md`. Read it in full before
+writing code: §0 records settled decisions (do not reopen them), §1 lists the files to
+read first, §21 is the implementation sequence. Also read
+`docs/plans/2026-08-15-implementation-notes.md` §"Cross-cutting implementation decisions"
+(note: item 5 is stale — the code uses a hand-rolled `reqwest` client in `src/curate/llm.rs`,
+keep that).
+
+## Hard rules
+
+- Implement ONLY the step assigned below. Later steps land separately; do not start them.
+  Where this step needs a type or table that a later step fills in, create it now exactly as
+  the plan specifies and leave it empty/unused with a short `// filled in by step N` comment.
+- Conventions: sqlx *runtime* queries (`sqlx::query(...).bind(...)`, never the `query!` macros),
+  `jiff` for time, RFC3339 UTC strings in SQLite, `thiserror`/`anyhow` error style, no `unwrap()`
+  outside tests, tracing spans per stage, rustfmt defaults, askama templates.
+- Tests never touch the network. Use mock backends following `MockBackend` in `src/curate/llm.rs`.
+- Follow the plan's names for modules, functions, config keys, table and column names, enum
+  strings and prompt constants exactly. If the plan is internally contradictory or impossible
+  for this step, pick the closest behaviour, keep the paper publishable, and describe the
+  deviation in your final report. Do not invent scope beyond the plan.
+- API keys only from env vars; never in config files, logs, tests or the database.
+- Prefer existing dependencies in `Cargo.toml`. Add a new crate only if there is no reasonable
+  way without it, and say so in the report.
+- Do NOT commit and do NOT create branches. Leave all changes in the working tree; the
+  orchestrator reviews and commits. Do not edit anything under `docs/`.
+- Keep `config.example.toml` and README in sync with any config keys you add or remove
+  (the test `shipped_example_config_parses` must pass).
+- Before finishing, run and make pass: `cargo fmt`, `cargo clippy --all-targets` (no new
+  warnings), `cargo test`. Fix what you broke; do not delete or `#[ignore]` tests to get green
+  unless the plan removes the feature they cover (then move/replace the tests as §18 says).
+
+## Final report
+
+End with a concise report (this is what the orchestrator reads): what you implemented, every
+deviation from the plan and why, anything from the step you could not finish, and the exact
+`cargo test` summary line(s). Keep it under 60 lines.
+
+## Host quirk (important)
+
+On this machine the built-in `apply_patch` tool's filesystem helper fails with
+`bwrap: ... Operation not permitted`. Do not keep retrying it. Edit files through shell commands
+instead (the `apply_patch` CLI invoked from bash works, as do `python3 - <<'EOF'` rewrite scripts,
+`sed -i`, and heredocs). Shell commands, `cargo build`, `cargo test` and `cargo clippy` all work.