devrites 7.1.2 → 7.2.0

package/pack/generated/dsh/skills/overhaul/references/records.md

@@ -0,0 +1,203 @@
+# Records, generations and freshness
+
+## Contents
+
+- [Run area](#run-area)
+- [Canonical records](#canonical-records)
+- [Publishing a generation](#publishing-a-generation)
+- [Finding lifecycle](#finding-lifecycle)
+- [Enforced versus review-only](#enforced-versus-review-only)
+- [Validator tool](#validator-tool)
+- [Dispatch packet schema](#dispatch-packet-schema)
+
+## Run area
+
+JSON is canonical for every machine decision; Markdown and HTML are projections
+rendered from it. The coordinator is the only writer of canonical records.
+
+```text
+<run>/                       # <repo>/.devrites/overhaul/<run-id>/ from `records init`, mode 0700, git-ignored
+  CURRENT                    # name of the active generation, replaced last and atomically
+  g0007/                     # one coherent generation of mutable records + manifest.json + views/
+  revisions/                 # immutable plan-r<N>.json, rubric-r<N>.json, profile-<id>-r<N>.json, bench-<id>-r<N>.json
+  packets/                   # dispatch packets, one per attempt
+  receipts/  proposals/      # immutable worker outputs, named <run>__<task>__<attempt>__<role>.json
+  evidence/                  # sanitized logs, samples, traces, screenshots, red/green output
+  baseline/                  # snapshot from `devrites-engine overhaul snapshot capture`
+```
+
+Placement rules: [`scope-and-safety.md`](scope-and-safety.md#run-area-and-checkpoints).
+
+## Canonical records
+
+| File (in a generation) | Role and key fields |
+| --- | --- |
+| `run.json` | `run_id`, `repo_root`, `mode` (`full`/`pr`/`branch`), `assessment_only`, `phase`, `readiness_verdict`, `execution_outcome`, `identities` (comparison, baseline, candidate), `capabilities` (tools + digests, concurrency, isolation, browser), `budget`, `revisions.plan`/`revisions.rubric` (`rev`, `file`), `degradation`, `questions[]`, `stop`, `task_outcomes` |
+| `coverage.json` | `files[]`: `path`, `sha256`, `lines`, `component`, `lanes`, `eligible`, `exclusion.reason`, `binary`, `ranges[]` (`start`, `end`, `lanes`, `profiles`, `receipts{lane: [...]}`, `tools[]`, `state`); `applicability[]`: `domain`, `component`, `lane`, `state` (`applicable`/`not-applicable`/`blocked`), `reason`, `receipts[]` ([matrix](audit-domains.md#applicability-matrix)) |
+| `stack-profiles.json` | `components[]` (B6 component record), `profiles[]` (`id`, `rev`, `file`, `sha256`, `status`), `dependencies[]` (dependency decisions) |
+| `dispatch.json` | `attempts[]`: `task_id`, `attempt_id`, `wave`, `role`, `lane`, `profiles`, `snapshot`, `write_paths`, `authorized_by`, `status`, `dispatched_at`, `started_at`, `finished_at`, `receipt`, `changed_paths` |
+| `contracts.json` | `contracts[]`: producer/consumer graph, schema/version, journeys, both-side evidence, open compatibility questions |
+| `findings.json` | `findings[]` with the fields in [`orchestration.md`](orchestration.md#finding-proposals) (including `domain` and `controls`) plus `status`, `severity`, `verified_by`, `history[]` |
+| `evidence.json` | `items[]`: `id`, `kind`, `path`, `sha256`, `command`, `exit`, `fingerprint`, `inputs`, `limitations`, `by`; benchmarks add `measurement` |
+| `approval.json` | append-only `events[]` ([fields](lifecycle.md#the-approval-gate)) |
+| `results-baseline.json`, `results-candidate.json`, `gates.json`, `scorecard*.json` | scoring inputs and calculator output ([`scoring.md`](scoring.md)) |
+| `cycles.json` | append-only `cycles[]` ([`lifecycle.md`](lifecycle.md#cycle-records)) |
+| `views/` | `review.*`, `report.*`, `plan.md`, each carrying the generation stamp. `publish` requires `report.{md,html}` once `execution_outcome` leaves `RUNNING`, and `review.{md,html}` plus (with a plan) `plan.md` while `phase` is `AWAITING_APPROVAL` |
+
+`null` means "not applicable by design"; a missing value means "not recorded" —
+never "passed". Worker receipts become canonical only after admission
+([`orchestration.md`](orchestration.md#receipts)). An unreadable or missing record
+blocks the run; it never reads as zero findings.
+
+## Publishing a generation
+
+Keep one staged generation open as the working generation of a phase and publish
+it at the phase boundary, not after every shard: after preflight, after the audit
+waves are admitted (coverage and findings), after verification and reconciliation,
+at the approval gate, after each completed repair cycle, and at every stop. Record
+dispatches and admissions in the working generation as they happen; `admit receipt`
+checks attempts there when a staged generation based on `CURRENT` exists. Receipts,
+proposals, packets, evidence and the staged generation are durable files, so a
+resume loses no worker output: it continues an open stage based on `CURRENT`, or
+re-admits the receipts into a new one. A writer attempt is still published as
+`dispatched` before it launches, so an interruption always shows the live writer,
+and every admission and settlement is recorded before the run leaves `RUNNING`
+([`orchestration.md`](orchestration.md#receipts)).
+
+1. `devrites-engine overhaul records stage <run>` copies the current generation to
+   `g<N+1>.tmp` (views and manifest excluded).
+2. Edit only the staged JSON. Write any new plan, rubric, profile or benchmark
+   revision as a new file under `revisions/`; never rewrite an existing one.
+3. Render views into the staged generation with `devrites-engine overhaul render`.
+4. `devrites-engine overhaul records publish <run>` validates the staged generation
+   against the previous one, writes `manifest.json` (SHA-256 of every generation file
+   and every revision), renames the directory, then replaces `CURRENT` last.
+5. Any reader runs `validate <run>` first. A mismatch between `CURRENT`, the manifest
+   and file bytes is a mixed generation: stop applying and republish.
+
+A crash leaves an incomplete `g<N+1>.tmp` or a complete `g<N+1>` not yet current:
+`validate` reports both, `stage` refuses until you inspect it, and the previous
+generation stays intact. One atomic rename is not a transaction; readers verify
+digests.
+Give run files restrictive permissions, redact secrets before storing evidence, and
+never store credentials, tokens or private keys.
+
+## Finding lifecycle
+
+| From | Allowed next statuses |
+| --- | --- |
+| `candidate` | `needs-validation`, `confirmed`, `rejected` |
+| `needs-validation` | `confirmed`, `rejected` |
+| `confirmed` | `approved-for-fix`, `deferred`, `accepted-risk`, `rejected` (only after disproof) |
+| `approved-for-fix` | `in-progress`, `deferred` |
+| `in-progress` | `fixed-unverified`, `approved-for-fix` (attempt failed) |
+| `fixed-unverified` | `verified`, `in-progress` (verification failed) |
+| `verified` | `confirmed` (regressed or evidence invalidated) |
+| `deferred`, `accepted-risk` | `approved-for-fix`, `confirmed` |
+| `rejected` | `candidate` (new evidence) |
+
+Each finding carries a `fingerprint`: its root-cause identity (component, symbol,
+contract and failure class — never line numbers, agent, wave, severity or verdict),
+unique across the record so one root cause keeps one record across cycles.
+`needs-validation` names its missing fact in `blockers` and carries no severity.
+Locations are repository-relative (`external: true` marks a label such as
+`mobile-app:src/api.ts` for code outside the repository); a host path is rejected. A rejection
+suppresses re-raising only while the cited files keep the hashes it was judged on.
+
+Severity exists only once impact is established (`confirmed` onward). `rejected`
+with reason `false_positive` requires disproving evidence. A user-declined confirmed
+defect keeps `confirmed` impact and moves to `deferred` or `accepted-risk`; its
+control still fails. `not reproducible yet`, `environment unavailable`,
+`requirement disputed` and `proven unreachable under the approved scope` are distinct
+recorded reasons, and none means safe. History is append-only: a finding never
+disappears between generations.
+
+## Enforced versus review-only
+
+`validate`/`publish` enforce: schema tags, enums and unique IDs and fingerprints;
+evidence inside the run area with a matching `sha256`; finding history that starts at
+`candidate`, legal transitions (a same-status entry needs a `reason`), severity only
+from `confirmed` onward, a history entry for any severity or kind change, blockers
+for needs-validation, evidence for decided findings, `verified_by` naming an admitted
+verifier attempt, repository-relative locations (external ones are labels, never
+host paths); `revisions.plan.file` equal to `revisions/plan-r<rev>.json`, required
+once approvals or writers exist; plan digest pins; known, acyclic dependencies;
+allowed paths that are exact files inside the repository (no `*` or `?`, no
+directories, no `.git` component or run-area path in any letter case or through a
+symlink, no symlink or traversal escape); a separate verifier role;
+approval and `accept-degradation` events with quote and trusted channel, approvals
+matching the plan digest, closure and current revision, none active after a later
+stop; a scorecard only with `revisions.rubric` and the same verdict as `run.json`;
+`READY_FOR_USER_REVIEW` only with a scorecard whose verdict is `MEETS_TARGETS`, and
+`COMPLETED_WITH_APPROVED_DEGRADATION` only with `MEETS_TARGETS_WITH_APPROVED_DEGRADATION`,
+each listing every audit gate (plus every repair gate outside assessment-only runs) as
+`PASS` or `NOT_APPLICABLE` (`G-CONCURRENCY` may be `WAIVED_OPERATIONAL` for the degraded outcome);
+no approval or writer in an assessment-only run; unchanged `run_id`, `repo_root`,
+`mode` and `assessment_only`; writers authorized for their task; one live writer
+per path (case-folded, symlink-resolved); every attempt `admitted`, `rejected` or
+`cancelled` once the outcome leaves `RUNNING` (`timed-out` and `unknown` are not settled); one outcome per approved task at the end;
+a coverage denominator that never shrinks; append-only cycles, findings history and
+approval events; immutable revisions; view stamps; manifest integrity; stale stages
+and interrupted publishes. Across records: every finding's `domain` is a score key;
+once a rubric is frozen every confirmed finding names known `controls`, and none of
+an open finding's controls is PASS in the current results; applicability cells use a
+score key, a known state, a reason unless `applicable`, unique keys and receipts
+inside the run; coverage ranges use the seven coverage states; a scorecard's
+`G-NO-CRITICAL-HIGH` PASS needs no open critical or high finding,
+`G-NO-OPEN-SERIOUS-LEAD` PASS no open lead with critical or high potential impact,
+and `G-COVERAGE` PASS a non-empty matrix with no blocked cell, every applicable cell
+closed by an admitted, non-gap receipt whose `domains_checked` lists its domain, and every range of
+every eligible file reviewed or excluded.
+
+Receipt admission and quote anchoring live in `devrites-engine overhaul admit`
+([`orchestration.md`](orchestration.md#admission-tool)).
+
+Review-only (the coordinator and verifiers must judge): whether evidence is
+sufficient, whether a finding is real, whether coverage receipts reflect genuine
+semantic review, catalog adequacy, benchmark comparability, and whether a quote in
+`approval.json` really came from the user. JSON Schema tooling may add structural
+checks when installed; its absence is a recorded limitation, not a pass.
+
+## Validator tool
+
+`devrites-engine overhaul records digest <file>` prints the SHA-256 of exact bytes; `stage <run>`,
+`publish <run>` and `validate <run>` implement the generation protocol above. Exit
+codes: 0 ok, 1 violations (each printed as `VIOLATION: …`), 2 usage or I/O error.
+
+## Dispatch packet schema
+
+`devrites-engine overhaul packet write <run> <task> <attempt> <role> [--from <fields.json>]
+[--phase P] [--wave W] [--lane L] [--snapshot S] [--authorized-by A] [--brief PATH]
+[--write-path PATH]...` creates `<run>/packets/<run>__<task>__<attempt>__<role>.json`
+(mode 0600; `packets/` is created with mode 0700 when absent) and prints its path. `<run>` is the run-area path;
+`run_id` is its last component. `--from` supplies any further fields; flags override
+it. Exit codes: 0 written, 1 invalid packet or the packet already exists (never
+overwritten), 2 usage or I/O error, including an extra positional argument or a
+run area or `packets/` directory that is a symlink.
+
+| Field | Rule |
+| --- | --- |
+| `run_id`, `task_id`, `attempt_id`, `role` | required plain names: no path separators, `.`/`..` or `__`; the tool does not check that `role` is unprefixed (`implementer`, not `overhaul-implementer`), so callers keep it so |
+| `phase`, `lane`, `snapshot`, `authorized_by`, `brief` | required non-empty strings |
+| `receipt_path` | must resolve, in clean form (relative or absolute), to `<run>/receipts/<run>__<task>__<attempt>__<role>.json`; a value naming any other location is rejected; an absent, empty or non-string value is replaced by that default |
+| `write_paths` | array of exact paths; empty for read-only roles |
+| `plan` | optional object; when present it needs `file`; `rev` and `digest` are carried through unchecked |
+| `wave` and anything else in `--from` | optional, not validated, carried through unchanged (task definition, read paths, budgets, stop conditions) |
+
+The Go package `engine/internal/overhaul/packet` exports `Validate(run, packet)` and `Load(path)`
+(which also checks that the file name matches the packet's identifiers) for tools
+that read packets.
+
+`devrites-engine overhaul admit packet <run> <packet.json>` admits a packet before its worker
+starts. It runs `packet.Validate` with the explicit `<run>`, then requires that the file is a
+plain (not symlinked) file named `<run_id>__<task_id>__<attempt_id>__<role>.json` directly in
+`<run>/packets/`, that `run_id` equals the working generation's `run.json` `run_id`, and that a
+`dispatch.json` attempt in the working generation has the same `task_id` and `attempt_id` and
+agrees on `role`, on `snapshot` when the attempt records one, and on `receipt` and `packet`
+(run-relative) when it records them. A relative `receipt_path` is resolved from the working directory,
+exactly as `packet write` resolves it, so a bare file name or `receipts/<name>.json` is rejected
+unless the working directory makes it name the run's receipt file; a packet carrying an absolute
+`receipt_path` is admitted from any working directory. Output and exit codes match `admit receipt`: 0
+`ADMISSIBLE`, 1 `REJECT` with the reasons, 2 usage or I/O error (including a missing or
+unparsable packet), 3 `DUPLICATE_OR_LATE` when the attempt is already admitted, rejected or
+cancelled.

package/pack/generated/dsh/skills/overhaul/references/repair-and-measurement.md

@@ -0,0 +1,310 @@
+# Repair and measurement
+
+## Contents
+
+- [One approved repair slice](#one-approved-repair-slice)
+- [Simplification repairs](#simplification-repairs)
+- [Oracles by finding kind](#oracles-by-finding-kind)
+- [Comments in repairs](#comments-in-repairs)
+- [Oracles by lane](#oracles-by-lane)
+- [Never do this to get green](#never-do-this-to-get-green)
+- [False-green defenses](#false-green-defenses)
+- [The assembled candidate](#the-assembled-candidate)
+- [Performance measurement](#performance-measurement)
+- [Measurement windows](#measurement-windows)
+- [Benchmark tool](#benchmark-tool)
+
+## One approved repair slice
+
+Only an `implementer` context writes, only inside one approved task's exact paths,
+and only after the coordinator recorded the approval.
+
+1. Recheck the task's input file hashes, ownership, requirement, baseline failures
+   and approval; re-read the code to edit.
+2. Write the smallest meaningful failing regression test or other falsifiable oracle
+   for the confirmed defect and run it against the unfixed code. Classify the first
+   run: **good red** (fails at the named assertion for the expected reason — quote the
+   failing line), **broken test** (setup, import or compile error — not a valid red
+   for a logic defect), **false pass** (passes on the unfixed code — the oracle does
+   not reach the defect), or **not run** (not discovered, filtered or skipped). Only a
+   good red continues; a repair other than a defect fix gets its red from
+   [Oracles by finding kind](#oracles-by-finding-kind).
+3. Implement the smallest coherent fix. Keep supported contracts and UX unchanged
+   except for the exact approved change. No formatting sweep, no speculative
+   abstraction. Add comments only as [Comments in repairs](#comments-in-repairs)
+   allows.
+4. Run the same oracle to green, then the relevant unit, integration, contract,
+   end-to-end, static and security checks plus the impact cascade on dependents.
+   Capture commands, exit codes and output as evidence.
+5. Refactor only while the meaningful tests stay green. Update affected docs,
+   schemas, contracts, migrations and lockfiles inside the approved scope through the
+   project's canonical generators, never by hand-editing generated output.
+6. A fresh `verifier` context verifies the fix and its neighboring failure modes and
+   runs the new test against the old implementation in a disposable baseline copy
+   (apply the recorded baseline patches) to prove it still catches the original
+   defect.
+7. Remeasure approved performance targets; compare guardrails and side effects. If
+   the slice fails, revert only the agent-owned hunks (preserving user work), record
+   the failed attempt, and revise or re-approve material plan changes.
+
+Workers never run git write commands (stage, commit, stash, checkout, reset) and
+never leave unaccounted changes; the coordinator compares observed changed paths with
+the contract before admitting a patch.
+
+A pure refactor starts with characterization or contract tests and strengthens weak
+oracles; never damage correct code just to see red. A simplification follows
+[Simplification repairs](#simplification-repairs). Performance work starts with a
+reproducible benchmark or query-budget oracle; ordinary unit tests do not assert
+flaky wall-clock times — use controlled benchmarks plus deterministic query counts or
+complexity bounds. When a bug cannot be reproduced safely, record the exact missing
+fact, propose a safe alternative and obtain a documented exception where needed; a
+waived verification stays a visible gap and may block readiness.
+
+## Simplification repairs
+
+A confirmed [over-engineering](audit-domains.md#over-engineering-and-dead-weight)
+finding — delete, inline, reuse, replace with standard library, platform or installed
+dependency, remove a dependency, shrink — preserves behavior, so its oracle proves
+preservation instead of a defect:
+
+1. **Population evidence**, rerun on the current fingerprint: the search that shows
+   the removed element is unused, single-implementation or never varied, with the
+   same scope rules as the finding.
+2. **Reach:** characterization or contract tests over the behavior that stays. Show
+   they reach it: a seeded mutant in the affected code turns them red on a disposable
+   baseline copy (this is the good red; quote it). Code with zero references has no
+   behavior to reach; the population evidence stands in for the red.
+3. **Green on the candidate:** the same tests, the full relevant suite, build,
+   typecheck and lint, with discovered and executed counts; for a dependency removal
+   also a clean install from the lockfile.
+4. **Result:** lines, files and dependencies removed, recorded as evidence. A
+   simplification that changes a public, persisted or wire contract is not a
+   simplification: it needs its own approved contract task.
+
+## Oracles by finding kind
+
+Every approved task needs a check that fails before the repair and passes after
+it. When correct code has no natural red, seed a known fault on a disposable
+baseline copy and show the new artifact catches it; when neither exists, the
+finding stays audit-only. A zero-mutant, zero-test or zero-link run is never a
+pass.
+
+| Repair | Red on the baseline | Green on the candidate |
+| --- | --- | --- |
+| Defect | Regression test fails at the named assertion | Same test passes |
+| Missing or weak test | A seeded mutant (or reverted behavior) in the covered lines survives the old suite; name the mutation tool and version | The new test kills it; diff-scoped mutation score recorded |
+| Simplification | [Simplification repairs](#simplification-repairs) | |
+| Documentation | The documented command, example, generated reference or link check fails, or `git diff --exit-code` shows drift after regeneration | It runs, compiles or regenerates without a diff |
+| Observability | A test with an in-memory log, metric or trace sink finds no record with the required keys (trace ID, stable semantic-convention names) | The record is present; deleting the new line turns it red again |
+| CI, build, IaC or container config | The linter or policy tool reports the named rule ID (actionlint, zizmor, hadolint, Checkov, conftest) | That ID is gone and nothing new appears |
+| Dependency | The advisory scanner reports the advisory against a pinned database snapshot | Same scanner and snapshot report nothing new; lockfile diff limited to the approved package and its required closure |
+| Contract or public API | The compatibility or schema diff (oasdiff, buf breaking, cargo-semver-checks, gorelease, griffe, api-extractor) or a consumer contract test fails | Zero breaking findings, or the approved version bump |
+| Operations | A fault test fails: a hanging dependency, SIGTERM during a request, a stopped database, a missing required setting | The call fails within its timeout, the request drains, readiness goes unready while liveness stays up, startup names the setting |
+| Flaky test | At least one failure in N ≥ 10 shuffled runs of the unchanged code | Zero failures in the same N runs |
+| Performance | [Benchmark tool](#benchmark-tool) verdict or a deterministic budget | |
+
+## Comments in repairs
+
+Default to no new comments: names, types and the regression test carry the meaning.
+Add one only when the code cannot show why it is written this way: an invariant, an
+ordering, locking or security trap, a workaround for a named external bug (link it),
+a measured performance trade-off, or a compatibility constraint. Doc comments on a
+public API are the exception when the project's convention requires them (for
+example Go exported identifiers); match the neighboring style.
+
+Never write in target code:
+
+- finding, task, run or plan IDs, or the word "overhaul": they belong in the receipt;
+- comments that restate the code, or test comments that restate the test name or
+  label Arrange/Act/Assert;
+- edit narration ("Fixed", "Added to handle", "Now correctly") or what the code did
+  before the change; history belongs in the commit, not the source;
+- chat residue, guesses stated as fact, stacked hedges, or sales words ("robust",
+  "seamless", "comprehensive").
+
+Put the constraint first, in literal words, in one sentence where possible. Keep a
+hedge only when it names a real, specific uncertainty ("unverified on Windows").
+Leave existing comments alone unless the change makes one false; then correct it.
+
+## Oracles by lane
+
+- **Frontend:** reproduce the behavior — stale or out-of-order responses,
+  cancellation, state transitions, optimistic failure and rollback, focus loss, the
+  broken keyboard path — not "the component renders". A DOM-only unit test does not
+  prove real browser or native-engine behavior.
+- **Backend:** the native service, data or concurrency oracle: deterministic
+  interleavings, transaction outcomes, idempotent replays, query counts.
+- **Boundary:** producer and consumer evidence plus the integrated journey; a mock
+  client never proves server compatibility, and separately green sides with
+  incompatible mocks prove nothing about the real contract.
+- **UI or contract-changing repairs:** compare against baseline journeys, the
+  relevant UI states and every compatible consumer; backend unit tests alone never
+  approve them.
+
+## Never do this to get green
+
+Delete or skip failing tests; weaken assertions; update snapshots blindly; suppress
+diagnostics; reduce workloads; loosen quality gates, retries, timeouts, tolerances or
+statistical thresholds; mock away the failure; change expected outcomes to match the
+patch. Quarantine an unrelated flaky test only with baseline evidence and explicit
+user authorization. A justified correction to a test or harness needs independent
+evidence that the old oracle was wrong, a versioned explanation, baseline and
+candidate re-evaluation, and approval when the acceptance meaning changes.
+
+## False-green defenses
+
+Record test discovery and selection as well as the exit status. None of these can
+satisfy a required oracle:
+
+- zero tests discovered or executed; an unintended filter, shard or "only changed"
+  mode that silences "no tests found";
+- skipped, pending or expected-failure cases counted as passes; a runner summary that
+  counts flaky or skipped tests as success;
+- cached output from different inputs, or reused output where fresh execution is
+  required;
+- a subprocess failure swallowed by a wrapper, or a pipeline that masks the exit
+  status (`cmd | tail` without `pipefail`);
+- a snapshot run that only created missing baselines; a replay command that exits 0
+  with nothing to replay;
+- an unsupported platform or a test that matches implementation details without
+  exercising the contract.
+
+Confirm that a seeded failing example actually reaches the assertion, and keep both
+the observed failure and the candidate's observed pass. For flaky checks, record
+every attempt, its environment and reset conditions, and the first-run outcome: a
+pass only after retry is a flaky observation, not proof that the defect is gone.
+
+## The assembled candidate
+
+Test the integrated candidate, never only each worker's isolated result. Before
+combining patches, check they apply cleanly together (for example `git apply --check`
+or `git merge-tree` on copies). When individually green patches fail together, bisect
+the combination to find the interacting pair; fix the interaction under existing task
+authority when covered, otherwise propose a plan amendment. Keep the last
+independently verified candidate reference and a per-slice patch and evidence history
+in the run area — never as commits in the user's repository. Roll back only
+attributable changes whose ownership is verified; never jump back to an earlier high
+score or erase a failed experiment. An edit after final verification invalidates the
+affected final evidence.
+
+## Performance measurement
+
+The goal is substantial wins on genuine bottlenecks — preferably at least 2×, ideally
+3× or more — never a promise for every path. First establish the baseline and the
+bottleneck's share of the user-visible outcome. If profiling does not support the
+requested gain, or it would break correctness or UX, or exceed the approved risk, show
+the evidence and ask the user to approve an alternative target, a broader intervention
+or no change; never lower the target quietly. A correctness or security fix needs no
+speedup to be valuable, and a trivial absolute gain is never sold as transformational
+through a flattering percentage.
+
+A versioned benchmark contract (`revisions/bench-<id>-r<N>.json`) fixes, before any
+comparison: baseline and candidate fingerprints; one harness revision for both; build
+mode, flags and compiler/runtime/database versions; hardware, OS, resources,
+background load, network, browser and device; datasets with cardinality, skew, seeds
+and correctness checksums; scenario, concurrency and arrival model (open or closed),
+warm/cold cache policy and reset procedure; primary metric and direction, percentiles
+or throughput criterion, absolute user or SLO targets, the 2× minimum and 3× stretch
+where justified, materiality threshold and regression tolerances; warmup, repetitions
+and the statistical method; raw-sample location; error and timeout treatment; stop
+conditions.
+
+Run arms interleaved (ABAB or randomized blocks) on the same host, never all
+baseline runs under one system state and all candidate runs under another. Warm JIT
+runtimes fairly and measure cold start separately when it matters. Use production
+builds for production-facing claims. Profile during benchmarking to confirm what is
+measured. Include realistic service, database and network work; never drop failures
+or slow requests to improve an average. Choose the load model on purpose, account for
+coordinated omission and dropped work, and report offered versus completed load; a
+result at lower load or a higher error rate is not an equivalent speedup.
+
+```text
+lower is better:   speedup = baseline / candidate    reduction% = 100 × (baseline − candidate) / baseline
+higher is better:  gain    = candidate / baseline    increase%  = 100 × (candidate − baseline) / baseline
+```
+
+A 2× latency speedup is a 50% reduction, not 200%. Report absolute values and
+uncertainty with every ratio. Zero or near-zero baselines, or values at the timer's
+resolution, get no ratio. Never average unlike ratios into an "overall speedup"; a
+workload-weighted aggregate needs predeclared weights. The resampling unit is one
+independent invocation — never inner iterations. Use at least 10 invocations per
+arm and more when the interval is wide. The benchmark tool below reports the ratio of
+medians with a seeded 95% bootstrap interval: claim "at least k×" only when the
+interval's lower bound is at least k; an interval spanning 1 or k is inconclusive
+and is never rounded up. Confirm a selected win on fresh runs; do not try variants
+until one lucky sample passes. An unmeasured change earns no credit, and an
+optimization with no measurable benefit is reverted (agent-owned hunks only) and
+logged so it is not retried.
+
+For databases keep query counts, plans where safe, rows scanned and returned, buffer
+and IO behavior, and write, storage and lock costs. For UI keep critical journeys,
+render and interaction traces and metrics under matched fixtures and devices, and
+label every number:
+
+| Signal | Measures | Does not establish |
+| --- | --- | --- |
+| Field p75 (CrUX or first-party RUM) | Real users over a window, by route and device | Effect of an undeployed change; routes without data (unavailable ≠ pass) |
+| Lab trace | One session under stated conditions; LCP parts, INP phases, long tasks | How common the problem is in the field |
+| Lighthouse score | One synthetic navigation, version-weighted | User experience, INP, cross-version comparison |
+| TBT | Lab main-thread blocking during load | Field INP or post-load responsiveness |
+| CLS | Unexpected layout-shift clusters | Latency; the shift initiator |
+| Bundle size | Bytes per route | Runtime cost unless runtime metrics move |
+| Automated a11y scan | A subset of criteria (`incomplete` is not a pass) | Conformance, keyboard or screen-reader usability |
+| Static inspection | A hypothesis | Any metric value |
+
+Never deploy to obtain measurements. Keep frontend, backend and boundary benchmark
+views tied to one workload graph: a 3× faster query is not a 3× faster page until the
+page is measured; a faster server never excuses a slower client or a broken keyboard
+journey; CLS never gets a latency ratio. Track guardrails for correctness, security,
+stale-data behavior, memory, CPU, write latency, tail latency, errors, accessibility
+and visual or interaction stability; surface any trade-off and get approval. Explain
+a smaller end-to-end gain with the bottleneck analysis.
+
+## Measurement windows
+
+Review agents may run concurrently; measurements may not share CPU, browser,
+database, network or caches with other tests or agents. Record the isolation evidence
+(what else was running, load average, governor). When isolation is unavailable,
+disclose the contamination, mark the comparison inconclusive and rerun in a
+controlled window; a contaminated ratio never passes a gate.
+
+## Benchmark tool
+
+`devrites-engine overhaul bench <result.json>` prints the comparison. Input: `direction` (exactly
+`lower_is_better` or `higher_is_better`; anything else is rejected, never guessed),
+raw per-invocation `baseline` and `candidate` samples, the recorded run `order`, the
+`target` ratio, `materiality`, optional `resolution`, `resamples` and `seed`.
+Verdicts: `SUPPORTS_TARGET`, `IMPROVEMENT_BELOW_TARGET`, `IMPROVEMENT`,
+`INCONCLUSIVE`, `REGRESSION`, `NO_RATIO`. Fewer than 10 samples per arm, arms not
+recorded as interleaved, or a missing interval cap any improvement at
+`INCONCLUSIVE`.
+
+The ratio carries two 95% intervals: the seeded bootstrap of the median ratio
+(`ci95`) and the distribution-free Hodges–Lehmann ratio bounds (`hodges_lehmann`),
+exact from the Mann–Whitney distribution and needing no seed. A claim uses the
+smaller lower bound; either upper bound below 1 is `REGRESSION`. A zero or negative
+sample, or more than four million baseline × candidate pairs, leaves no
+Hodges–Lehmann bounds and caps the verdict. Optional inputs:
+
+- `quantile` (for example `0.99`) compares a tail. Give each invocation as its raw
+  request latencies (the tool takes their quantile) or as its own quantile with
+  `requests_per_invocation`, never both in one arm. Fewer than `10 / (1 − quantile)`
+  requests per invocation (1000 for p99) caps the verdict and any budget PASS. Never pool requests across invocations: the
+  invocation stays the resampling unit.
+- `tolerance` (for example `0.05`) adds a `guardrail` for metrics that must not get
+  worse: `NON_INFERIOR` when the lower bound is at least `1 / (1 + tolerance)`,
+  `REGRESSION` when the upper bound is below it, otherwise `INCONCLUSIVE`. "Not
+  significant" is never "no regression".
+- `budget` (`value`, `quantile` default `0.5`, `deterministic`) tests the candidate
+  against an absolute target with one-sided 95% order-statistic bounds: `PASS` only
+  when the bound clears the target, `FAIL` when the opposite bound misses it,
+  `INSUFFICIENT_DATA` when there are too few invocations for that quantile (p75 needs
+  11, p95 59, p99 299). `deterministic: true` (bytes, query or request counts) needs
+  every invocation to agree, else `NONDETERMINISTIC`.
+- `error_rates` (`baseline`, `candidate` per-invocation rates, absolute `tolerance`,
+  optional `requests` totals) guards failures: the candidate-minus-baseline interval
+  is the wider of an invocation bootstrap and the Newcombe score interval; `PASS`
+  only when its upper bound is within tolerance. Pair every latency claim under load
+  with it: fast failures flatter latency.
+- `load` (`offered` and `completed` per arm) marks a run where either arm completed
+  under 98% of offered load as saturated and caps every verdict.

package/pack/generated/dsh/skills/overhaul/references/review-and-report.md

@@ -0,0 +1,139 @@
+# Review page, report and terminal summary
+
+## Contents
+
+- [Views are projections](#views-are-projections)
+- [The review page](#the-review-page)
+- [Decisions and the approval message](#decisions-and-the-approval-message)
+- [The end-of-run report](#the-end-of-run-report)
+- [Terminal summary](#terminal-summary)
+- [Renderer tool](#renderer-tool)
+
+## Views are projections
+
+`review.html`/`.md`, `report.html`/`.md` and `plan.md` (the task table and approval
+message, written with a review) are rendered by the renderer tool
+below from one generation's canonical JSON; never hand-write or hand-edit them. Each
+carries the stamp `overhaul-stamp run=… generation=… plan=r<N>:<sha256>`, and the
+validator rejects a view whose stamp does not match its generation, so a stale page
+can never be applied. Human feedback on a view becomes a proposed change that the
+coordinator reconciles into a new plan revision; views are then re-rendered — there
+are never three competing versions of the plan.
+
+## The review page
+
+The page opens as a local file and works offline: one self-contained document, no
+scripts, no CDNs, no remote fonts or analytics, a hash-pinned stylesheet under a
+restrictive Content-Security-Policy, system font stacks, explicit light and dark
+backgrounds, visible `:focus-visible` outlines, semantic tables with captions and
+column headers inside keyboard-focusable scroll regions, no horizontal page scroll at
+phone width, text as well as color for every status, and a print-friendly layout.
+Every repository-derived string — filenames, snippets, finding titles, comments, JSON
+— is HTML-escaped before formatting and never interpolated as markup or script;
+absolute home paths are redacted to `~`. Never publish the page or serve it beyond
+loopback without a separate user decision.
+
+Order: summary and decision first, then evidence. Sections, each with a stable
+anchor, and rows anchored by their IDs (`#F-012`, `#T-003`, `#C-040`) so feedback can
+cite them:
+
+- scope, baseline, candidate and comparison identities, capabilities, known limits,
+  open questions;
+- one section per lane — frontend, backend, boundary, other — with actual attempts,
+  profiles, timings and receipts (no duplicate independent plans);
+- the coverage ledger and stack profiles; contracts and boundaries;
+- confirmed findings (location, failing case, impact, evidence, uncertainty, proposed
+  action), then unvalidated leads without severity, then rejected candidates with
+  reasons; opportunities stay separate from defects;
+- before-state measurements with benchmark conditions, proposed minimum and stretch
+  targets and regression guardrails;
+- the repair plan: tasks with dependencies, exact allowed paths, oracles, migration
+  and rollback needs, expected benefits, costs and alternatives, and the continuation
+  envelope ([`lifecycle.md`](lifecycle.md#what-one-approval-permits));
+- the rubric controls with lane membership and shared-control marking, the baseline
+  global, lane and domain scorecards, hard blockers and why readiness does or does
+  not qualify; frontend engineering evidence, interaction/accessibility proof and
+  optional aesthetic proposals visibly separate;
+- approvals and decisions as recorded events, never as page state.
+
+The renderer derives the report tables below from the records: lane coverage
+(admitted reviewers with their windows, profiles, reviewed versus eligible ranges,
+open ranges, lane score), findings and repairs (finding and task, severity, previous
+failure, changed paths, oracle, verification, remaining risk), and the transparent
+scorecard (baseline versus candidate per scope, applicable control weight, evidence
+gaps, hard blockers). Columns it cannot fill from records render as "not recorded".
+
+When a diagram clarifies architecture, trust boundaries, data flow or the task DAG,
+add a textual equivalent (a dependency table or indented list); an image never
+carries information the text lacks.
+
+## Decisions and the approval message
+
+The user decides per item — approve, reject, defer, ask for explanation or change —
+and approves one complete plan revision. The page never contains an "Approve" button:
+nothing a page can do (a checkbox, localStorage, a form, an edited file, a local
+server request) authenticates the user, and a script or any local process can forge
+such signals. Instead the page shows a read-only, copyable message:
+
+```text
+Approve overhaul <run-id> plan revision <N>, digest <sha256>, tasks T-001 T-002 T-005.
+Keep all listed constraints and exclusions.
+```
+
+The approval exists only when the user sends such a decision in the active trusted
+conversation (or a genuinely authenticated host action), and the coordinator
+re-hashes the plan revision and matches the digest before recording it
+([`lifecycle.md`](lifecycle.md#the-approval-gate)).
+
+## The end-of-run report
+
+Produce `report.{md,html}` from the same generation for every ending —
+interim, blocked, stopped, audit-only or final. Use real measurements only; a missing
+value renders as "not recorded", never as a sample number. Zero findings is a valid
+result; report counts always equal record counts.
+
+State separately: mode, lifecycle phase, readiness verdict and execution outcome
+(`AUDIT_COMPLETE`, `AUDIT_INCOMPLETE`, `AWAITING_APPROVAL`, `READY_FOR_USER_REVIEW`,
+`COMPLETED_WITH_APPROVED_DEGRADATION`, `STOPPED_BY_USER`, or the exact blocked state).
+`AUDIT_COMPLETE` never means the target passed. Include revisions, coverage and
+exclusions, applicable stacks, authentic approvals and actual changes, the three
+identities, environment limitations and remaining unknowns. Never write "every bug is
+fixed", "cannot break" or "fully secure".
+
+Required tables (column order fixed):
+
+| Table | Columns |
+| --- | --- |
+| Lane, stack and boundary coverage | Lane/component · actual reviewer and overlap evidence · language/runtime/framework versions · active profile/rule revisions · reviewed vs eligible ranges · mandatory proof gaps · verdict/evidence |
+| Findings and repairs | Finding/task · severity and evidence confidence · previous failure · change made · regression proof · independent result · remaining risk |
+| Performance before/after (grouped frontend, backend, end-to-end) | Scenario and workload · metric/direction · before · after · absolute delta · relative change/speedup · uncertainty/repetitions · approved target · guardrails · verdict/evidence |
+| Transparent scorecard | Global or lane/domain · weight · unique applicable control weight · baseline · candidate · evidence/profile gaps · hard blockers · evidence |
+| Iteration history | Cycle · starting deficient lanes/controls · hypothesis or proof gap · approved tasks/agents · code changes vs evidence-only work · tests/benchmarks/independent outcome · global and affected lane/domain scores · gate changes/remaining gaps · next action or stop reason |
+| Dependency decisions | Dependency · resolved before · resolved after/unchanged · keep/patch/upgrade/replace/remove · official evidence date · reason and alternatives · migration/compatibility proof · risk |
+
+Show lanes separately — never one "full-stack checked" row — plus justified absent or
+not-impacted lanes, inaccessible external components, embedded-language and
+generated-source boundaries, actual scanner coverage and manual review gaps. Keep
+candidate, rejected, deferred and accepted-risk counts apart from confirmed, fixed and
+verified. Show full-precision global and lane results, domain floors, rubric and
+profile revisions, shared-control accounting, N/A decisions, accepted risks and a
+separate hard-gate verdict, and explain score deltas by control transitions (fix,
+evidence-only, regression, invalidated evidence, rubric correction). Include original
+versus revised performance targets with the user's recorded decision, checks run and
+not run, failures proven pre-existing versus introduced, questions and decisions,
+resource and cost totals (estimates labeled), rollback and deploy-order notes (without
+deploying), the final changed-path summary, and remaining work.
+
+## Terminal summary
+
+First line: outcome, verdict and the one next action. Then the full-precision global
+and lane scores, open gates, counts, the report path and the approval message when
+awaiting approval. Last line: the next action again. No praise, no preamble, no
+estimates presented as measurements.
+
+## Renderer tool
+
+`devrites-engine overhaul render <run> <staged-generation> review|report` writes the views into
+`<staged-generation>/views/`, before `publish`. After publishing at a stop, open the
+main view with `devrites-engine open-visual <run>/<generation>/views/<review|report>.html`,
+using the published generation named in `CURRENT`, not the `.tmp` stage.