diff --git a/.claude/REQUIRED-READING.md b/.claude/REQUIRED-READING.md index cbb7e89a..18646ff4 100644 --- a/.claude/REQUIRED-READING.md +++ b/.claude/REQUIRED-READING.md @@ -43,7 +43,7 @@ sufficient: it shows what was finished, never what was asked. subagent. If the writer died, its spawner deletes it; if the spawner was a lost session, the next session does, after step 1 has printed it. - **One session per working tree.** Nothing assigns `session.md`, so - concurrent sessions need separate worktrees (`git worktree add`). + concurrent sessions need separate worktrees. - **After merging a change to `CLAUDE.md` or `.claude/agents/`, restart before spawning the changed persona**. - **A subagent whose product is a file creates that file first and writes @@ -181,9 +181,10 @@ file, no harness state, no push): that is a guard false positive. Redo the write with Edit or Write, and add a `GUARD FALSE POSITIVE:` line naming the files to the handback. A refused write to a rule file is never redone by any route. A refused push, pull request or merge is redone only when its sole -reason is that the head is not reviewed, and only once an approving -`@reviewer` verdict covering it is recorded; a refused amend, only in the form its reason names. The guard judges each redo -again. While away, a branch Ola named with +reason is that the head is not reviewed, once an approving `@reviewer` +verdict covering it is recorded, or that the branch was not yet granted, +once Ola's later grant names it; a refused amend, only in the form its +reason names. The guard judges each redo again. While away, a branch Ola named with `away.py --grant ` may be pushed (as `git push origin :refs/heads/`, or `git push private ...` for a branch holding commits of `private/master`), opened as a pull request and enqueued, or on the @@ -192,6 +193,9 @@ fresh yes, provided `@reviewer`'s last verdict on the branch, recorded by a hook from its handback, approved its head; the guard checks this, and the grant ends with the window. Otherwise record it as an `ASK OLA:` line (main session: in `session.md`; subagent: in its handback) and continue with other work. +A default taken while away is an `ASK OLA:` line ending "default taken: +", written as it is taken; the first report to Ola after the window +lists every one. A question whether to build at all waits for Ola. When Ola says he is leaving, ask him how long, and ask him to run `away.py` with that duration. Before he leaves, the `QUEUE:` line names at least one fallback that needs no ruling and writes no governed path, and one diff --git a/.claude/agents/architect.md b/.claude/agents/architect.md index 386c68b2..29dbce52 100644 --- a/.claude/agents/architect.md +++ b/.claude/agents/architect.md @@ -38,6 +38,7 @@ written before the design. Its rules are `docs/increments/README.md`, step 1 ## 5. Operational Instructions for Claude Code * **Constants:** Every absolute constant in a design states the scale it assumes and the largest input it was checked at. * **Fixtures:** each test a design specifies carries its fixture's measured figures; an amendment recomputes them for each existing test it changes. +* **Estimates:** a cost estimate counts each driver it does not know with a scratch probe; a timing gate's factor sums the estimate of each new term in the gated call, plus noise. * **Action:** Before allowing `@developer` to write code for a complex task, you must provide a high-level component blueprint showing the data flow and interface boundaries. * **Ideas:** before a design, read the private ideas file; name each entry the design takes up or overlaps, and hand back each idea it leaves out. diff --git a/.claude/agents/perf.md b/.claude/agents/perf.md index e990113d..229817a3 100644 --- a/.claude/agents/perf.md +++ b/.claude/agents/perf.md @@ -44,6 +44,10 @@ figures only. unchecked ones; when a baseline of the matching mode is missing, measure the previous merge commit in that mode back to back (`docs/increments/24-release-hardening.md` §7). +* **Outside data first:** before planning runs on outside data, check its + dates and extent against the run's period and domain. +* **Python profiles:** py-spy needs root on macOS for native frames; + otherwise use cProfile and `sample `. * **Repeat and take the median**; record the machine, the thread counts, the DEM, the domain and the tolerance. * **Record quality with speed:** worst angle, max vertex degree, the tolerance @@ -71,6 +75,9 @@ figures only. is marked as the best, and each modelled line gets a reasonable explanation of what that run is. When plain words make the legend too long, the descriptions go in a caption at the base of the plot, like a figure legend. +* A table scoring a modelled series against an observed one shows KGE with + its parts r, α and β, NSE, and the half-water date (the day half the + period's flow has passed). ## 4. Reporting * Hand back figures you measured, with their power state, in a table against diff --git a/.claude/agents/reviewer.md b/.claude/agents/reviewer.md index 34a95e5d..19cd9def 100644 --- a/.claude/agents/reviewer.md +++ b/.claude/agents/reviewer.md @@ -47,7 +47,8 @@ probe only for a figure the design marks unmeasured. the quick check's catchments (`tools/bench_quick.py`), and every library repair or coverage call names its method and tolerance, and every claimed mutant kill holds against the fixtures' figures, all holes reported in one - pass. + pass. Check the design's list of files and pieces against Ola's verbatim + ruling: anything beyond its words blocks the design until Ola rules on it. **You do not edit or commit:** your verdict goes in the handback, and your spawner records it. diff --git a/.claude/agents/tester.md b/.claude/agents/tester.md index c478ba3d..251382ef 100644 --- a/.claude/agents/tester.md +++ b/.claude/agents/tester.md @@ -24,6 +24,8 @@ correctness. * **Determinism:** Tests must be 100% deterministic. Eliminate any race conditions in async Python loops, and enforce strict bitwise consistency or acceptable floating-point tolerances (using `pytest.approx` or custom numerical predicates) in C++. * **Numeric bounds:** Every absolute bound in an assertion states the scale it assumes and the largest input it was checked at. * **Zero Flakiness:** Flaky tests are a blocking bug. If a test fails intermittently due to timing or resource state, it must be refactored immediately. +* **Lists:** a red step that adds a command or module greps the tests for + each list of them it must join, and adds it there. * **Scaffolding:** after green, remove red-step scaffolding, red notes included, before review. * **Choices beyond the design:** list every choice your tests pin that the increment file leaves open, under the handback heading "Pinned or assumed @@ -76,5 +78,5 @@ Reference implementations: `delaunay_oracle` and `tolerance_oracle` in ## 4. Operational Style Guide for Tests * **Idiomatic & Clean:** Test code is production code. It must be self-documenting, readable, and free of massive, unreadable boilerplate blocks. Use `pytest` fixtures heavily for data setup. * **Explicit Assertions:** Never use generic `assert False` or blanket `try/except` blocks without asserting the exact exception type and error message. A refusal test asserts the reason (stderr or message), not only the exit status. When the design names the fix by code location, apply it to a scratch copy made as for mutants, with your uncommitted tests copied in, and run the whole suite once; an older test it turns red is fixed in the red commit. -* **PR Constraint:** Reject any code change that lacks corresponding tests. Test suites are exempt from the ceiling in `CLAUDE.md` §2 entirely — it counts production code. +* **PR Constraint:** Reject any code change that lacks corresponding tests. diff --git a/.claude/briefs/common.md b/.claude/briefs/common.md index 64020de1..e18dcb94 100644 --- a/.claude/briefs/common.md +++ b/.claude/briefs/common.md @@ -10,7 +10,8 @@ $note; write **no other file under .claude/current-task/**. **Ola's words appear only under "Ola, verbatim"** below. If **blocked on power, network or a lock**, stop and hand back. Start a long run with Bash's `run_in_background` and wait for its end -notice, never `sleep`; write a rule +notice, never `sleep` or a polling loop; before you hand back, stop every +background command you started; write a rule file with Edit or Write, never through the shell. End each commit message with the **Co-Authored-By trailer** from your system context. End each commit subject you write with `(@$persona)`. diff --git a/CLAUDE.md b/CLAUDE.md index 0ffe0548..74e09a61 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,6 +50,7 @@ the personas. Its rules: tests go back to `@developer`. * **Resume while small.** Resume a persona only while its transcript is under about 150 k tokens; past that, spawn fresh on the increment file. +* **Worktrees.** Make each new worktree with `tools/new_worktree.py`. * **Finish before starting.** At most three items are in flight: product, harness and process work, retrospectives included. An item counts from its first spawn until its PR merges or Ola parks or drops it, except while @@ -80,7 +81,6 @@ the personas. Its rules: first, then stop. No file that does not exist yet, no number from a run still in progress, no cause not checked. No unasked images, no undefined jargon. -* **Prohibited dependencies.** Hold every persona to §2's list. * **Lessons.** A persona reports a lesson in its handback; pass it to `@orchestrator`, which records it in `docs/retrospectives/`. * **When to spawn `@orchestrator`.** After each increment merges (a check of