Merge pull request #12 from cs-util/v9

V9

Author: cs-util

AGENTS.md

@@ -4,14 +4,17 @@
 - You must follow the instructions in the `AGENTS.md` file while working on your task and regularly review if you are still aligned with these instructions and the spec.
 - Do not stop until every acceptance criterion is implemented, verified locally and prepared for review.
 - **Co-locate docs**: every code file must have a matching `*.md` sidecar next to it, that explains the component in detail. The goal of the sidecar is to make purpose, API, invariants, examples and test strategy of the component obvious to agents and humans.
-
 - This is a minimal local first web app (static HTML + modular JS). Prefer tailwind over custom CSS.
 - Entrypoint: `index.html` (+ static pages in `pages/` if any needed)
 - The code is composed of small, focused modules in `src/` (`components/`, `utils/`, ..) with colocated tests
-- Run `npm test` and `npm outdated` at the start and end of each significant task and weekly at minimum; keep dependencies healthy. Prefer bumping to the `Wanted` version unless blocked by incompatibilities (document any exceptions). Also run `npm audit` to catch security issues even when versions are current
+- Do exactly one prioritized task per iteration and work in a TDD approach where possible.
+- Before and after any change, run `npm test`
+- Run `npm outdated` weekly at minimum; keep dependencies healthy. Prefer bumping to the `Wanted` version unless blocked by incompatibilities (document any exceptions). Also run `npm audit` to catch security issues even when versions are current.
 - Only change code directly related to the current task; keep diffs small!
 - Preserve existing comments & docs; add concise, long-lived comments where useful and avoid narrating changes via comments
 - When external documentation could be consulted, do so to validate your plan makes sense. If you lack a browsing/online search tool, ask the user to run an online search for you (e.g., "Please search for \"x\" and paste back the findings")
+- Before adding functionality, search the codebase (e.g., ripgrep) to confirm it's truly absent. If present, prefer refactor over re-implementation.
+- After each iteration add a concise update at the end of docs/implementation-progress.md to use it as the memory between iterations for learnings, decisions, planning etc.
 
 ## Dependencies & no-build approach to use
 
@@ -36,6 +39,7 @@ Do requirements gathering before implementation
 - Reduce risks from assumptions (no matter how sure you are) by **proving these assumptions with tests**.
   Do not throw away the produced tests after you did the validation, because they often serve as useful documentation of a behavior. Make sure their comments explain their purpose.
 - **TDD by default.** Interfaces emerge from tests.
+- When adding/updating tests, keep a brief "why this test matters" comment in the test so future iterations can better decide to modify/keep/remove.
 
 ## TDD Loop