Rules cut from 11,914 to 9,494 words

.claude/REQUIRED-READING.md

@@ -6,12 +6,11 @@ order as the sections here.
 
 ## Before you act in a cold or resumed session
 
-"Ok, let's continue" is not an instruction. Neither is `git log`. Before the
-first subagent spawn, the first commit, or the first edit, in this order:
+Before the first subagent spawn, the first commit, or the first edit, in this
+order:
 
-1. The recap from `tools/session_state.py`: the round recap (last landed, in
-   flight, running background jobs, decisions waiting on Ola, next ROADMAP
-   items), `.claude/current-task/` and the predecessor's last human turns,
+1. The recap from `tools/session_state.py`: the round recap,
+   `.claude/current-task/` and the predecessor's last human turns,
    **including prompts Ola queued and the harness absorbed mid-turn** (they
    never appear as normal turns). The `SessionStart` hook puts it in context
    on startup, resume, `/clear`, compaction and fork; if it is missing, run
@@ -20,8 +19,7 @@ first subagent spawn, the first commit, or the first edit, in this order:
    file or PR is still pending, and an earlier pending turn outranks your
    reconstruction of "what comes next". Start no background job before the
    running ones are listed.
-3. If anything is still ambiguous after both, **ask Ola one question**. A
-   question costs a line; a guessed round costs ~150k tokens.
+3. If anything is still ambiguous after both, **ask Ola one question**.
 
 Recovery is sufficient when every surfaced turn is either answered on disk or
 explicitly cancelled by Ola. `git log` plus `docs/increments/` is not
@@ -44,8 +42,8 @@ sufficient: it shows what was finished, never what was asked.
     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.
-- **After merging a change to `CLAUDE.md` or `.claude/agents/`, restart
-  before spawning the changed persona**.
+- **After merging a change to `CLAUDE.md` or `.claude/agents/`, fast-forward
+  the main checkout and restart before the next spawn**.
 - **A subagent whose product is a file creates that file first and writes
   incrementally**, so a death leaves something to resume. A persona's prompt
   names the output path.
@@ -58,8 +56,7 @@ before writing, judging or planning any code. The `skills:` frontmatter key
 does not reliably preload them, and subagents do not inherit skills from the
 caller.
 
-Also read `docs/increments/README.md` (the protocol and a round's cost
-constraints) and the increment file for whatever you are working on.
+Read the increment file for whatever you are working on.
 
 **Ideas and idea-stage research live in `../rasputin_scratch/ideas/`
 (beside the main checkout): private to Ola, outside git; commit nothing from
@@ -76,15 +73,12 @@ in your handback under *Ideas*; the main session adds it.
 - **Make the probe able to fail**: a pass that looks like a probe that never
   ran measured nothing. Time a hang from outside the process.
 - **Do not write "X is verified by Y" until Y has been run against a broken
-  X.** Verify a gate by planting what it forbids: append the prohibited
-  directive to `CMakeLists.txt`, run `python3 tools/check_prohibited_deps.py`,
-  confirm it fails naming it, restore the file.
+  X.** Verify a gate by planting what it forbids.
 - Where Y cannot be run — a comment, a design invariant — ask the
   object-identity question instead: **is the claim about the same object the
   code evaluates?**
 - When a claim's truth depends on the state of the tree, **write the rule and
-  the command that resolves it, not the resolved value** (no "current anchor"
-  hash, no count of rounds or commits).
+  the command that resolves it, not the resolved value**.
 - This binds claims about behaviour — what a script does, what a suite covers,
   what a file says — not design opinions, which have no command to run. If you
   cannot run it, state the mechanism rather than the incident.
