devrites 5.14.0 → 5.14.2

package/pack/generated/pi/agents/overhaul-verifier.md

@@ -19,9 +19,9 @@ specialization:
 
 | Specialization | Question to answer |
 | --- | --- |
-| `finding-verify` | Is this candidate real? Look for existing defenses, counterexamples, unreachable prerequisites, wrong locations, duplicate root causes |
-| `repair-verify` | Does the fix hold, including neighboring failure modes, and does the new test still fail against the old implementation in a disposable baseline copy? |
-| `coverage-critic` | Which surfaces, ranges, boundaries or check classes did the last wave miss or leave stuck? |
+| `finding-verify` | Is this candidate real? Look for existing defenses, counterexamples, unreachable prerequisites, wrong locations, duplicate root causes. For an absence claim (unused, one implementation, never varies), rerun the population search yourself, including dynamic, reflective, generated, entry-point and external-consumer paths, and check each "never flag" case in `.pi/skills/overhaul/references/audit-domains.md` § Over-engineering and dead weight |
+| `repair-verify` | Does the fix hold, including neighboring failure modes, does the new test still fail against the old implementation in a disposable baseline copy (for other repair kinds, the red that `.pi/skills/overhaul/references/repair-and-measurement.md` § Oracles by finding kind names), and does every added comment meet `.pi/skills/overhaul/references/repair-and-measurement.md` § Comments in repairs (a violation is a finding, not a pass)? |
+| `coverage-critic` | Which surfaces, ranges, boundaries, check classes or applicability cells did the last wave miss, leave stuck or close without a receipt that lists the domain? |
 | `final-clean-critic` | Is there any remaining coverage work? Only a clean answer lets coverage count as complete |
 | `catalog-adequacy` | Does the rubric cover the inventory, profile risk families, journeys and trust boundaries, without duplicate or diluting controls? |
 | `profile-challenge` | Do a provisional profile's rules fit the installed versions, fail on a known-bad fixture and stay quiet on a known-good one? |

package/pack/generated/pi/prompts/rite-fast.md

@@ -0,0 +1,5 @@
+---
+description: "Fast lane for mid-size work: one spec-and-plan step with clarifying questions, up to ten slices built without per-slice gates, one completeness check with gap fixes, review, polish, proof."
+argument-hint: "<task | slug>"
+---
+Read and follow the DevRites skill at `.pi/skills/rite-fast/SKILL.md`, applying it to: ${ARGUMENTS:-the current request}.

package/pack/generated/pi/skills/devrites-lib/reference/intent-map.md

@@ -43,6 +43,7 @@ One binary test per pair; both true ⇒ ask once.
 | `devrites-frontend-craft` vs `rite-polish` | Building new UI vs finishing built UI; craft sets standards at build, polish runs the catch pass. |
 | `devrites-ux-shape` vs `rite-spec` | Interaction/state/flow design question vs behavior-contract gap; shaped UX feeds the spec. |
 | `devrites-prose-craft` vs `devrites-frontend-craft` | Long-form prose (docs/README/replies) vs visible product copy; boundary lives in [`browser-proof-checklist.md`](standards/browser-proof-checklist.md). |
+| `rite-quick` vs `rite-fast` vs `rite-spec` | One reversible change → `/rite-quick`; mid-size work the user explicitly runs as `/rite-fast` (≤10 slices, one check after build) → `/rite-fast`; work needing strategy review, a vetted plan, or per-slice gates → `/rite-spec`. |
 | `rite-frame` vs `rite-quick` | Ask underspecified/vague vs small, reversible, unambiguous; frame first when the ask cannot name its outcome. |
 | `devrites-interview` vs `rite-pressure-test` | No stated idea yet (extract intent) vs idea exists (stress-test it). |
 | `rite-handoff` vs `rite-status` | Syncing chat-only context into the workspace for a fresh agent vs read-only current-state report. |
