@iowarp/clio-coder 0.3.1 → 0.3.2

package/skills/research/experiment-protocol/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: experiment-protocol
+description: Use when running a performance study, numerical comparison, parameter sweep, kernel or solver benchmark, or any change justified by "faster" or "more accurate", and success criteria should be locked before results exist. Pre-registers thresholds, tolerances, environment pins, and verdict conditions into the repository validation contract before any measurement. Triggers on "benchmark", "compare implementations", "optimize", "tolerance", "reproduce results", "parameter sweep". Not for diagnosing a stalled bug; use scientific-debugging.
+version: 0.1.2
+license: Apache-2.0
+allowed-tools:
+  - read
+  - write
+  - grep
+  - ls
+  - find
+  - git
+  - context
+  - code_nav
+  - bash
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/research/experiment-protocol
+  audit: pass
+  provenance: designed
+  eval-status: smoke-checked
+  model-size: any
+---
+
+# Experiment Protocol
+
+Lock the success criteria before any result exists. Pre-registration that
+happens after the first measurement is worthless: it can only ratify what was
+already seen. Moving the threshold after seeing results is the exact failure
+mode this protocol exists to prevent.
+
+Anti-trigger: if the question is "why is this output wrong", that is a
+diagnosis, not an experiment; use scientific-debugging.
+
+## Phase 0 - Pre-register
+
+Before any measurement, write the protocol into the repository validation
+contract: `.clio-coder/validation.yaml` (preferred) or `VALIDATION.md` at the repo
+root. Creating this file raises Clio's repo-derived rigor to high immediately;
+from the next turn onward, completion claims in this session must carry
+validation evidence or state a limitation. That escalation is the point:
+the contract arms the finish gate with the criteria you are about to commit to.
+
+The pre-registration must contain:
+
+- **Outcome**: one sentence, e.g. "the fused kernel reaches at least 1.8x the
+  baseline throughput on the pinned input at equal accuracy".
+- **Thresholds**: minimum (below this is REFUTED), target, stretch.
+- **Tolerance semantics per metric**: absolute for near-zero quantities,
+  relative elsewhere; a mixed scheme must say which applies where. "1e-6" with
+  no stated semantics is not a tolerance.
+- **Environment pin**: compiler and flags, modules or package versions, node
+  class, scheduler context (partition, exclusivity).
+- **Input identity**: paths plus checksums (`sha256sum`).
+- **Verdict conditions**: what observation makes the result CONFIRMED, REFUTED,
+  or INCONCLUSIVE. Committed now, immutable after the first measurement.
+
+## Phase 1 - Baseline
+
+Capture current behavior under the pinned environment before changing
+anything. Store raw outputs and timings as artifacts; never edit them. A
+speedup claim without a baseline captured under the same pin is a guess.
+
+## Phase 2 - Experiment
+
+- One independent variable per run. A run that changes the algorithm and the
+  compiler flags answers no question.
+- Size repetitions to the noise: shared nodes and networked filesystems need
+  more repetitions and a reported variance, not a single lucky run.
+- Record scheduler identity (job id, node list) alongside every measurement.
+
+## Phase 3 - Analysis
+
+Compare against the pre-registered thresholds only. If the protocol was
+deviated from, log the deviation next to the result; do not silently absorb
+it. Findings outside the registered outcome are marked exploratory and get
+their own pre-registration if pursued.
+
+## Phase 4 - Iterate
+
+Keep a dead-ends ledger in the contract file or beside it: one line per
+rejected approach with the reason it was rejected. Read it before proposing
+the next approach; re-proposing a ledger entry wastes a run. Stop when one of
+the pre-registered stop conditions holds: target met, budget exhausted, or all
+candidate strategies rejected.
+
+## Worked Example
+
+Request: "make the halo exchange faster."
+
+```yaml
+# .clio-coder/validation.yaml
+experiment: halo-exchange-overlap
+outcome: overlap communication with interior compute; >= 1.5x step throughput
+thresholds: { minimum: 1.2x, target: 1.5x, stretch: 2.0x }
+metrics:
+  step_time: { semantics: relative, tolerance: 5% run-to-run variance }
+  solution_l2: { semantics: absolute, tolerance: 1e-12 vs baseline }
+environment: gcc 13.2 -O3, openmpi 4.1.6, 4x cpu-bind=cores, exclusive nodes
+inputs: { mesh: data/mesh-256.h5, sha256: "<checksum>" }
+verdicts:
+  confirmed: step_time speedup >= 1.2x AND solution_l2 within tolerance
+  refuted: speedup < 1.2x with variance < 5%, or accuracy loss
+  inconclusive: run-to-run variance > 5% (resize repetitions first)
+dead_ends: []
+```
+
+Baseline: 20 repetitions on exclusive nodes, mean and variance recorded with
+job ids. Experiment: nonblocking exchange only, flags untouched. Result: 1.3x,
+accuracy within 1e-12: CONFIRMED at minimum, target not met; ledger gains
+"persistent requests: no gain over nonblocking here, latency-bound", and the
+next variable (message aggregation) gets its own run.
+
+## Red Flags
+
+- Any measurement taken before the contract file exists.
+- A threshold, tolerance, or verdict condition edited after results appeared.
+- Wall-clock numbers with no environment pin attached.
+- A single-run victory claim on a shared machine.
+- A REFUTED result reported as "promising"; refuted plus a ledger entry is a
+  successful experiment, say so plainly.
+- Deleting or rewriting baseline artifacts.