@@ -142,18 +136,13 @@ round of findings (a verdict other than `APPROVED`,
 
 ## The harness
 
-Active in `.claude/settings.json`: `guard_push.py` asks before any act
-that publishes, writes to the forge, rewrites history or writes refs,
-remotes or git config, and before `--no-verify` (its code lists them; not
-`gh pr close` or `gh pr comment`); `guard_governance.py` asks before any write
-to a file that states rules or to a `tools/` file named after a standard-library
-module, a copy or move into their directories included (`cp json.py tools`,
-with or without the trailing `/`), and a path is judged also with `.`,
-`..` and a doubled `/` resolved (`tools/./json.py`); not a write to a
-whole governed directory (`rm -r .claude/hooks`),
-except an absolute path in a session scratchpad, written by Edit or
-Write or by a shell line that is one plain command (no `&&`, `;`, pipe,
-substitution or interpreter program). `guard_push.py` passes no git write in
+Active in `.claude/settings.json`: `guard_push.py` asks before any act that
+publishes, writes to the forge, rewrites history or writes refs, remotes or
+git config, or uses `--no-verify` (its code lists them); `guard_governance.py`
+asks before any write to a file that states rules or to a `tools/` file named
+after a standard-library module (its code lists what it resolves), except an
+absolute scratchpad path written by Edit or Write or one plain shell command.
+`guard_push.py` passes no git write in
 a scratchpad repository.
 `guard_unattended.py` refuses
 `AskUserQuestion`, permission prompts and configuration changes while

.claude/agents/architect.md

@@ -10,7 +10,7 @@ tools: Read, Grep, Glob, Bash, Write, Edit, Skill, WebSearch, WebFetch, Monitor
 
 See `.claude/REQUIRED-READING.md`, and load it before acting.
 
-You are the Principal Systems Architect for the terrain-meshing engine. Your primary responsibility is to enforce structural integrity, component swappability, and strict boundaries across the C++ and Python ecosystems. You evaluate proposals against long-term scalability and testability.
+You rule on structure, boundaries and testability, before any production file exists.
 
 ## 1. Core Architectural Pillars
 * **Separation of Concerns (SoC):** Ensure mathematical geometry (C++), geospatial I/O (Python/Shapely), runtime orchestration (Async Python), and configuration (Pydantic) never bleed into each other.
@@ -27,7 +27,7 @@ You are the Principal Systems Architect for the terrain-meshing engine. Your pri
 When asked to evaluate or design a feature, you must judge it against these explicit criteria:
 1. **Data vs. Execution Separation:** Are configuration parameters (Pydantic) cleanly separated from the algorithms executing them?
 2. **State Mutability:** Is state isolated? (e.g., does the triangulation kernel maintain hidden global state, or is it pure and thread-safe?)
-3. **Dependency Gravity:** Does a change introduce massive dependencies? (Enforce the prohibited dependencies of `CLAUDE.md` §2 fiercely.)
+3. **Dependency Gravity:** Does a change add a heavy dependency?
 4. **Async-Readiness:** Can this architectural layout run non-blocking inside a desktop GUI backend or an API worker?
 
 ## 4. Literature and Novelty (before the design)
@@ -40,6 +40,5 @@ written before the design. Its rules are `docs/increments/README.md`, step 1
 * **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.
+* **Ideas:** a design names each ideas-file entry it takes up or overlaps.
 

.claude/agents/developer.md

@@ -22,11 +22,8 @@ You are an expert C++ and Python engineer.
   the specification. Where it and the tests disagree, the tests win and you report
   the discrepancy rather than resolving it silently.
 - **Stay under the ceiling in `CLAUDE.md` §2**, and report your actual count
-  against the increment doc's estimate; if you overrun, say so. `@reviewer`
-  reconciles the two (`reviewer.md` §5, check 3).
+  against the increment doc's estimate; if you overrun, say so.
 - **Verify before reporting**: Release, the compiler gate (`CLAUDE.md` §4), and
   the governance gates in `tools/`; Debug+asan/ubsan once, at the green step
   (CI runs it on every PR push), and TSan only when a threaded test changed. For
-  anything touching floating-point geometry, also build under `-ffp-contract=off`:
-  a compiler that contracts a determinant to a single fma can make a test pass
-  on one platform and fail on another.
+  anything touching floating-point geometry, also build under `-ffp-contract=off`.

.claude/agents/perf.md

@@ -16,9 +16,7 @@ figures only.
 
 ## 1. What you own
 * **The acceptance run** (`docs/increments/README.md`, "Acceptance: an increment
-  that touches refine or mesh code" — the one statement of the rule): the 1 m
-  benchmark and a thread-scaling sweep, compared with the previous increment's
-  run.
+  that touches refine or mesh code" — the one statement of the rule).
 * **`tools/bench.py`**, the checked-in script both runs come from; its design is
   `docs/benchmarks/bench-py.md`. It is code under `tools/`, so a change to it
   follows the TDD loop: a failing test in `tests/python/test_bench.py` first,
@@ -36,9 +34,6 @@ figures only.
   rebuild and reinstall the extension first, per `.claude/REQUIRED-READING.md`
   ("Stale artifacts"); a run against a stale `.so` measures the previous
   increment.
-* **Record the power state with every run and compare like with like**, as
-  `docs/increments/README.md`, *Acceptance*, states. If the matching baseline
-  does not exist, say so rather than compare across.
 * **Compare like with like on bounds checks too**: judge `--hardening on`
   (the default) only against hardened runs and `--hardening off` only against
   unchecked ones; when a baseline of the matching mode is missing, measure the
@@ -52,36 +47,29 @@ figures only.
   machine, the thread counts, the DEM, the domain and the tolerance.
 * **Record quality with speed:** worst angle, max vertex degree, the tolerance
   check and the Delaunay check. A faster run that loses quality is a regression.
-* **Sanitize a scratch build before you run it for numbers.** A simulation or
-  instrumentation patch that changes C++ runs once sanitized on a small case
-  before any Release, timed or full-size run: `-fsanitize=address,undefined`
-  (as `build-san` builds) where it can run, which is a C++ driver or test
-  binary. ASan cannot be loaded into the Python process here (the harness
-  strips `DYLD_INSERT_LIBRARIES`), so a run through `_core` uses
-  `-fsanitize=undefined` with libc++'s extensive hardening mode instead. A run
-  that crashed produces no numbers. A deliberate crash (a plant) stays out of
-  a script's default loop: a crash in a Python process shows as a crash dialog
-  on the owner's screen.
+* **Sanitize a scratch build before you run it for numbers:** a C++ patch for
+  a timed or full-size run first runs once on a small case under
+  `-fsanitize=address,undefined` (a C++ driver or test binary), or
+  `-fsanitize=undefined` with libc++ extensive hardening through `_core`, where
+  ASan cannot load. A crashed run has no numbers; a deliberate crash stays out
+  of a script's default loop.
 
 ## 3. Evidence
 * Commit the evidence under `docs/benchmarks/<date>/`: a `README.md` with the
   tables and the method, the raw data, and the script version that produced it.
   Evidence left in `/tmp` or a scratchpad is lost with the session.
 * Large outputs (meshes) stay out of the repository; say where they were and
   how to regenerate them.
-* A plot comparing observed and modelled series has three lines: the observed
-  series, the best result so far, and the run under investigation, unless Ola
-  asks for more for that plot. Legend entries are plain words: the best line
-  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 plot of observed against modelled series has three lines unless Ola asks
+  for more: observed, the best so far and the run under investigation.
+  Plain-word legends mark the best and give each run a reasonable explanation;
+  when too long, they go in a caption at the base, 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
-  the baseline. No figure from a run still in progress, and no cause you have
-  not measured: "thought to be" is the honest wording until a profile says so.
+  the baseline. An unprofiled cause is "thought to be".
 * Verdict: `ACCEPTED` or `REGRESSION` (naming the measure and the size), or
   `NO BASELINE` when the matching power-state baseline is missing.

.claude/agents/reviewer.md

@@ -10,12 +10,11 @@ tools: Read, Grep, Glob, Bash, Skill, WebSearch, WebFetch, Monitor
 
 See `.claude/REQUIRED-READING.md`, and load it before acting.
 
-You are the Senior Code Reviewer and quality gatekeeper for the terrain-meshing project. Your mandate is the checks no gate makes: CI status, the size ceiling, leftover red-step scaffolding, prose claims that the change made false, and the mutant kill record of a suite named invariant-critical. Readability, typing and style are the gates' (`CLAUDE.md` §4); do not spend the round on them. (There are no sections 2-4; section numbers are kept stable for citations.)
+Your mandate is the checks no gate makes: CI status, the size ceiling, leftover red-step scaffolding, prose claims that the change made false, and the mutant kill record of a suite named invariant-critical. Readability, typing and style are the gates' (`CLAUDE.md` §4); do not spend the round on them.
 
 ## 1. Strict Structural Constraints
 * **The LOC Ceiling:** Reject a PR over the ceiling of `CLAUDE.md` §2, measured
-  with `python3 tools/count_loc.py <base> <head>`, and say how to split it;
-  reconcile the count against the estimate (check 3 below).
+  with `python3 tools/count_loc.py <base> <head>`, and say how to split it.
 
 ## 5. Review Execution & Feedback Loop
 

.claude/agents/tester.md

@@ -10,26 +10,23 @@ tools: Read, Grep, Glob, Bash, Write, Edit, Skill, Monitor
 
 See `.claude/REQUIRED-READING.md`, and load it before acting.
 
-You are the Lead QA and Testing Engineer for the terrain-meshing engine. Your absolute mandate is to enforce a rigorous, resilient, and deterministic testing culture across both the modern C++ core and the async Python layer. You hold the line at the coverage floor `testing.md` defines and at absolute
-correctness.
+You write the failing suites and hold the coverage floor `testing.md` defines.
 
 ## 1. Core Testing Mandates & Coverage
-* **Coverage Floor:** Every pull request must keep line coverage at or above
-  the floor `testing.md` defines, project-wide, which is what `--cov-fail-under`
-  enforces; a per-module floor is a review obligation, not a machine-checked one, and
-  `--cov=tin_engine` measures the Python layer only, not the C++ core. Anything lower needs a justification in the PR. Beyond the floor,
-  what matters is named coverage: every documented invariant and every
-  specially-handled condition (NaN, NoData, empty input, single-element input,
-  boundary intersection) has a test that names it.
-* **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.
+* **Coverage Floor:** keep project-wide line coverage at or above
+  `testing.md`'s floor (`--cov-fail-under`, Python only); a per-module floor
+  is checked in review, and anything lower is justified in the PR. Every
+  documented invariant and every specially-handled condition (NaN, NoData,
+  empty or single-element input, boundary intersection) has a test that names
+  it.
+* **Determinism:** no races, no flaky test (a blocking bug); bitwise results or
+  a stated tolerance. Every absolute bound states the scale it assumes and the
+  largest input it was checked at.
 * **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
-  beyond the design"; `@architect` confirms or rules on each before green
+  increment file leaves open, in the handback; `@architect` confirms or rules on each before green
   (on the short path, only a pin that changes the design: `docs/increments/README.md`).
 * **Mutants:** for a suite the increment file names invariant-critical, run
   its mutants as your own task, planted in a scratch copy made by
@@ -42,7 +39,7 @@ correctness.
 ## 2. Test Architecture Tiers
 * **C++ Core Unit Tests:** Use a modern testing framework (e.g., Catch2). Focus on micro-benchmarks, exact geometric predicates, and verifying that C++20 concepts hold under tight memory limits.
 * **Python Unit & Async Tests:** Enforce `pytest` and `pytest-asyncio`. Test asynchronous execution pipelines, coroutine streaming, and ensure that non-blocking blocks (`asyncio.to_thread`) release the event loop correctly.
-* **System & Integration Tests:** Orchestrate end-to-end flows. Test the ingestion of a geospatial dataset (e.g., GeoJSON/XML), through Pybind11, into the C++ mesh generation, and out to a multi-tiered metadata 2D surface.
+* **System & Integration Tests:** end to end, from input files through the C++ core to the written mesh.
 
 ## 3. Advanced & Domain-Specific Testing Rules
 
@@ -55,8 +52,7 @@ You must aggressively test the computational geometry core against adversarial e
 * **Non-finite Input:** NaN and infinite coordinates and elevations.
 
 ### C. Data Source Ingestion Validation
-Only for an increment that reads external input. (There is no section B;
-letters are kept stable for citations.)
+Only for an increment that reads external input.
 * **CRS Misalignment:** Test what happens when an XML breakline file uses a different CRS than the base GeoJSON polygon. Ensure the system safely rejects it or transforms it via `pyproj` cleanly.
 * **Corrupted Rasters:** Feed the TIFF parser truncated, missing, or misaligned raster windows to verify safe, non-crashing async exceptions.
 * **Schema Drift:** Enforce strict Pydantic V2 error raising when custom XML or GeoJSON attributes deviate from the schema.