devrites 5.12.0 → 5.13.0

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

@@ -0,0 +1,137 @@
+# 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)
+
+## 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>/                       # default ~/code-overhaul-runs/<repo-id>/<run-id>/, mode 0700
+  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` (outside the target tree)
+```
+
+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`) |
+| `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) 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 |
+
+`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
+
+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`, 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`;
+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); no `dispatched`, `running` or `returned`
+attempt once the outcome leaves `RUNNING`; 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.
+
+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.

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

@@ -0,0 +1,207 @@
+# Repair and measurement
+
+## Contents
+
+- [One approved repair slice](#one-approved-repair-slice)
+- [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.
+3. Implement the smallest coherent fix. Keep supported contracts and UX unchanged
+   except for the exact approved change. No formatting sweep, no speculative
+   abstraction.
+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. 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.
+
+## 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 or arms not
+recorded as interleaved cap any improvement at `INCONCLUSIVE`.

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

@@ -0,0 +1,137 @@
+# 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`.