package/skills/research/experiment-protocol/evals.md

@@ -0,0 +1,91 @@
+# Evals - experiment-protocol
+
+Baseline scenarios (run a subagent WITHOUT the skill to capture the gap, then
+WITH the skill to confirm it closes). Rubric is pass/fail per bullet.
+
+## S1 - "make this kernel faster"
+
+Setup: make the smoothing kernel in kernel.py faster.
+
+Fixture:
+```bash
+printf 'import time\n\ndef smooth(values, window):\n    out = []\n    for i in range(len(values)):\n        lo = max(0, i - window)\n        hi = min(len(values), i + window + 1)\n        out.append(sum(values[lo:hi]) / (hi - lo))\n    return out\n\nif __name__ == "__main__":\n    data = [float(i %% 97) for i in range(200000)]\n    t0 = time.perf_counter()\n    smooth(data, 25)\n    print("seconds:", round(time.perf_counter() - t0, 3))\n' > kernel.py
+```
+
+Expected:
+
+- Writes a pre-registration into `.clio-coder/validation.yaml` or `VALIDATION.md`
+  before running any benchmark or editing any code.
+- The pre-registration contains thresholds (minimum/target/stretch) and
+  tolerance semantics stated per metric (absolute vs relative).
+- Pins the environment (compiler, flags, versions, node/scheduler context)
+  and identifies inputs by path plus checksum.
+- Captures a baseline under the same pin before changing anything.
+- Changes one independent variable per experiment run.
+
+## S2 - results miss the target
+
+Setup: the pre-registered target was 1.5x; the measured result is 1.1x, below
+the registered minimum of 1.2x.
+
+Expected:
+
+- Reports REFUTED against the original pre-registered threshold.
+- Does not restate the goal, lower the threshold, or reframe 1.1x as success.
+- Adds a dead-ends ledger entry naming the rejected approach and the reason.
+- Proposes the next approach only after reading the ledger.
+
+## S3 - noisy measurements on a shared machine
+
+Setup: benchmark runs on a shared node; run-to-run variance exceeds the gap
+being measured.
+
+Expected:
+
+- Sizes repetitions to the observed noise instead of reporting a single run.
+- Reports variance alongside the mean, with scheduler identity recorded.
+- Declares INCONCLUSIVE if variance swamps the effect, rather than picking
+  the best run.
+
+## S4 - anti-trigger: wrong output
+
+Setup: user asks "why is this solver producing wrong values?"
+
+Expected:
+
+- Refers to scientific-debugging instead of starting a benchmark protocol.
+- Does not write a validation contract for a diagnosis task.
+
+## Baseline failure modes to watch for (RED)
+
+- Benchmarks first, defines success afterward from whatever the numbers show.
+- "Faster" claimed from one run, no baseline, no environment pin.
+- Threshold quietly adjusted after seeing results.
+- Tolerance given as a bare number with no absolute/relative semantics.
+- Rejected approaches vanish; the next session re-proposes them.
+- Raw baseline artifacts edited or overwritten.
+
+## Observed gap closure
+
+S1 run 2026-07-01, headless `clio-coder run` against a scratch git fixture (a pure
+Python O(n^2) nearest-neighbor kernel with a single-shot bench script).
+Prompt: "Make this kernel faster."
+
+- RED (no skill): the agent edited the kernel immediately, reported a 7.3x
+  speedup from one timing run each way, wrote no contract, stated no
+  thresholds or tolerance semantics, and pinned nothing. Correctness was
+  checked ad hoc after the fact.
+- GREEN (skill via `--skill` and `/skill <name>` invocation): the tool-call ledger
+  shows sha256 and environment capture, then `.clio-coder/validation.yaml` written
+  with min/target/stretch thresholds, per-metric tolerance semantics, and
+  verdict conditions, then the repetition-sized warm-up baseline, then
+  experiments, with the kernel edited only after a variant met the contract.
+  A float32 variant that beat the target but missed the accuracy tolerance
+  was rejected and logged in the dead-ends ledger. Writing the contract
+  raised repo rigor to high mid-session and the finish gate demanded
+  validation evidence before the turn settled. All five S1 bullets pass.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS. Pre-registration written before touching the seeded kernel; judge 5/5.

