@brunosps00/dev-workflow 2.2.0 → 2.4.0

package/scaffold/skills/dw-review-rigor/SKILL.md

@@ -14,88 +14,46 @@ A set of rules the caller applies while producing a review report. This skill do
 
 ## When Invoked
 
-By `/dw-review --code-only`, `/dw-review --coverage-only`, `/dw-refactor`, and `/dw-brainstorm --mode=refactor-audit`. The caller has already identified a scope (files, a PR, a codebase area). This skill governs how findings are selected, deduplicated, ordered, and phrased.
+By `/dw-review --code-only` (all five rules plus the full candidate pipeline), `/dw-review --coverage-only` (de-dup and severity-ordering on PRD-vs-code gaps), `/dw-refactor` and `/dw-brainstorm --mode=refactor-audit` (rules 1, 2, 4, 5; rule 3 adapts, so a smell with a justifying ADR becomes a `low` finding at most). The caller has already identified a scope — files, a PR, a codebase area — and this skill governs how findings are selected, deduplicated, ordered, and phrased.
 
 ## Required Inputs
 
 - The scope the caller is reviewing (file paths, directories, or PR diff).
-- Optional: prior review reports in `.dw/spec/prd-*/reviews/` — so this round only surfaces NEW findings.
+- Optional: prior review reports for the same target, so this round surfaces only NEW findings. See Prior-Round Awareness.
 
-## Pre-Report Gate
+## Candidate Pipeline
 
-Before writing ANY finding, clear four checks — if any is "no"/"unsure", downgrade or drop it (an unactionable finding is noise):
+Nothing you notice is a finding yet. Everything enters as a **candidate** and leaves through exactly one of three exits: `finding`, `needs-validation`, or `rejected`. There is no fourth — a candidate that quietly disappears is a defect of the review.
+
+**Stage 1 — Gate.** Clear four checks; any "no" or "unsure" means this is not ready to be a finding:
 
 1. **Location** — exact file and line?
 2. **Failure mode** — a concrete input/state and the bad outcome it produces?
 3. **Context** — read the surrounding code (callers, imports, tests), not just the flagged line?
 4. **Severity** — defensible against Rule 2's definitions? (a missing JSDoc is never HIGH)
 
-Report only findings you are **>80% confident** are real. A style preference no rule backs is not a finding. See `references/false-positives.md` for patterns LLM reviewers habitually mis-flag.
-
-## The Five Rules
-
-### 1. De-duplicate before writing
-
-If the same pattern (e.g., missing null check, unhandled error, magic constant) appears in multiple files, **create one finding** for the most representative instance and list the other affected files inside its body. Do not create N identical findings for N files sharing one root cause.
-
-Example — wrong:
-```
-- [HIGH] src/a.ts:14 — missing null check on user
-- [HIGH] src/b.ts:22 — missing null check on user
-- [HIGH] src/c.ts:31 — missing null check on user
-```
-
-Example — right:
-```
-- [HIGH] Missing null check on `user` in 3 places.
-  Representative: src/a.ts:14
-  Also affects: src/b.ts:22, src/c.ts:31
-  Fix: add `if (!user) return` at function entry.
-```
-
-### 2. Severity-order the output
-
-Always present findings in this order: **critical → high → medium → low**. Inside each severity, order by impact or blast radius, not by file path.
+See `references/false-positives.md` for patterns LLM reviewers habitually mis-flag.
 
-Severity definitions:
-- **critical** — correctness bug, security hole, data loss, unavailability.
-- **high** — material deviation from PRD/TechSpec, concurrency hazard, significant perf regression, missing error handling on a user path.
-- **medium** — maintainability cost that will hurt the next change, missing edge-case handling, inconsistent with project rules.
-- **low** — stylistic, naming, minor readability. Often omit unless pattern-level.
+**Stage 2 — Refutation.** The reasoning that produced a candidate cannot also be its check; it anchors every reading that follows. Each candidate clearing Stage 1 faces a deliberate attempt to disprove it. With subagents, dispatch `dw-finding-refuter` with the claim and the raw code, never the reasoning behind it, one candidate per dispatch. Otherwise re-derive the path from source, working to show the outcome cannot happen. Packet contract, upstream guards and both output formats: `references/refutation-pass.md`.
 