@@ -73,6 +74,7 @@ Wrong-skill fire: stop, admit it, switch rites.
 | Reslice, reorder, or repair an existing plan | `/rite-plan` | Slices exist and evidence invalidates them. |
 | Review plan before code | `/rite-vet` | Every plan; depth scales to risk. |
 | Small safe fix | `/rite-quick` | Escalates auth, migration, public API, destructive, ambiguous, or multi-slice work. |
+| Mid-size work, fast lane (explicit only) | `/rite-fast` | Spec + plan + questions once, ≤10 slices, one completeness check, review, polish, proof; risk deepens questions. |
 | Prove UI/runtime | `/rite-prove` + `devrites-browser-proof` | Capture real evidence. |
 | Stuck/unfamiliar | `/rite-zoom-out` | Map before editing. |
 | Teach me | `/rite-explain` | Human learning loop. |

package/pack/generated/pi/skills/overhaul/SKILL.md

@@ -103,7 +103,8 @@ deployment, or anything the user did not start with this command.
 
 1. Dispatch `recon` ([`overhaul-recon`](.pi/agents/overhaul-recon.md)); admit its inventory,
    components, lanes, partitions, contract seeds and journeys into `coverage.json`,
-   `stack-profiles.json` and `contracts.json`.
+   `stack-profiles.json` and `contracts.json`, and record the applicability matrix
+   in `coverage.json` ([`references/audit-domains.md`](references/audit-domains.md#applicability-matrix)).
 2. Compose profiles per component ([`references/stack-profiles.md`](references/stack-profiles.md));
    research unknown stacks through the unknown-stack procedure.
 3. Launch the concurrent engineering wave: when both lanes apply,

package/pack/generated/pi/skills/overhaul/references/audit-domains.md

@@ -8,6 +8,7 @@
 - [Concurrency, caching, retries and distributed reliability](#concurrency-caching-retries-and-distributed-reliability)
 - [Security, privacy and trust boundaries](#security-privacy-and-trust-boundaries)
 - [Architecture, maintainability and anti-slop](#architecture-maintainability-and-anti-slop)
+- [Over-engineering and dead weight](#over-engineering-and-dead-weight)
 - [Tests and verification quality](#tests-and-verification-quality)
 - [Dependencies and supply chain](#dependencies-and-supply-chain)
 - [Backend performance](#backend-performance)
@@ -15,17 +16,23 @@
 - [Frontend craft, interaction and accessibility](#frontend-craft-interaction-and-accessibility)
 - [Classifying frontend guidance](#classifying-frontend-guidance)
 - [Cross-layer contracts](#cross-layer-contracts)
+- [Public API and developer experience](#public-api-and-developer-experience)
+- [Documentation](#documentation)
 - [Operations and project-specific extensions](#operations-and-project-specific-extensions)
 
 ## Applicability matrix
 
 Before a review shard starts, build the matrix domain × component × lane × active
-profile. Each cell is `applicable` (reviewed under the correct semantics),
-`not applicable` (with evidence), or `blocked` (with the missing capability). Missing
-expertise, tools or browser access is `blocked`, never `not applicable`. Extend the
-matrix for discovered stacks, risks and requirements. Every item below is a question
-to answer with evidence, not a finding to assume; a clean domain has checks and
-inspected ranges recorded.
+profile and record it in `coverage.json` `applicability[]` (`domain` as one of the
+eight [score keys](scoring.md#audit-sections-and-score-domains), `component`, `lane`,
+`state`, `reason`, `receipts[]`). Each cell is `applicable` (reviewed under the
+correct semantics), `not-applicable` (with a reason and evidence), or `blocked` (with
+the missing capability). Missing expertise, tools or browser access is `blocked`,
+never `not-applicable`. Extend the matrix for discovered stacks, risks and
+requirements. Every item below is a question to answer with evidence, not a finding
+to assume. A cell is closed only by an admitted receipt that lists its domain in
+`domains_checked`; a cell with no such receipt is not checked, never clean, and
+`G-COVERAGE` cannot pass over it.
 
 ## Correctness and data integrity
 
@@ -107,7 +114,8 @@ globals; duplicated sources of truth; over-centralized modules; abstraction leak
 expensive coupling; error semantics; resource ownership; unsafe casts and type
 escapes; broad catches; shotgun changes; superficial wrappers; cargo-cult patterns;
 speculative infrastructure; copy-paste divergence; placeholder code;
-performance-obscuring indirection.
+performance-obscuring indirection. Complexity without a current need has its own
+floor in [Over-engineering and dead weight](#over-engineering-and-dead-weight).
 
 A refactor needs a concrete defect, inconsistency, maintenance cost or measurable
 risk. Never rewrite working idiomatic code toward a personal style. Similar-looking
@@ -119,13 +127,77 @@ Prose clean-up applies only to approved docs, comments or report text and must k
 facts, terminology, identifiers and meaning. No UI or copy change rides on a backend
 approval.
 
+## Over-engineering and dead weight
+
+Code that serves no current requirement still costs reading, testing, securing and
+migrating. Agent-written code shows these patterns more often — larger patches, more
+duplicated blocks, fewer reuses of existing helpers — but authorship is never
+evidence: check every codebase the same way. Tag each candidate with its cheapest cut:
+
+- `delete`: unreferenced code, exports, routes, flags, config keys and environment
+  variables; scratch and debug files, commented-out blocks, leftover debug output;
+  parameters and options every caller leaves at the default; compatibility shims,
+  aliases and "legacy" branches for forms that never shipped; features and edge-case
+  paths no requirement, caller or test needs.
+- `yagni`: an interface, abstract base or protocol with one implementation (fakes
+  count); a factory, builder, registry or plugin system with one product; a type
+  parameter used with one type; a strategy, hook or options bag nobody varies; a
+  layer that only passes data along; configuration or a flag whose value never
+  differs across real deployments.
+- `reuse`: a near-duplicate of a helper, type or pattern that already exists under
+  another name. Search by what the code does, not by its name.
+- `stdlib` / `native`: hand-written code that the standard library, the platform
+  (HTML, CSS, database constraints, the runtime) or an installed dependency already
+  provides. Name the replacement and the version that has it.
+- `dependency`: a package used for a few lines, a manifest entry nothing imports, two
+  packages doing one job, or a name that does not resolve on its registry
+  (hallucinated or typosquat risk: route to security).
+- `shrink`: wrappers that only delegate; single-use helpers whose name says no more
+  than their body; checks for states the types or an internal caller already exclude;
+  the same validation repeated across internal layers; broad catches and
+  success-shaped fallbacks that hide failure; retries, timeouts or circuit breakers
+  around local work, or nested retry layers; caching without a measurement; one error
+  logged at every layer; comments and docstrings that restate the code.
+
+Evidence for each candidate: the population count (implementations, callers,
+non-default arguments, importers, values across deploy configuration) with tool,
+scope and file count reconciled with `git ls-files`, covering tests, reflection and
+string dispatch, dependency injection, generated code, entry points (CLI, handlers,
+plugins, serverless), public exports and external consumers; history (`git log -S`)
+showing whether the form shipped or the value ever varied; the lines and dependencies
+removable; and the concrete cost. Dead-code, unused-dependency and clone tools yield
+candidates, not findings; token clone detectors miss renamed copies, so a low
+duplication figure proves nothing.
+
+Never flag: validation at trust boundaries (user input, network, files,
+deserialization, environment, IPC) — generated code misses these more often than it
+repeats them; exported, published or persisted contracts and their documented
+migration windows; test seams that tests use; real plural implementations, including
+fakes and plugins; audit, security and compliance logging; caching, retries or
+low-level code backed by a linked measurement, incident or SLO; decisions recorded in
+an ADR (report a mismatch with the ADR instead); refactoring and tests that make
+change easier; a single smoke test or assertion self-check. When nobody can say why
+code exists, check its history and owners before proposing removal.
+
+Severity follows consequence: most cuts are low or medium `maintainability`.
+Duplicated logic that can diverge on money, authorization, tenancy or time is a
+correctness finding; a swallowed error is correctness or reliability; an unresolvable
+dependency is security.
+
 ## Tests and verification quality
 
 Check assertion strength, observable behavior, unhappy paths, boundaries, state
 transitions, retries, races, idempotency, time dependence, migrations, rollback,
 compatibility, tenant and security isolation, service contracts, flakiness and test
 isolation. Mocks must not remove the database, network or concurrency behavior the
-defect lives in. Confirm tests are discovered and actually run.
+defect lives in. Confirm tests are discovered and actually run. Detect flakiness by rerunning, in
+random order with a recorded seed (`go test -shuffle=on -count=N`, `pytest -p
+randomly`, Jest `--randomize`): a test that fails then passes on unchanged code is
+flaky and cannot serve as an oracle; order dependence is its most common cause.
+Flag tautological
+tests (asserting what a mock returns, or only "not null"), mocks of internal
+collaborators or of the unit under test, near-duplicate tests that differ by one
+literal, and production code special-cased to pass a test.
 
 Line and branch coverage locate gaps; they never prove correctness. Use focused
 mutation testing, property-based tests, fuzzing, differential checks or fault
@@ -137,7 +209,8 @@ that merely restate the implementation.
 
 Inventory direct and transitive **resolved** versions, their runtime/build/test
 roles, origins, licenses, support and end-of-life status, advisories, deprecated
-APIs, provenance, integrity and install scripts. Verify the latest compatible and
+APIs, provenance, integrity and install scripts, plus the unused, redundant or
+unresolvable entries named under [Over-engineering and dead weight](#over-engineering-and-dead-weight). Verify the latest compatible and
 the latest upstream versions separately against official registries, releases and
 advisories at run time; "newer" alone justifies nothing.
 
@@ -251,11 +324,65 @@ documented or observed contract evidence from unverifiable internals. A coordina
 interface change needs one reconciled contract revision, explicit write owners,
 ordered tasks and approval.
 
+## Public API and developer experience
+
+For libraries, SDKs, CLIs, plugins and configuration consumed outside the repository:
+
+- **Compatibility:** diff the exported surface against the last release with the
+  ecosystem's checker (`gorelease` or `apidiff`, `cargo-semver-checks`, `griffe
+  check`, api-extractor with publint and `attw`, japicmp); a breaking change needs a
+  major version or a documented migration. `gorelease` does not fail on `v0`
+  modules; report their breaking changes anyway.
+- **CLI:** data on stdout and diagnostics on stderr; exit 0 only on success, with
+  distinct non-zero codes for usage and runtime errors; `--help` and `--version`;
+  machine-readable output where scripts consume it; no color when not a TTY or when
+  `NO_COLOR` is set; never prompt without a TTY, and a flag for every prompt.
+- **Errors:** name the cause and the offending value, the constraint, and how to fix
+  it; no stack trace as the only message; never rely on color alone.
+- **Configuration:** documented precedence (flags, environment, project, user,
+  system); unknown keys rejected with a suggestion; a validate command or dry run.
+
+Each claim gets an executed check: the compatibility diff, `cmd --json` parsing,
+`NO_COLOR=1 cmd` containing no escape codes, a bad argument giving a non-zero exit
+with empty stdout, golden tests on error text.
+
+## Documentation
+
+Inventoried docs are reviewed, not skipped. Check that install, setup and quick-start
+commands run on a clean checkout; examples compile or run (Go `Example` tests,
+doctests, `cargo test --doc`); generated references (CLI help, OpenAPI, config
+schemas) match a fresh regeneration with no diff (`cog --check`, `mdox fmt --check`,
+`git diff --exit-code`); documented flags, endpoints and settings exist in code and
+the reverse; local links and anchors resolve (`lychee --offline`). Wrong docs that
+send a user down a broken path are findings with the same severity rules as code.
+
 ## Operations and project-specific extensions
 
-Check observability, missing or unsafe logs, metric cardinality, tracing boundaries,
-health and readiness, feature flags, deployment order, graceful shutdown, rollback,
-backup and restore, version skew, configuration drift, resilience and diagnosability.
+For every long-running service, check with a fault test where possible:
+
+- **Signals:** structured logs carrying the trace or correlation ID from the inbound
+  `traceparent` to outbound calls and jobs; RED metrics per endpoint and USE metrics
+  per resource under stable OpenTelemetry semantic-convention names; no secrets,
+  tokens or personal data in logs, spans or metrics; bounded metric cardinality.
+- **Health:** liveness checks only the process, never a dependency; readiness checks
+  what serving needs; a startup probe covers slow boot. Stop the database: readiness
+  fails, liveness stays up.
+- **Shutdown:** on SIGTERM readiness fails first, in-flight work drains and consumers
+  stop fetching, all within the platform's grace period.
+- **Timeouts and retries:** every outbound call has connect and total timeouts from
+  the caller's deadline; retries are bounded, jittered, at one layer, only for
+  idempotent work; queues and concurrency are bounded.
+- **Configuration:** from environment or mounted files, never secrets in the
+  repository or image; a missing required setting fails startup and names it.
+- **Change safety:** rollback or roll-forward path, staged rollout, feature-flag
+  kill switches with owners and removal dates, expand-and-contract migrations with
+  lock and statement timeouts (squawk, `atlas migrate lint`), version skew between
+  old and new instances.
+- **Recovery:** backups proven by a restore that queries data against RTO and RPO;
+  alerts on symptoms and SLO burn, each with a runbook; SLOs on user-visible
+  behavior; CPU and memory requests and a memory limit.
+
+Also check deployment order, configuration drift, resilience and diagnosability.
 Add language- or domain-specific extensions when applicable: memory ownership and
 FFI, native sanitizers, embedded constraints, GPU and frame budgets, numerical, data
 and ML reproducibility, regulated or safety requirements. An unfamiliar domain is

package/pack/generated/pi/skills/overhaul/references/lifecycle.md

@@ -145,6 +145,8 @@ interface one write owner with explicit ordering; let a shared-contract change l
 only with evidence from both consumers. Independent frontend and backend tasks may
 run concurrently. A task like "improve architecture", "optimize queries" or "add
 tests" with no concrete failing case and acceptance evidence is not approvable.
+Each task names the oracle its kind requires
+([`repair-and-measurement.md`](repair-and-measurement.md#oracles-by-finding-kind)).
 Rejected and deferred findings stay visible and keep failing their controls.
 
 ## Revisions, evidence and freshness

package/pack/generated/pi/skills/overhaul/references/orchestration.md

@@ -35,13 +35,15 @@ directory names or file extensions. One package or file can serve several lanes.
 | Backend engineering | Service, domain, API, job, data, concurrency, authorization and service performance, including server parts of full-stack frameworks | [`overhaul-backend-engineer`](.pi/agents/overhaul-backend-engineer.md) |
 | Boundary / integration | Producer/consumer contracts, shared packages, serialization, trust transitions, deployment skew | [`overhaul-boundary`](.pi/agents/overhaul-boundary.md) |
 | Frontend craft | Design system fit, interaction states, keyboard/focus, accessibility, responsive and motion evidence | [`overhaul-craft`](.pi/agents/overhaul-craft.md) |
-| Other | Build tooling, infrastructure, libraries, data/ML workloads — explicit extra profiles, never forced into frontend/backend | [`overhaul-specialist`](.pi/agents/overhaul-specialist.md) |
+| Other | Build tooling, CI, infrastructure, libraries, data/ML workloads, operations readiness, public API and CLI experience, documentation — explicit extra profiles, never forced into frontend/backend | [`overhaul-specialist`](.pi/agents/overhaul-specialist.md) |
 
 Frontend and backend engineering are always different agent invocations with
 different active profiles, even in a same-language codebase. The boundary reviewer
 supplements them; it never absorbs them into one generic "full-stack" review. The
 craft reviewer supports the frontend lane; it never approves code correctness or
-imposes a redesign.
+imposes a redesign. Dispatch the `operations`, `devex` and `docs` specializations
+whenever the matrix marks their cells applicable: a deployable service, a published
+library, CLI or SDK, and inventoried documentation.
 
 For every lane record `present`, `not present`, `not impacted within scope`, or
 `blocked/unavailable`. Only the first three are facts about the target; only
@@ -148,14 +150,17 @@ Each worker writes one immutable `overhaul.receipt/1` JSON file:
 ```json
 {"schema": "overhaul.receipt/1", "run_id": "", "task_id": "", "attempt_id": "", "role": "",
  "lane": "", "context_id": "", "started_at": "", "finished_at": "", "snapshot": "",
- "profiles": [], "inspected": [{"path": "", "ranges": [[1, 80]]}], "rules_applied": [],
+ "profiles": [], "inspected": [{"path": "", "ranges": [[1, 80]]}], "domains_checked": [], "rules_applied": [],
  "rules_unassessed": [], "commands": [{"cmd": "", "exit": 0, "log": "evidence/..."}],
  "outcome": "findings|no-findings|gap|patch|verdict", "findings": [], "questions": [],
  "changed_paths": [], "evidence": [], "limitations": [], "basis": ""}
 ```
 
 `no-findings` names the checks and ranges inspected; a bare "looks good" is
-malformed. `gap` names the missing input, failed check or capability limit.
+malformed. `domains_checked` lists the score domains (`correctness`, `security`,
+`reliability`, `performance`, `tests`, `architecture`, `ux`, `operations`) the
+reviewer applied to those ranges; admission rejects an unknown key and a
+`no-findings` without it, and only a listed domain can close an applicability cell. `gap` names the missing input, failed check or capability limit.
 Timeouts, null output and malformed receipts are `gap`, never `no-findings`. A
 generic full-stack receipt cannot close a missing lane, language or profile
 assignment. Admit receipts only through `devrites-engine overhaul admit receipt`; a duplicate or
@@ -170,7 +175,10 @@ finding cannot be confirmed.
 ## Finding proposals
 
 Workers propose; the coordinator assigns canonical `F-` IDs after admission. Fields:
-`title`; `domain`; `lanes`; `component_ids`; `profile_ids` with revisions;
+`title`; `domain` (one score domain key, per the
+[section map](scoring.md#audit-sections-and-score-domains)); `controls` (the rubric
+control IDs it fails, required once a rubric is frozen and the finding is
+confirmed); `lanes`; `component_ids`; `profile_ids` with revisions;
 `rule_ids`; `contract_or_journey_ids`; `kind` (`defect`, `hardening`,
 `maintainability`, `opportunity`); `scope_origin` (`introduced`, `exposed-existing`,
 `pre-existing`); `locations` (paths, line ranges, symbols, file hashes);

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

@@ -32,11 +32,11 @@ Placement rules: [`scope-and-safety.md`](scope-and-safety.md#run-area-and-checkp
 | 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`) |
+| `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) plus `status`, `severity`, `verified_by`, `history[]` |
+| `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)) |
@@ -132,7 +132,16 @@ per path (case-folded, symlink-resolved); no `dispatched`, `running` or `returne
 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.
+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)).

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

@@ -3,6 +3,9 @@
 ## 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)
@@ -24,10 +27,12 @@ and only after the coordinator recorded the approval.
    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.
+   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.
+   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.
@@ -47,13 +52,80 @@ never leave unaccounted changes; the coordinator compares observed changed paths
 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
+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,
@@ -203,5 +275,36 @@ controlled window; a contaminated ratio never passes a gate.
 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`.
+`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/pi/skills/overhaul/references/scope-and-safety.md

@@ -76,13 +76,28 @@ these limits:
 - Never install, update or fetch dependencies, and never run commands that
   deploy, migrate or seed a real database, call paid or production services, or send
   data out. When a check needs one of those, record it `BLOCKED` with the missing
-  step, or ask.
+  step, or ask. The one exception is an approved dependency task, described below.
 - Treat any change to a non-ignored path as a write. Run `snapshot state`
   before a command and `delta` after it: build output and caches the repository
   ignores are expected; any other changed path stops the run for reconciliation,
   exactly like an unexpected writer change.
 - Run each baseline command once and give its log to every lane that needs it,
-  rather than rerunning it per lane.
+  rather than rerunning it per lane. When a baseline test fails, or touches time,
+  concurrency, network or randomness, rerun that test at least 3 times (10 before it
+  serves as an oracle) in shuffled order with a recorded seed, and record each
+  outcome: a fail-then-pass is flaky, never evidence for or against a repair.
+
+**Approved dependency tasks.** When the approved plan changes a manifest or lockfile,
+the implementer changes only the task's exact manifest and lockfile paths, through
+the package manager's own lockfile-only command with install scripts disabled (for
+example `npm install --package-lock-only --ignore-scripts`, `pnpm install
+--lockfile-only`, `uv lock --upgrade-package`, `cargo update -p <name> --precise`,
+`go get <module>@<version>` then `go mod tidy`). Network is limited to the configured
+package registry or proxy, and the plan records that effect. Afterwards verify the
+lockfile (`npm ci`, `go mod verify`, `uv lock --check`, `cargo metadata --locked`):
+the diff holds only the approved package and its required closure, with no new
+install scripts or registry hosts. Do not adopt a release younger than the project's
+cooldown (or one day) unless it is the security fix itself.
 
 **Isolated (`--isolate`, or code the user did not write).** Use this mode when the
 user passes `--isolate`, and ask before running in place when the code under review

package/pack/generated/pi/skills/overhaul/references/scoring.md

@@ -4,6 +4,7 @@
 
 - [What the index is and is not](#what-the-index-is-and-is-not)
 - [Freeze the control catalog before repairs](#freeze-the-control-catalog-before-repairs)
+- [Audit sections and score domains](#audit-sections-and-score-domains)
 - [Credit and arithmetic](#credit-and-arithmetic)
 - [Lane scores](#lane-scores)
 - [Thresholds and hard gates](#thresholds-and-hard-gates)
@@ -35,13 +36,17 @@ immutable `rubric-r<N>.json` before any repair; the plan pins its digest.
 Each control definition carries: stable `id`; exactly one `domain`; `lanes` it
 belongs to; components, requirement, profile rule and contract IDs; `failure_case`;
 risk `rationale`; `weight` (1 modest, 3 material, 5 high-consequence);
-`hard_gate`; `evaluation` (`executed`, `static`, `source-proof`, `human`);
+`hard_gate`; `evaluation` (`executed`, `static`, `source-proof`, `human`; a
+`performance` control passes only on `executed`, `source-proof` or `human` evidence,
+because static inspection establishes no metric);
 `evidence_required`; `independent_verification`; and `na` (null, or an approved
 exclusion with reason and evidence). Candidate status, verifier receipts and
 evidence live in separate results files that reference the rubric digest.
 
-Default domain weights (tailor only with a stated project-risk reason and user
-approval before remediation):
+The calculator accepts control weights 1, 3 or 5 only. Default domain weights
+(tailor only with a stated project-risk reason and user approval before remediation;
+each changed domain needs a `weight_deviations` entry with `domain`, `reason` and the
+`approval` reference, or the calculator rejects the rubric):
 
 | Domain key | Meaning | Weight |
 | --- | --- | ---: |
@@ -66,6 +71,25 @@ an opportunity to add easy passing controls that dilute the denominator.
 Mark hard-gate controls for every mandatory safety, security, data-integrity,
 compatibility and critical-user-journey requirement.
 
+## Audit sections and score domains
+
+Every finding, receipt `domains_checked` entry and applicability cell uses one of the
+eight score keys. The [audit floor](audit-domains.md) sections map to them:
+
+| Audit section | Score domain |
+| --- | --- |
+| Correctness and data integrity; Database, queries, migrations and storage (integrity, migrations) | `correctness` |
+| Security, privacy and trust boundaries; Dependencies (advisories, provenance, unresolvable names) | `security` |
+| Concurrency, caching, retries and distributed reliability | `reliability` |
+| Backend performance; Database (query cost); Frontend performance | `performance` |
+| Tests and verification quality | `tests` |
+| Architecture, maintainability and anti-slop; Over-engineering and dead weight; Frontend engineering (structure) | `architecture` |
+| Frontend craft, interaction and accessibility; Public API and developer experience; Cross-layer contracts (compatibility) | `ux` |
+| Operations and project-specific extensions; Documentation; Dependencies (support, end of life, build integrity) | `operations` |
+
+A finding that spans two domains takes the domain of its consequence and names the
+other's control in `controls`.
+
 ## Credit and arithmetic
 
 Binary credit only, from current evidence meeting the predeclared acceptance
@@ -146,7 +170,7 @@ High numbers never compensate for a failed gate.
 | `G-REPORT-CONSISTENCY` | Records validate; views carry the current stamp | all |
 | `G-APPROVAL` | Authentic, current approval of the exact plan revision and tasks | repair |
 | `G-TASKS-COMPLETE` | Every approved task met its acceptance evidence | repair |
-| `G-ORACLES` | Regression oracles red on baseline, green on candidate, independently verified | repair |
+| `G-ORACLES` | Each task's oracle red on baseline and green on candidate as [its kind requires](repair-and-measurement.md#oracles-by-finding-kind), independently verified | repair |
 | `G-NO-REGRESSION` | No new regression, skipped required check, or unapproved behavior change | repair |
 | `G-PERF-TARGETS` | Approved targets and guardrails demonstrated (N/A only when none approved) | repair |
 | `G-PRESERVATION` | Behavior, UI/UX and public-contract preservation evidence | repair |
@@ -215,8 +239,13 @@ frontend `Q_l = 9.0` → `NOT_READY`.
 `devrites-engine overhaul score --rubric <rubric.json> --results <results.json> --gates <gates.json>
 [--out <scorecard.json>]` computes the scorecard; `devrites-engine overhaul score compare --rubric
 <rubric.json> --baseline <a.json> --candidate <b.json>` labels control transitions.
-Inputs: the immutable rubric, a results file (`overhaul.results/1`: `rubric_digest`,
-`subject`, `fingerprint`, `results{control_id: {status, evidence[], verified_by}}`)
+Inputs: the immutable rubric, a results file (`overhaul.results/1`: `rubric_digest`
+(required; the SHA-256 of the rubric file, checked by `score` and by both arms of
+`compare`), `subject`, `fingerprint`, `results{control_id: {status, evidence[],
+verified_by}}`)
 and a gates file (`overhaul.gates/1`: `mode` `audit|remediation`, `gates{id: {status,
 evidence[], reason, approval}}`). Exit 2 means invalid input: nothing may be treated
-as scored.
+as scored. `G-THRESHOLDS` and `G-MANDATORY` are computed; `validate` rejects a
+scorecard whose `G-NO-CRITICAL-HIGH`, `G-NO-OPEN-SERIOUS-LEAD` or `G-COVERAGE` PASS
+contradicts `findings.json` or `coverage.json`, and a control recorded PASS while a
+linked finding is still open ([`records.md`](records.md#enforced-versus-review-only)).