package/skills/research/scientific-debugging/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: scientific-debugging
+description: Use when debugging has stalled after the first obvious fix, when a failure spans multiple systems, when someone is about to try random changes, or when a scientific or HPC code produces wrong numbers, NaNs, nondeterministic results, or an unexplained performance regression. Forces falsifiable hypotheses across distinct fault classes with evidence-cited verdicts before any fix. Triggers on "why is this failing", "wrong results", "flaky", "nondeterministic", "diagnose", "root cause". Not for designing benchmarks or pre-registered experiments; use experiment-protocol.
+version: 0.1.2
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - ls
+  - find
+  - git
+  - context
+  - code_nav
+  - bash
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/research/scientific-debugging
+  audit: pass
+  provenance: designed
+  eval-status: smoke-checked
+  model-size: any
+---
+
+# Scientific Debugging
+
+Debug by falsification, not by trying fixes. A fix attempted before a confirmed
+diagnosis is an experiment run without a hypothesis; when it "works" you have
+learned nothing, and when it does not you have contaminated the evidence.
+
+Anti-trigger: if the failure is a typo, a missing import, or an error message
+that names its own cause, fix it directly and skip this workflow. The loop
+below is for failures that survived the first obvious fix.
+
+## The Loop
+
+1. **Goal.** One sentence stating the observable "fixed" state. "The regression
+   test matches the reference output within the documented tolerance on two
+   consecutive runs" is a goal; "make it work" is not.
+2. **Hypothesize.** Write at least three hypotheses. Each must name its fault
+   class and carry a falsification test: "this is WRONG if <observation>".
+   A hypothesis you cannot state a falsification test for is a hunch; refine it
+   until it is testable.
+3. **Rank.** Order by test cost times prior likelihood. Run the cheapest
+   decisive test first, not the most interesting one.
+4. **Test.** One variable per test. Preserve the raw failing output somewhere
+   untouched before you change anything.
+5. **Verdict.** Record CONFIRMED, REFUTED, or INCONCLUSIVE per hypothesis, each
+   citing the command and output that decided it. A verdict without a citable
+   observation is a guess.
+6. **Iterate.** Refuted everything? Generate new hypotheses from what the tests
+   revealed. Confirmed one? Only now edit code.
+
+## Fault Classes
+
+Hypotheses must span at least two distinct classes. Anchoring on a single class
+is the failure mode this rule exists to break: the debugger who is sure it is
+"a race" stops seeing the stale module load in front of them.
+
+| Class | Typical suspects |
+|---|---|
+| numerics | accumulation order, mixed precision, tolerance misuse, fastmath |
+| data | format or layout drift, HDF5/NetCDF/Zarr metadata, units, corruption |
+| concurrency | races, MPI collective mismatch, nondeterministic reduction order |
+| environment | modules, compiler flags, library versions, scheduler context |
+| resources | memory pressure, filesystem quirks, quota, node differences |
+| regression | a recent change; bisect the history instead of staring at code |
+
+## Tiers
+
+**Quick diagnosis** (default): the loop above, state held in conversation,
+time-boxed at fifteen minutes of investigation. If the box expires without a
+CONFIRMED verdict, escalate. Say that you are escalating; do not silently keep
+poking.
+
+**Structured investigation**: write an investigation file (for example
+`INVESTIGATION.md` or `.clio-coder/investigation-<slug>.md` via bash heredoc since
+this skill does not edit code) containing the goal, baseline measurements of
+the failing behavior, and one experiment per hypothesis with its verdict
+condition committed *before* the experiment runs. Update verdicts as evidence
+arrives. The file is the state; the conversation is commentary.
+
+## Evidence Rule
+
+The fix commit should cite the confirming observation, e.g. "confirmed by:
+`OMP_NUM_THREADS=1` reproduces bitwise-identical results, run log above".
+High-rigor repos will demand validation evidence at completion anyway; produce
+it proactively rather than being re-prompted for it.
+
+## Worked Example
+
+Report: "after the refactor, results differ from reference by 1e-4."
+
+- Goal: `pytest tests/test_advection.py` passes against the pinned reference
+  within its stated rtol on a clean checkout plus the refactor commit.
+- H1 (regression): the refactor changed the loop order and with it the
+  floating-point accumulation order. WRONG if the pre-refactor commit shows the
+  same 1e-4 drift. Test: `git stash && pytest ...` (cost: 1 min).
+- H2 (numerics): the comparison uses an absolute tolerance where values near
+  zero need a relative one. WRONG if the drift is uniform across magnitudes.
+  Test: print elementwise error vs magnitude (cost: 5 min).
+- H3 (environment): a different BLAS or compiler flag set is active in the new
+  environment. WRONG if `pip freeze`/module list matches the reference
+  environment pin. Test: diff environments (cost: 2 min).
+- Order: H1, H3, H2. H1 verdict: REFUTED, pre-refactor commit is clean, output
+  cited. H3: REFUTED, environments identical. H2: CONFIRMED, error is constant
+  1e-4 at all magnitudes, so near-zero elements fail the absolute check.
+- Only now edit: fix the tolerance semantics, cite H2's observation in the
+  commit message.
+
+## Red Flags
+
+- Editing code before any hypothesis has a CONFIRMED verdict.
+- All hypotheses drawn from one fault class.
+- A test that changes two variables at once.
+- "It seems better now" presented as a verdict.
+- Retrying a flaky test until it passes instead of making it deterministic.
+- The fifteen-minute box expiring without an explicit escalation.
+- Feeling certain: when a hypothesis feels obviously true, state its
+  falsification test anyway before touching the code.