-### 3. Verify intent before flagging
+**Stage 3 — Disposition.** Holds on evidence the refutation found for itself → `finding`, with a severity. Blocked upstream, input unreachable, or behavior intended → `rejected`, one line at the end of the report naming what disproved it. Cannot be established either way → `needs-validation`, which never receives a severity and records what is missing and what would settle it. When the environment needed to settle a claim is unavailable, it **stays** `needs-validation` — not promoted, not dropped. Each exit carries different fields: contract in `references/refutation-pass.md`.
 
-Before creating a finding, check whether the pattern is intentional:
-- adjacent comment explaining the choice?
-- ADR in `.dw/spec/*/adrs/` that justifies it?
-- test coverage that asserts the behavior?
-- rule in `.dw/rules/` that permits it?
+Report only findings you are **>80% confident** are real *after* Stage 2. Three needs-validation entries and one finding is a more honest round than four.
 
-If the code looks suspicious but has a clear justification (e.g., `// intentionally ignoring close error on read-only handle`), do NOT create a finding. Only flag patterns that are genuinely problematic, not merely unconventional.
-
-### 4. Skip what linters already catch
-
-Before writing findings, ensure the project's linter/formatter has run. Anything the configured linter would flag is NOT a finding in this review — it is a linter task. Save human attention for issues linters cannot find (logic, architecture, security, requirements).
-
-If the linter cannot run (missing tooling, build errors), note that in the summary and proceed with the review.
-
-### 5. Signal over volume
-
-Aim for fewer, higher-quality findings.
+## The Five Rules
 
-- Keep ALL `critical` and `high`.
-- If total findings exceed 20, prune `medium` and `low` to the most impactful ones.
-- A review with 8 precise findings is more useful than one with 30 that includes marginal concerns.
+For the five rules, read `references/the-five-rules-detail.md`. Load only when this part of the task applies.
 
-**Also note well-implemented aspects.** They inform the summary and calibrate tone — but they do not produce findings.
+When the scope is an already-merged range (`/dw-review --post-merge`), also read `references/composition-audit.md`: the seven cross-interaction classes, the composition-only defect checklist, the documentation ledger and the semver recommendation.
 
 ## Prior-Round Awareness
 
-If the PRD directory has prior review reports:
+Prior reports live in `<target>/QA/` (PRD target) or `<target>/review/` (bugfix target). Read them and extract three lists — known findings (titles + file/line signatures), open `needs-validation` entries, rejected candidates — then:
 
-1. Read them and extract the list of known findings (their titles + file/line signatures).
-2. The current round surfaces **only NEW findings**. Do not re-flag items already tracked as pending, resolved, or accepted in earlier rounds.
-3. If a prior finding was resolved incorrectly, open it as a NEW finding with "Regression of <prior ref>" in the body.
+1. Surface **only NEW findings**. Do not re-flag items already tracked as pending, resolved, or accepted.
+2. Re-check every open `needs-validation` entry. Resolve it into a finding or a rejection when this round has the missing evidence; otherwise carry it forward unchanged. Carrying it forward is a valid outcome — dropping it is not.
+3. Do not re-raise a rejected candidate unless the code changed in a way that defeats the recorded refutation. Name what changed.
+4. If a prior finding was resolved incorrectly, open it as a NEW finding with "Regression of <prior ref>" in the body.
 
 ## Finding Format
 
@@ -115,14 +73,13 @@ Evidence: <relevant code snippet, test output, or reference>
 
 The caller emits:
 
-1. **Merge/ship recommendation** — one of:
-   - `Needs fixes before merge` (if any critical or high exist), with blocking findings named.
-   - `Safe to merge with follow-ups` (only medium/low).
-   - `Clean — ready to merge` (no findings).
+1. **Merge/ship recommendation** — `Needs fixes before merge` when any critical or high exists, naming the blockers; `Safe to merge with follow-ups` for medium/low only; `Clean — ready to merge` for none.
 2. **Counts** — critical / high / medium / low.
 3. **Findings** — ordered by severity, each in the format above.
-4. **Well-implemented aspects** — short bulleted list, calibrates tone.
-5. **Self-score** — rate the report on the five axes in `references/self-eval-rubric.md`; any axis below top cites the gap, then fix (<30s) or flag.
+4. **Needs Validation** — open questions carried by this round, without severities.
+5. **Rejected Candidates** — one line per refuted candidate, with what disproved it.
+6. **Well-implemented aspects** — short bulleted list, calibrates tone.
+7. **Self-score** — rate the report on the five axes in `references/self-eval-rubric.md`; any axis below top cites the gap, then fix (<30s) or flag.
 
 ## Critical Rules
 
