From 1d778553223cc41b82371fb94d2c6aee5134adec Mon Sep 17 00:00:00 2001 From: Ola Skavhaug Date: Thu, 22 Oct 2026 07:01:29 +0200 Subject: [PATCH 1/3] Rule round: worktrees, background commands, perf data checks, scores, estimates, away defaults, ruling scope (@architect) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All approved by Ola; prose rule files only. - CLAUDE.md §3: new worktrees are made with tools/new_worktree.py (2026-10-21-merge-326.md proposal 2). REQUIRED-READING drops its `git worktree add` hint, which said otherwise. - briefs/common.md: no polling loop; stop every background command you started before handing back (merge-326 proposal 1). - perf.md §2: check outside data's dates and extent against the run's period and domain; py-spy needs root on macOS for native frames, otherwise cProfile and `sample` (merge-326 proposal 3, its wording: the brief said "uses py-spy", which the proposal Ola approved qualifies; py-spy is not installed here either). - perf.md §3: score tables show KGE with r, alpha, beta, NSE, half-water date. Public file only; the private perf.md is outside this write limit. - tester.md §1: a red step greps the tests for lists a new command or module must join (merge-326 proposal 4). - architect.md §5: one line, cost estimates probe unknown drivers; a timing gate's factor sums each new term's estimate plus noise (2026-10-22-merge-lsm39.md proposals 1 and 2). - REQUIRED-READING unattended mode: defaults taken while away go on disk as ASK OLA lines ending "default taken: " and are all listed in the first report after the window; a build-at-all question waits; a refused push may be redone once Ola's later grant names the branch (2026-10-22-night.md proposals 2-4, review-applied wording at 4061f236). "Morning report" is undefined in the rules, so the text says "the first report to Ola after the window". - reviewer.md check 6: a design's files and pieces are checked against Ola's verbatim ruling; anything beyond its words blocks until Ola rules. Offsets: CLAUDE.md "Prohibited dependencies" bullet (restates §2, gated; night retro §6); tester.md's sentence restating the LOC exemption of tests. rule_sizes.py total 11,951 before edits on this base? No: 11,714 at base, 11,913 after (+199). Co-Authored-By: Claude Opus 5.5 --- .claude/REQUIRED-READING.md | 12 ++++++++---- .claude/agents/architect.md | 1 + .claude/agents/perf.md | 7 +++++++ .claude/agents/reviewer.md | 3 ++- .claude/agents/tester.md | 4 +++- .claude/briefs/common.md | 3 ++- CLAUDE.md | 2 +- 7 files changed, 24 insertions(+), 8 deletions(-) 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 From 5ff8c3eba20c857bf1d0a26e7d9d2e27ecc7671b Mon Sep 17 00:00:00 2001 From: Ola Skavhaug Date: Thu, 22 Oct 2026 07:06:36 +0200 Subject: [PATCH 2/3] Rule round: review APPROVED WITH WORDINGS on 1d778553 (@reviewer); tester.md sentence on the size ceiling restored (cut not approved) Co-Authored-By: Claude Opus 5.5 --- .claude/agents/tester.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/agents/tester.md b/.claude/agents/tester.md index 251382ef..4b83fc39 100644 --- a/.claude/agents/tester.md +++ b/.claude/agents/tester.md @@ -78,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. +* **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. From f0aea3bded3bb50b3dc199ae1f2a890d1c50bb49 Mon Sep 17 00:00:00 2001 From: Ola Skavhaug Date: Thu, 22 Oct 2026 07:13:34 +0200 Subject: [PATCH 3/3] =?UTF-8?q?Rule=20round:=20tester.md=20drops=20its=20r?= =?UTF-8?q?estatement=20of=20the=20size=20ceiling=20(Ola:=20CLAUDE.md=20?= =?UTF-8?q?=C2=A72=20is=20its=20only=20statement)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- .claude/agents/tester.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/agents/tester.md b/.claude/agents/tester.md index 4b83fc39..251382ef 100644 --- a/.claude/agents/tester.md +++ b/.claude/agents/tester.md @@ -78,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.