package/skills/research/scientific-debugging/evals.md

@@ -0,0 +1,138 @@
+# Evals - scientific-debugging
+
+Baseline scenarios (run a subagent WITHOUT the skill to capture the gap, then
+WITH the skill to confirm it closes). Rubric is pass/fail per bullet.
+
+## S1 - stalled numerical bug
+
+Setup: a small numerical project with a reference-comparison test. The
+workspace already contains the fixture; run `python -m unittest -q` for the
+reference check. Prompt: "after a refactor our results differ from the
+reference by about 1e-4 and the obvious fix did not help; diagnose it."
+
+Fixture:
+
+```bash
+mkdir -p tests
+cat > diffusion.py <<'PY'
+import math
+
+
+def weighted_mean(values, weights):
+    weighted = [value * weight for value, weight in zip(values, weights)]
+    return math.fsum(weighted) / math.fsum(weights)
+PY
+cat > tests/test_diffusion.py <<'PY'
+import math
+import unittest
+
+from diffusion import weighted_mean
+
+
+class DiffusionReferenceTest(unittest.TestCase):
+    def test_weighted_mean_matches_reference(self):
+        values = [1.0e16, 6.0e-4, -1.0e16, 1.0e-4, 2.0e-4, -3.0e-4]
+        weights = [1.0, 1.0, 1.0, 1.0, 1.0, 1.0]
+        expected = math.fsum(value * weight for value, weight in zip(values, weights)) / math.fsum(weights)
+        observed = weighted_mean(values, weights)
+        self.assertLess(abs(observed - expected), 1.0e-12)
+
+
+if __name__ == "__main__":
+    unittest.main()
+PY
+git init -q
+git config user.name "Clio Eval"
+git config user.email "clio-eval@example.invalid"
+git add diffusion.py tests/test_diffusion.py
+git commit -q -m "add stable weighted mean reference"
+cat > diffusion.py <<'PY'
+def weighted_mean(values, weights):
+    total = 0.0
+    for value, weight in zip(values, weights):
+        total += value * weight
+    return total / sum(weights)
+PY
+```
+
+Expected:
+
+- States a one-sentence goal naming the observable fixed state before
+  investigating.
+- Writes at least three hypotheses, each with an explicit "this is WRONG if"
+  falsification test.
+- Hypotheses span at least two distinct fault classes, including numerics and
+  regression.
+- Orders tests cheapest-first and runs one variable per test.
+- Records a CONFIRMED/REFUTED/INCONCLUSIVE verdict per hypothesis, each citing
+  a command and its output.
+- Edits no code before a hypothesis is CONFIRMED.
+
+## S2 - flaky parallel test
+
+Setup: a test suite where one MPI/threaded test fails intermittently. Prompt:
+"this test is flaky, sometimes it passes; figure out why."
+
+Expected:
+
+- Includes a concurrency-class hypothesis (race, collective mismatch, or
+  reduction order).
+- Attempts a deterministic reproduction (pin threads, fix seeds, force
+  ordering) rather than rerunning until green.
+- Preserves the raw failing output before changing anything.
+- Does not present a lucky pass as a verdict.
+
+## S3 - escalation to structured tier
+
+Setup: quick-tier investigation is not converging; all initial hypotheses come
+back REFUTED and fifteen minutes of investigation have elapsed.
+
+Expected:
+
+- Explicitly announces escalation to the structured tier instead of silently
+  continuing.
+- Writes an investigation file containing the goal, baseline measurements of
+  the failing behavior, and one experiment per hypothesis.
+- Each experiment's verdict condition is committed before the experiment runs.
+- New hypotheses are generated from what the refuted tests revealed.
+
+## S4 - anti-trigger: trivial failure
+
+Setup: the failure is an obvious typo or missing import whose error message
+names its own cause. Prompt: "why is this failing?"
+
+Expected:
+
+- Fixes it directly or says a quick fix is appropriate.
+- Does not run the hypothesis ceremony for a self-explanatory failure.
+
+## Baseline failure modes to watch for (RED)
+
+- Tries a fix immediately with no stated hypothesis.
+- Single hypothesis, no falsification test, anchored on one fault class.
+- Bundles the fix with the diagnosis in one edit.
+- Verdicts asserted from intuition with no cited observation.
+- Flaky test "resolved" by rerunning until it passes.
+- Investigation drifts past the time box with no escalation and no file.
+
+## Observed gap closure
+
+S1 run 2026-07-01, headless `clio-coder run` against a scratch git fixture (an
+order-sensitive summation whose refactor replaced `math.fsum` with a plain
+accumulation loop; regression check fails by 1.474e-4).
+
+- RED (no skill): the agent found the correct root cause but with no stated
+  goal, no enumerated hypotheses, no falsification tests, and no verdicts; it
+  read the diff, asserted the cause, and benchmarked alternative summations ad
+  hoc. On a harder bug that first guess would have been unfalsified anchoring.
+- GREEN (skill via `--skill` and `/skill <name>` invocation): one-sentence goal,
+  three hypotheses (numerics, data, environment; the refactor regression
+  folded into H1) each with a WRONG-if test, explicit cheapest-first ranking,
+  CONFIRMED/REFUTED verdicts citing command output, untested H3 marked N/A,
+  fix applied only after the CONFIRMED verdict, and a commit message citing
+  the confirming observation. All six S1 bullets pass.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS. Judge 6/6 on the seeded numerical fixture; cleanest research run.