@@ -131,33 +88,19 @@ The caller emits:
 - Do not flag patterns that have a clear adjacent justification or ADR.
 - Do not write N identical findings for one root cause — de-duplicate.
 - Do not mix severities — order is critical → high → medium → low.
-
-## Integration With Other dev-workflow Commands
-
-- `/dw-review --code-only` — applies all five rules to its Level-3 review output; uses prior reports in `.dw/spec/*/reviews/` to dedupe across rounds.
-- `/dw-review --coverage-only` — applies de-dup + severity-ordering when listing gaps between PRD requirements and code.
-- `/dw-refactor` — applies rules 1, 2, 4, 5 when cataloging code smells (rule 3 adapts: a "smell" with a justifying ADR becomes a `low` finding at most).
-
-Callers should mention this skill in their "Skills Complementares" section.
+- Do not assign a severity to anything that did not survive Stage 2.
+- Do not delete a candidate — route it to findings, needs-validation, or rejected.
 
 ## Inspired by
 
-Ported from Compozy's `cy-review-round` skill (`/tmp/compozy/.agents/skills/cy-review-round/SKILL.md`). Adapted for dev-workflow:
-
-- No `reviews-NNN/` directory convention — dev-workflow reviews already persist in `.dw/spec/*/reviews/` per command's existing contract.
-- The five rules are extracted here so three different dev-workflow review commands can share the discipline without duplicating it.
-- No issue-file frontmatter (Compozy uses it to interoperate with its remediation engine; dev-workflow's remediation is manual or via `/dw-qa --fix`).
-
-Credit: Compozy project (https://github.com/compozy/compozy).
+The five rules are ported from Compozy's `cy-review-round` (credit: [Compozy](https://github.com/compozy/compozy), MIT), extracted here so three review commands share one discipline. The candidate pipeline, `needs-validation` and the rejected-candidate log originate in [`cloudflare/security-audit-skill`](https://github.com/cloudflare/security-audit-skill) (MIT), reaching us via `akitaonrails/my-skills` — chain: cloudflare → akitaonrails → dev-workflow. Reimplemented independently; no upstream text reused.
 
 ## Structured Return
 
-When invoked directly or by a harness, return or merge this block:
-
-- **Status:** `PASS` when no defensible findings remain, `FINDINGS` when review findings exist, `BLOCKED` when diff/context is insufficient, `NOT_APPLICABLE` when no review is in scope.
+- **Status:** `PASS` when no defensible findings remain (open `needs-validation` entries do not block it, but each must be listed), `FINDINGS` when review findings exist, `BLOCKED` when diff/context is insufficient, `NOT_APPLICABLE` when no review is in scope.
 - **Scope:** diff range, files reviewed, prior rounds, and review mode.
-- **Evidence:** file/line references, behavior impact, and prior-round disposition.
+- **Evidence:** file/line references, behavior impact, the refutation each finding survived, prior-round disposition.
 - **Artifacts:** review report, inline findings, or consolidation notes.
-- **Decisions:** finding severity/order, duplicate suppression, and false-positive rejection.
-- **Risks:** missing tests, unreviewed generated files, stale base branch, or non-defensible claims.
-- **Next Step:** exact fix, verification, or approval/block marker.
+- **Decisions:** severity and order, duplicate suppression, and every refuted candidate with what disproved it.
+- **Risks:** missing tests, unreviewed generated files, stale base branch, non-defensible claims, open `needs-validation` entries.
+- **Next Step:** exact fix, verification, what would resolve each `needs-validation` entry, or the approval/block marker.

package/scaffold/skills/dw-review-rigor/references/composition-audit.md

@@ -0,0 +1,160 @@
+# Composition Audit — reviewing N merged PRs as one state
+
+Loaded by `/dw-review --post-merge`. It does not replace the five rules or the candidate pipeline; it
+changes what you go looking for when the unit of review is a merged range instead of one branch.
+
+## What changes when the scope is a range
+
+Every PR in the range was reviewed alone and passed alone. That is exactly why this pass exists: the
+defects below need two changes to exist, so no per-PR review could have caught them, and the collection of
+per-PR summaries is optimistic by construction. Audit the final tree, not the summaries.
+
+Two consequences for severity. A defect here is already shipped, which changes **urgency**, not severity —
+do not inflate a medium because it is live, and do not discount a critical because "it has been fine so
+far". And the range is the only honest unit: a finding that says "PR #3 broke it" is usually wrong, because
+what broke it is #3 meeting #7.
+
+## The seven interaction classes
+
+### 1. Invariant bridges
+
+One PR adds a field, column, flag, or route; another populates or authorizes it somewhere that is not the
+canonical boundary. The writer looks fine (it writes a legitimate value) and the reader looks fine (it
+reads a field that exists), but the invariant the boundary was supposed to enforce is now bypassed.
+
+- *Detection:* for each new field or path added in the range, `git log -S'<name>' --oneline <range>` to
+  find every commit that touched it, then check whether the writers all pass through the same guard.
+- *False positive:* a deliberate second writer with its own validation. Read it before flagging.
+- *Minimum severity:* high when the bypassed boundary is authorization or tenancy, otherwise medium.
+
+### 2. Helper and policy drift
+
+Two PRs each add or change normalization, identity comparison, validation, retry, error mapping, or a
+permission check — and the two copies now disagree. The system behaves differently depending on which path
+the request took.
+
+- *Detection:* `git diff <range> --name-only` grouped by subsystem, then grep for near-duplicate helper
+  names and for the same literal in two places.
+- *False positive:* intentional divergence with different requirements. Look for a comment or an ADR.
+- *Minimum severity:* medium; high when the two copies disagree about a security decision.
+
+### 3. Default and config composition
+
+Each default was compatible on its own. Together they change behavior, create ambiguity, or enable
+something that was meant to stay off. The classic shape: one PR flips a default to "on for new installs"
+and another adds a code path that assumes it is off.
+
+- *Detection:* list every default, env var, feature flag, and config key the diff touches, then evaluate
+  them as a set, not one at a time. Check the upgrade case — existing installs — separately from a fresh one.
+- *Minimum severity:* high when the composed state is insecure or data-losing.
+
+### 4. Order and lifecycle
+
+Startup and shutdown ordering, retries, cleanup, transactions, rollback, background jobs, leases. One PR
+adds work at a lifecycle point; another changes when that point runs.
+
+- *Detection:* find the lifecycle entry points in the range and read them whole, not as hunks. Ask what
+  happens on the second run, on a crash between the two changes, and on rollback.
+- *Minimum severity:* high when a partial state can persist.
+
+### 5. Shared resource behavior
+
+Queues, connection pools, files, ports, rate limits, caches, locks, disk. Two PRs that each take a
+reasonable share of a bounded resource can together exhaust it.
+
+- *Detection:* for each bounded resource the range touches, sum the new consumers. Look for a new consumer
+  added to a pool whose size did not change.
+- *Minimum severity:* medium, high when the bound is reached under normal load rather than attack.
+
+### 6. Schema, API, and data composition
+
+Migrations, wire schemas, public functions, CLI flags, persisted data, older callers. Two migrations that
+each apply cleanly to the pre-range state may not compose; an additive API change plus a rename is a break.
+
+- *Detection:* apply the migrations in range order against a copy of the pre-range schema, not against a
+  fresh one. For public surfaces, diff the signature set at `BASE_SHA` against `HEAD_SHA` rather than
+  reading the PRs' claims.
+- *Minimum severity:* high for anything a released caller can hit.
+
+### 7. Test masking
+
+The one that most reliably hides in a green build: one PR's mock, fixture, helper, or test config makes
+another PR's test pass without exercising production behavior. Both PRs were green. The composed suite is
+green. The feature does not work.
+
+- *Detection:* for each test added in the range, check whether the production path it claims to cover is
+  actually reached — a global mock registered in shared setup, an autouse fixture, a stubbed client, a
+  widened test config. Where feasible, revert the production change and confirm the test goes red.
+- *False positive:* a legitimately isolated unit test whose integration coverage lives elsewhere. Find that
+  elsewhere before flagging.
+- *Minimum severity:* high — a test that cannot fail is worse than no test, because it is counted as
+  coverage.
+
+## Composition-only defect checklist
+
+Run this after the seven classes. These are shapes that per-PR review systematically misses:
+
+- an **additive feature that broke a public API by accident** — additive intent does not excuse an
+  unrelated signature change;
+- a **fallback that now swallows an unrelated error** — the fallback was added for one failure and now
+  catches a second one introduced later;
+- a **test bound to a real home directory, platform, clock, network, or live service** — it passes on the
+  machine that wrote it;
+- **one entry point fixed while its parallel implementation went stale** — CLI fixed, API not; one platform
+  fixed, the other not;
+- **code only the development platform's gate exercises.** This is the highest-yield item in the list,
+  because a single-platform fast gate cannot see any of it:
+  - path identity that assumes one canonical spelling — symlinked temp and home roots, drive letter versus
+    POSIX separators, a trailing separator, case sensitivity;
+  - file-locking semantics that differ per OS;
+  - stderr and exit-code differences between platforms for the same command;
+  - line endings in anything compared as text.
+
+  Flag these for the full matrix rather than trusting the merge gate. A red matrix is a real finding — do
+  not route around it.
+
+## Documentation ledger
+
+Build the surface list from the **diff**, never from the PRs' prose. A PR body describes what someone meant
+to ship; the diff describes what shipped.
+
+Surfaces to enumerate: features, fixes, changed defaults, flags, env and config fields, supported
+platforms, endpoints, public APIs, schemas, migrations, install and deploy steps, security behavior.
+
+For each surface, find every authoritative location and look for a **description that is now wrong**, not
+only a name that is missing. A stale sentence is worse than an absent one: it is confidently incorrect.
+The usual homes are the README's support and compatibility tables, examples, the architecture and config
+reference, migration notes, and platform docs.
+
+## Semver recommendation
+
+From the diff:
+
+- only fixes → **patch**;
+- any additive surface → **minor**;
+- any break — on-disk format, public API, CLI or wire contract, a removed surface → **major**.
+
+State the recommendation and the **single highest-impact entry** that forces it, so the reader can check
+the one thing the conclusion rests on.
+
+Then check two changelog hazards that a heading-uniqueness script cannot catch:
+
+- **An entry stranded in an already-released section.** A PR authored before a release was cut anchors its
+  entry at the old position of "Unreleased". Merging the mainline back can resolve *cleanly, with no
+  conflict*, and leave the entry inside the now-frozen released section — claiming the change shipped in a
+  version that never contained it. Compare the changelog at `BASE_SHA` with the lines the range added:
+  `git diff <BASE_SHA>...<HEAD_SHA> -- <changelog>`, and confirm each new entry sits under the pending
+  heading.
+- **Merge-resolution residue.** `git diff --check` flags leftover conflict markers, but scripted resolution
+  also leaves diff3 base markers (`|||||||`) and duplicated bullets, which no uniqueness check sees. Grep
+  for the marker and scan for repeated entries.
+
+This section produces a recommendation and nothing else. `/dw-review --post-merge` does not tag, bump, or
+publish.
+
+## Attribution
+
+The boundary freeze, provenance inventory, cross-interaction sweep, documentation ledger and the two
+changelog hazards were reimplemented independently from the technique described in
+`akitaonrails/my-skills`. That repository declares no license; no upstream text, structure or file was
+reused, and no reuse license is assumed. The release step described there was deliberately not ported.

package/scaffold/skills/dw-review-rigor/references/refutation-pass.md

@@ -0,0 +1,124 @@
+# Refutation Pass — disprove the candidate before it becomes a finding
+
+A candidate is a hypothesis produced by one line of reasoning. That same reasoning cannot test it: once a
+conclusion is reached, every later reading is pulled toward it. Re-reading your own trace feels like
+verification and is not. The pass below replaces the reader.
+
+## With a subagent: the refutation packet
+
+Dispatch `dw-finding-refuter`, **one candidate per run**. It receives exactly this and nothing else:
+
+| Include | Exclude |
+|---|---|
+| The claim in one sentence: location, input or state, bad outcome | How the candidate was found |
+| The raw code — the flagged lines, the file, the entry points that reach it | Your confidence and your severity |
+| Which commands it may run | Every other candidate from this round |
+| — | Prior-round text, the PRD, the diff summary |
+
+Severity is withheld deliberately. A candidate handed over labelled `critical` comes back confirmed more
+often than the identical candidate labelled `medium`, and that difference is the anchor, not the evidence.
+
+The refuter returns `REFUTED`, `HOLDS`, or `UNRESOLVED`. One case needs care: if it returns `HOLDS` citing
+only the `file:line` you handed it, that is an echo, not confirmation. Treat it as `UNRESOLVED`.
+
+## Without a subagent: re-derive from zero
+
+Read the path as if you had never seen the candidate — start at the entry point, move forward, and reach
+the flagged line **last**. The objective is to show the bad outcome cannot occur. Work the list in order
+and stop at the first hit:
+
+1. **Validation upstream** — a schema, parser, or guard clause the value already passed.
+2. **Permission upstream** — an authorization check, middleware, or policy on the route.
+3. **A type or schema that cannot hold the bad value** — a typed boundary, an enum, a branded type, a
+   `NOT NULL` constraint.
+4. **A framework or runtime default** — auto-escaping, parameterized queries, CSRF middleware, a default
+   timeout.
+5. **Configuration that is not what the claim assumed** — read the config file; do not infer it from
+   naming.
+6. **Intent** — a test asserting the behavior, an adjacent comment, an ADR, a rule under `.dw/rules/`.
+
+If everything you can say about the candidate at the end is what you already said at the start, the result
+is `UNRESOLVED`, not confirmed.
+
+## What each exit may and may not carry
+
+The three exits are not three severities of the same thing — they are three different claims, and each one
+is entitled to different fields. Most of the damage a review does comes from mixing them: a severity on an
+unresolved lead reads as an assessed risk, and a remediation on a refuted claim sends someone to fix
+nothing.
+
+| Exit | Carries | **Must not carry** |
+|---|---|---|
+| `finding` | The confirmed cause, the reachable input or state, the observable outcome, the fix, a severity | A *claimed* cause — by this point it is established or it is not a finding |
+| `needs-validation` | The **claimed** cause, the trace, the evidence so far, what blocks resolution, and how to resolve it | **A severity.** Also no fix and no exploit path — you do not have the facts those require |
+| `rejected` | The claim as it was made, and what disproved it | A severity, a fix, an exploit path, a blocker — the claim is closed, not pending |
+
+The prohibition on severity for `needs-validation` is the load-bearing one. A severity is an assessment of
+impact, and an unresolved lead has not established the impact. "Possible critical" is not a cautious
+finding; it is a number with nothing behind it, and it will be read as a ranking.
+
+## Degradation: no environment means unresolved, not resolved
+
+When the environment needed to settle a claim is unavailable — no sandbox, no runtime, no access to the
+configuration that decides it — the candidate stays `needs-validation`. It is not promoted because the
+reasoning looked strong, and it is not dropped because it could not be checked.
+
+This is the rule that keeps the class honest. Without it, a missing environment quietly turns into whatever
+the reviewer already believed.
+
+## needs-validation format
+
+```
+[needs-validation] <file.ext>:<line> — <what is unresolved, ≤72 chars>
+
+Unresolved: <the specific fact that could not be established>
+Blocked by: <why — missing runtime config, unreadable caller, external system, no test data>
+Resolved by: <the concrete thing that would settle it — a file, a command, an owner's answer>
+```
+
+No severity. No "possible critical", no "likely exploitable". The whole point of the class is that you do
+not know yet, and saying so plainly is the honest output. A severity attached here is a severity invented.
+
+## Rejected candidate format
+
+One line each, under `## Rejected Candidates` at the end of the report:
+
+```
+- <claim in one line> → refuted: <what disproves it> (<file:line or command>)
+```
+
+Keep it even when it feels like clutter. The line is what stops the next round from rediscovering the same
+false positive and paying for the same refutation twice.
+
+## Anti-patterns
+
+- **Sending the refuter your reasoning "for context."** That is the exact failure this pass exists to
+  prevent; the packet is short on purpose.
+- **Refuting a batch.** One candidate per run. Batching restores the shared frame you were trying to
+  escape.
+- **Letting the refuter open findings of its own.** Its output is a verdict on one claim. New observations
+  it makes along the way are for the next round, not this report.
+- **Promoting `UNRESOLVED` to a finding** because the round would otherwise look thin. Three
+  `needs-validation` entries and one finding is a more honest round than four findings.
+- **Deleting a refuted candidate** instead of logging it.
+- **Treating "the refuter found no blocker" as proof.** Absence of a refutation is `UNRESOLVED` unless the
+  refuter cited independent evidence for `HOLDS`.
+
+## Proportionality
+
+The pass is for candidates that will carry a severity. A duplicate of an already-reported root cause, a
+finding the configured linter owns, or a cosmetic note does not need a refuter — it needs to be dropped or
+merged under Rule 1. Spend the pass where a wrong answer would cost something.
+
+## Attribution
+
+The three-outcome discipline — adversarial refutation by a reader who did not produce the claim, an
+unresolved-lead class that carries no severity, and a durable record of rejected candidates — originates in
+[`cloudflare/security-audit-skill`](https://github.com/cloudflare/security-audit-skill) (MIT), which calls
+it adversarial verification, needs-validation discipline and coverage honesty. It reached this project
+through `akitaonrails/my-skills`, which credits Cloudflare for the same model and declares no license of
+its own. **Attribution chain: cloudflare → akitaonrails → dev-workflow.**
+
+The per-exit field contract and the degradation rule above come from reading the Cloudflare skill directly:
+there they are enforced by a JSON schema and a validator script, and here they are prose, because our
+reviews are markdown reports rather than validated records. No upstream text or file was reused.

package/scaffold/skills/dw-review-rigor/references/the-five-rules-detail.md

@@ -0,0 +1,56 @@
+## The Five Rules
+
+### 1. De-duplicate before writing
+
+If the same pattern (e.g., missing null check, unhandled error, magic constant) appears in multiple files, **create one finding** for the most representative instance and list the other affected files inside its body. Do not create N identical findings for N files sharing one root cause.
+
+Example — wrong:
+```
+- [HIGH] src/a.ts:14 — missing null check on user
+- [HIGH] src/b.ts:22 — missing null check on user
+- [HIGH] src/c.ts:31 — missing null check on user
+```
+
+Example — right:
+```
+- [HIGH] Missing null check on `user` in 3 places.
+  Representative: src/a.ts:14
+  Also affects: src/b.ts:22, src/c.ts:31
+  Fix: add `if (!user) return` at function entry.
+```
+
+### 2. Severity-order the output
+
+Always present findings in this order: **critical → high → medium → low**. Inside each severity, order by impact or blast radius, not by file path.
+
+Severity definitions:
+- **critical** — correctness bug, security hole, data loss, unavailability.
+- **high** — material deviation from PRD/TechSpec, concurrency hazard, significant perf regression, missing error handling on a user path.
+- **medium** — maintainability cost that will hurt the next change, missing edge-case handling, inconsistent with project rules.
+- **low** — stylistic, naming, minor readability. Often omit unless pattern-level.
+
+### 3. Verify intent before flagging
+
+Before creating a finding, check whether the pattern is intentional:
+- adjacent comment explaining the choice?
+- ADR in `.dw/spec/*/adrs/` that justifies it?
+- test coverage that asserts the behavior?
+- rule in `.dw/rules/` that permits it?
+
+If the code looks suspicious but has a clear justification (e.g., `// intentionally ignoring close error on read-only handle`), do NOT create a finding. Only flag patterns that are genuinely problematic, not merely unconventional.
+
+### 4. Skip what linters already catch
+
+Before writing findings, ensure the project's linter/formatter has run. Anything the configured linter would flag is NOT a finding in this review — it is a linter task. Save human attention for issues linters cannot find (logic, architecture, security, requirements).
+
+If the linter cannot run (missing tooling, build errors), note that in the summary and proceed with the review.
+
+### 5. Signal over volume
+
+Aim for fewer, higher-quality findings.
+
+- Keep ALL `critical` and `high`.
+- If total findings exceed 20, prune `medium` and `low` to the most impactful ones.
+- A review with 8 precise findings is more useful than one with 30 that includes marginal concerns.
+
+**Also note well-implemented aspects.** They inform the summary and calibrate tone — but they do not produce findings.

package/scaffold/skills/dw-simplification/SKILL.md

@@ -30,64 +30,11 @@ Do NOT use when:
 
 ## The Five Rules
 
-### 1. Chesterton's Fence — understand BEFORE changing
-
-Before removing or rewriting any code, answer three questions:
-
-1. **What does it actually do?** Run/trace it; don't guess from the name.
-2. **Why was it added?** Check `git log --follow <file> --oneline` and look at the introducing commit's message + PR. Often there's a reason.
-3. **What breaks if it's gone?** Search for callers. Run the test suite to find what changes.
-
-If you can't answer all three, you're not ready to simplify. Get answers first.
-
-Concrete cases where Chesterton's Fence saves you:
-- A "redundant" early return that handles a race condition.
-- A "useless" type cast that fixes a compiler bug on a specific platform.
-- A "duplicated" check that exists for clarity at the API boundary.
-- A "dead" branch that runs only with a feature flag enabled in production.
-
-### 2. Preserve behavior exactly
-
-The test for "did I simplify or did I change?" is: do the existing tests still pass without modification? If yes, behavior is preserved. If you needed to update tests, you changed behavior — that's a refactor, not a simplification.
-
-When tests are inadequate to confirm behavior preservation, write tests FIRST that document current behavior, then simplify against them. This is the test characterization technique.
-
-### 3. Follow project conventions
-
-Match what the project already does. If files use 2-space indent and arrow functions, your simplified version uses 2-space indent and arrow functions — even if you'd prefer 4-space and `function`. Conventions matter more than personal preference; consistency is itself a form of clarity.
-
-Project conventions live in `.dw/rules/<module>.md` (from `/dw-analyze-project`). Read first.
-
-### 4. Prefer clarity over cleverness
-
-Rules of thumb:
-
-- A line of code that takes 30 seconds to understand is worse than three lines that take 5 seconds each.
-- A "neat trick" with comments is uglier than the boring obvious code without comments.
-- Optimization that costs readability needs measurement (`dw-performance` skill territory) — without numbers, prefer the readable version.
-- "Magic" that requires knowing a language feature most teammates haven't used is anti-clarity. Use it only when the alternative is genuinely worse.
-
-### 5. Scope to recent changes
-
-Don't go simplifying old code while you're "in there". The risk-to-benefit ratio of changing 5-year-old battle-tested code is bad. Limit simplification to:
-
-- Code you just wrote in this session.
-- Code your current task touches.
-- Code with explicit recent breakage (e.g., a bug just fixed that revealed bad structure).
-
-Out of scope: any other code, no matter how ugly. Open a task / ADR for those instead of fixing in-flight.
+For the five rules, read `references/the-five-rules-detail.md`. Load only when this part of the task applies.
 
 ## Pattern recognition
 
-Frequent simplification targets — but apply Rules 1-5 before acting:
-
-| Smell | Healthy refactor | When NOT to refactor |
-|-------|------------------|----------------------|
-| Deep nesting (4+ levels) | Early returns / guard clauses | When the nesting maps to a real domain hierarchy (e.g., visitor pattern) |
-| Long function (>50 lines) | Extract method | When the "natural" extraction would produce 3-4 single-call helpers — you're trading complexity for indirection |
-| Generic name (`data`, `info`, `helper`) | Rename to specific | When the function genuinely processes generic input (e.g., a serializer middleware) |
-| Duplication (same 5 lines twice) | Extract to function/constant | When the duplication is by design (e.g., independent business rules that may diverge) |
-| `if/elif/else` chain (5+ branches) | Strategy pattern / lookup table | When the branches are naturally exclusive states with branch-specific logic |
+For pattern recognition, read `references/pattern-recognition-detail.md`. Load only when this part of the task applies.
 
 ## Rule of 500 — automate large refactors
 

package/scaffold/skills/dw-simplification/references/pattern-recognition-detail.md

@@ -0,0 +1,11 @@
+## Pattern recognition
+
+Frequent simplification targets — but apply Rules 1-5 before acting:
+
+| Smell | Healthy refactor | When NOT to refactor |
+|-------|------------------|----------------------|
+| Deep nesting (4+ levels) | Early returns / guard clauses | When the nesting maps to a real domain hierarchy (e.g., visitor pattern) |
+| Long function (>50 lines) | Extract method | When the "natural" extraction would produce 3-4 single-call helpers — you're trading complexity for indirection |
+| Generic name (`data`, `info`, `helper`) | Rename to specific | When the function genuinely processes generic input (e.g., a serializer middleware) |
+| Duplication (same 5 lines twice) | Extract to function/constant | When the duplication is by design (e.g., independent business rules that may diverge) |
+| `if/elif/else` chain (5+ branches) | Strategy pattern / lookup table | When the branches are naturally exclusive states with branch-specific logic |