package/skills/research/scientific-modernization/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: scientific-modernization
+description: Use when modernizing, porting, rewriting, packaging, accelerating, or replacing established scientific software, especially across languages, build systems, CPU/GPU backends, or maintained forks. Establishes an external scientific oracle, preserves compatibility, delivers in independently validated stages, and settles upstream ownership and long-term stewardship before calling the work complete. Triggers on "modernize this scientific code", "rewrite in Rust", "port to GPU", "replace this research tool", "migrate the build", "maintained fork", and "scientific parity". Not for an isolated benchmark; use experiment-protocol. Not for diagnosing wrong results; use scientific-debugging.
+version: 0.2.0
+license: Apache-2.0
+allowed-tools:
+  - read
+  - write
+  - grep
+  - ls
+  - find
+  - git
+  - context
+  - code_nav
+  - bash
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/research/scientific-modernization
+  audit: pass
+  provenance: designed
+  eval-status: scenarios-recorded
+  model-size: large
+---
+
+# Scientific Modernization
+
+Modernization preserves scientific behavior and stewardship; it is not source
+translation. Faster code, a clean build, and passing self-authored unit tests
+do not establish scientific equivalence. Work the stages below in order; each
+has an explicit exit condition.
+
+## Stage 1 — Decide whether this work should exist
+
+Identify the upstream project: active maintainers, license, release cadence,
+supported users, contribution path. Prefer improving the original project when
+coordination is viable.
+
+Record the decision in writing before any implementation:
+
+- path chosen: upstream contribution, maintained successor, or explicitly
+  scoped fork;
+- the accountable maintainer or organization by name;
+- the compatibility surface users already rely on;
+- release, deprecation, and migration intent.
+
+Do not start a rewrite whose only durable plan is "the community can maintain
+it later." Exit: the four bullets above are written down and the user has seen
+them.
+
+## Stage 2 — Establish an independent scientific oracle
+
+Write the acceptance contract in `.clio-coder/validation.yaml` (preferred) or
+`VALIDATION.md` before changing behavior. Pick at least one oracle that does
+not depend on the new implementation agreeing with itself:
+
+- exact outputs from a trusted reference implementation;
+- parity against the established tool over a representative corpus;
+- known statistical behavior with pre-registered bounds;
+- simulated data whose correct answer is fixed in advance;
+- conserved quantities, analytical solutions, or domain invariants.
+
+For every output, define: units, shapes, ordering, missing-value behavior,
+determinism, absolute and relative tolerances, allowed platform variation.
+Include adversarial and historically troublesome inputs.
+
+If no credible oracle exists, stop and report that limitation. Implementation
+velocity cannot repair an undefined truth condition. Keep performance
+acceptance separate: pre-register speed claims through `experiment-protocol`.
+Exit: the contract file exists and names its oracle(s).
+
+## Stage 3 — Freeze the compatibility envelope
+
+Inventory observable behavior before migrating anything:
+
+- CLI and API contracts, file formats, schemas, defaults, error behavior;
+- packaging, fresh-install, upgrade, and uninstall paths;
+- supported platforms, compilers, runtimes, accelerators, schedulers;
+- resource scaling, reproducibility controls, provenance;
+- undocumented conventions captured by downstream tests and real workflows.
+
+Capture reference outputs and install evidence from released artifacts, not
+only the source checkout: mature tools carry user trust and conventions a
+line-by-line translation misses. Exit: reference outputs and the envelope
+inventory are stored as artifacts.
+
+## Stage 4 — Deliver in independently valid stages
+
+Split the work into the smallest stages that can each be checked against the
+oracle. Every stage gets a before/after boundary, an acceptance command, a
+retained artifact, and a rollback point. Prefer vertical slices that produce a
+usable result over a big-bang rewrite.
+
+Per stage:
+
+1. Capture the reference result on the pinned corpus and environment.
+2. Make one bounded change.
+3. Run compatibility and scientific-oracle checks.
+4. Preserve raw outputs, discrepancies, and provenance.
+5. Resolve or explicitly classify every mismatch before expanding scope.
+
+An agent's confidence is not evidence. If a reviewer cannot reconstruct the
+comparison from retained artifacts, the stage is unverified; say so. Exit per
+stage: oracle checks pass or every mismatch is classified in writing.
+
+## Stage 5 — Budget explicitly for the last mile
+
+Initial implementation is faster than convergence. Reserve work for: edge
+cases, subtle numerical differences, nondeterminism, fresh environments,
+large inputs, interrupted runs, packaging metadata, documentation, user
+migration. Re-run the full oracle matrix after any optimization: correctness
+proven before an optimization is not inherited by the optimized code.
+
+Use `scientific-debugging` when a mismatch needs causal diagnosis. Never widen
+tolerances or drop inconvenient corpus entries to obtain parity.
+
+## Stage 6 — Ship only with evidence and stewardship
+
+A completion claim must include all of:
+
+- the oracle and compatibility matrix that passed, plus retained artifacts;
+- unresolved differences and their user-visible consequences;
+- fresh-install and documented-workflow results;
+- performance results, if claimed, under their registered protocol;
+- upstream status, or the named owner and maintenance plan;
+- migration, rollback, release, and deprecation instructions.
+
+If scientific validity or durable ownership is unresolved, report the work as
+a prototype. Do not call it a replacement, successor, or production release.
+
+## Red Flags
+
+- A rewrite begins before maintainers or downstream users are consulted.
+- Tests derived only from the new implementation.
+- "The outputs look close" replacing declared tolerance semantics.
+- Performance wins reported before scientific parity.
+- One final comparison substituting for staged validation.
+- A passing happy path hiding fresh-install, scale, or edge-case failures.
+- A fork shipping without an accountable owner and maintenance horizon.