@brunosps00/dev-workflow 2.2.0 → 2.4.0

package/scaffold/skills/dw-testing-discipline/references/mutation-testing.md

@@ -0,0 +1,19 @@
+# Investigating weak tests with mutations
+
+Use when an important behavior has weak evidence, when auditing tests, or when the approved testing strategy includes mutation analysis. Do not install a mutation framework for a copy edit or make every test change run a repository-wide campaign.
+
+1. Name the behavior at risk and inspect its production path and tests. Select a bounded module and the existing runner. Confirm a clean baseline test run so unrelated failures are not misreported as detected mutants.
+2. Run the installed mutation tool with an explicit source scope and inspect its execution status. If unavailable, a reversible deliberate defect in an isolated copy can probe one invariant; report it as a targeted experiment, not a complete mutation score. Never leave a deliberate defect in the delivery tree.
+3. For a survivor, examine the changed expression, reachable inputs and expected observable result. Distinguish a missing assertion from equivalent behavior, unreachable code, exclusion, timeout or tooling failure. Report unassessed cases instead of calling them safe.
+4. Add or strengthen a test only for a meaningful missing behavior. Derive expected values from requirements, fixtures or an independent oracle; do not repeat the algorithm under test. Ensure mocks match real module exports and API contracts. Assertions on shape, invocation or snapshots are useful only when that is the actual contract being protected.
+5. Demonstrate that the selected defect is detected and the unmodified implementation passes. Record source scope, cases investigated, remaining limitations, command, tool version and report path. Do not weaken assertions, alter production semantics or exclude survivors just to improve a number.
+
+Do not introduce a default mutation-score gate. Preserve existing project-required policy and raise a proposal if it needs revision. A run can succeed while reporting surviving mutants; a tool crash or zero selected files does not establish successful behavioral validation.
+
+## Incremental execution
+
+[StrykerJS incremental mode](https://stryker-mutator.io/docs/stryker-js/incremental/) reuses a prior report; it is not automatically selection of the current PR diff. Determine the PR base and intended source set separately. Include test changes and affected production scope. An empty selection must be explicitly justified.
+
+Stryker's cache does not detect every dependency, configuration, snapshot or environment change. Invalidate reuse when those inputs affect results; use the installed version's supported force/full-scope mechanism. Preserve the unmutated dry run and check runner support for test-change detection. Reuse under `dw-verify` also requires valid input and environment evidence.
+
+In CI, publish inspectable reports and distinguish infrastructure failures from investigated survivors. Select schedule and scope according to risk and measured cost. Broad campaigns belong in an agreed audit or scheduled job, not an implicit requirement on unrelated tasks.

package/scaffold/skills/dw-testing-discipline/references/patterns.md

@@ -192,20 +192,11 @@ No merge to main without a real-system path going green. Mocks are speed, real i
 
 **Anti-pattern:** 100% mocked test suite. "It all passes locally" → first user request fails because the mock didn't match the real API shape.
 
-## 11. Mutation score over coverage percentage
+## 11. Mutation analysis investigates specific behavioral gaps
 
-**Pattern:**
-
-Set up mutation testing (Stryker for JS/TS, mutmut for Python, etc.) ONCE per project. Run weekly on critical modules.
-
-```bash
-npx stryker run
-# Output: 87 mutants, 78 killed, 9 survived → mutation score 89.6%
-```
-
-A surviving mutant means: this code path runs in tests, but the tests don't actually assert anything that breaks when the code changes. Investigate each.
+Use `mutation-testing.md` when critical behavior or weak assertions justify the cost. Inspect survivors individually: they may expose missing tests, equivalent behavior or analysis limits. Strengthen assertions against the intended contract and verify both the deliberate defect and unmodified behavior. Choose scope and cadence from project risk; do not install a tool in every project or introduce a score target.
 
-**Anti-pattern:** 95% line coverage with assertions like `expect(result).toBeTruthy()` — every line ran, but mutations all survive. The suite is decorative.
+**Anti-pattern:** increasing coverage or killing mutants while assertions still repeat the implementation or only confirm mock setup.
 
 ## 12. Page Object Model is a tool, not a religion
 

package/scaffold/skills/dw-ui-discipline/SKILL.md

@@ -23,70 +23,13 @@ If you're tempted to skip this "because it's just a small tweak" — that's the
 
 ## The four grounding questions
 
-Answer all four before proposing colors, layouts, components, or any visual decision.
-
-### 1. Where do design decisions come from?
-
-Find the project's design source-of-truth in this order:
-1. `.dw/rules/<frontend-module>.md` design system section.
-2. `DESIGN.md`, `BRAND.md`, `STYLE_GUIDE.md` at project root.
-3. Design token config — Tailwind theme, CSS variables in `theme.css`/`globals.css`, MUI/Chakra theme.
-4. Component library config — `components.json` for shadcn, theme exports.
-5. Storybook stories (implicit canonical components).
-
-**Stop at the first match** in this list — that source is the authority; defer to it and do not override it with a lower rung or a training-data default. If a needed token is missing (e.g., a danger-secondary color), propose adding it to the authority FIRST, not inline.
-
-If **none exists**: read `references/curated-defaults.md` and pick one of the 10 neutral palettes + one of the 10 font pairings shipped there. Mark the choice in the techspec/PR description: "Design source: no project authority found; using curated default `<name>`; recommend establishing `DESIGN.md`."
-
-**Anti-patterns at this question:**
-- Inventing color hex values inline (`bg-[#FF6B35]`).
-- "I'll use Tailwind defaults" — that's training-data defaults, not project authority.
-- Copying values from "a site I like" without understanding what it solved.
-
-### 2. What does this surface help the user do?
-
-Write one sentence: **"This surface helps the user `<verb-phrase>` so that `<outcome>`."**
-
-Good examples:
-- "...helps the user filter overdue invoices so they can chase late payers in under 30 seconds."
-- "...helps the on-call engineer diagnose which deploy caused the spike so they can roll back without paging the team."
-- "...helps the manager approve or reject expense reports without leaving Slack."
-
-Bad examples:
-- "This surface displays invoice data." (no user, no outcome)
-- "Settings page for managing the account." (vague, no specificity)
-- "Dashboard." (one word)
-
-If you can't write the sentence, the requirements are unclear. Stop and clarify before proceeding.
-
-### 3. What states does the surface have?
-
-Enumerate all states before designing the happy path. Minimum nine, plus domain-specific ones — see `references/state-matrix.md`:
-
-`default`, `hover`, `active`, `focus-visible`, `disabled`, `loading`, `empty`, `error`, `success` plus any domain states (read/unread, online/offline, stale/fresh, pending/approved/rejected, draft/saved/dirty, partial/complete, etc.).
-
-Missing a state at design time = production bug later. The "we'll add empty state later" trap is real.
-
-### 4. Who uses this surface, where, and in what mood?
-
-One sentence: **"`<Who>` uses this on `<where>` in `<what light>` while `<what mood>`."**
-
-Good examples:
-- "An on-call engineer uses this on a dark-room laptop at 3am while troubleshooting a fire."
-- "A field nurse uses this on a phone in bright outdoor light while juggling clipboards."
-- "A receptionist uses this on a 24″ monitor at a busy front desk while talking to a visitor."
-
-Decisions cascade from the answer:
-- 3am dark room → dark mode, high contrast, no flashing animations.
-- Bright outdoor → minimum 7:1 contrast, larger touch targets, no thin fonts.
-- Busy front desk → glanceable info, no nested menus, large numbers.
-
-Without this sentence, defaults take over: light mode, default contrasts, animations, regular touch targets. Production users hate it; you can't articulate why.
+For the four grounding questions, read `references/the-four-grounding-questions-detail.md`. Load only when this part of the task applies.
 
 ## Required reading by context
 
 | Doing what | Read |
 |------------|------|
+| Planning/auditing frontend data flow, dependencies or quality tooling | `references/frontend-engineering.md` (may be read directly without visual grounding for nonvisual work) |
 | Any UI work (the full version of the grounding) | `references/hard-gate.md` |
 | Reviewing or proposing a design | `references/visual-slop.md` (14 patterns + specific anti-default values) |
 | Designing state coverage | `references/state-matrix.md` |

package/scaffold/skills/dw-ui-discipline/references/frontend-engineering.md

@@ -0,0 +1,46 @@
+# Frontend engineering controls
+
+Read when planning frontend architecture, auditing a frontend module, or reviewing changes to its data flow, dependencies or quality tooling. A visual/copy-only edit needs only the relevant UI checks. This reference can be used directly without running visual grounding for an API client or CI configuration change.
+
+## Discover before changing
+
+Inspect the target workspace's scripts, lockfile, framework, compiler, API source, lint configuration, entry points and CI. Reuse working controls. Record observed configuration separately from proposed policy; an absent tool is not a failed check. Installation of dev-workflow does not authorize replacing consumer tooling.
+
+For a project audit, use the installed `frontend-quality-template.md` in `.dw/templates/` to document the baseline in the module's existing rules file. For a feature, include only affected decisions in its TechSpec. Read those decisions during implementation and review. A request to analyze produces findings and proposals; an authorized implementation may add compatible scripts/configuration and validate them.
+
+When using this skill standalone without the scaffold template, record the same compact control fields from the adoption section below in the project's existing document; no template installation is required.
+
+## Contract and type boundaries
+
+- Identify the authoritative API schema and its owner/revision before introducing response fields. If generation is used, record the generator version, command and output paths. Review contract changes, regenerate reproducibly and inspect drift; correct the source or generator rather than editing generated output.
+- When there is no maintained schema, derive a narrow boundary from verified backend code or documented responses and test it; label unresolved assumptions. Do not invent an OpenAPI specification from frontend guesses.
+- Runtime data still needs validation at relevant trust boundaries. Generating a validator is insufficient unless the actual response path calls it and handles failure. [Hey API's Zod integration](https://heyapi.dev/docs/openapi/typescript/plugins/zod) is one option when compatible with the existing client.
+- For TypeScript, inspect effective inherited configuration. Consider [`strict`](https://www.typescriptlang.org/tsconfig/strict.html), [`noUncheckedIndexedAccess`](https://www.typescriptlang.org/tsconfig/noUncheckedIndexedAccess.html) and [`exactOptionalPropertyTypes`](https://www.typescriptlang.org/tsconfig/exactOptionalPropertyTypes.html). Migrate by package or a coherent project boundary; passing filenames to a compiler invocation must not accidentally bypass project settings. Do not hide migration errors behind casts, `any` or non-null assertions.
+
+## Architecture and lint feedback
+
+Derive allowed imports from the project's architecture, including framework-specific server/client boundaries. Reuse an existing graph checker; [eslint-plugin-boundaries](https://github.com/javierbrea/eslint-plugin-boundaries) is an option for JS/TS. Verify aliases, workspace packages, type imports and legitimate framework entry points. A rejected dependency should identify its source, forbidden destination and the intended placement. Do not impose a universal folder layout.
+
+Choose lint rules against concrete failure modes and the installed runner: missing assertion awaits, accidentally focused tests, unsafe type escapes and inaccessible JSX. For React state changes, check whether an Effect actually synchronizes an external system; derived values and event responses often belong in rendering or handlers. Preserve legitimate synchronization. See [React's Effect guidance](https://react.dev/learn/you-might-not-need-an-effect).
+
+For a recurring repository-specific defect, prefer an existing rule. A custom detector needs a documented failure mode, an actionable diagnostic and valid/invalid fixtures. Exercise aliases, exclusions and unsupported syntax; an unresolved import is an analysis limitation, not proof of safety. Use an AST or the framework's parser when syntax matters. [ESLint's RuleTester workflow](https://eslint.org/docs/latest/extend/custom-rule-tutorial) supports rule validation. Avoid adding a regex-based import graph when the existing tool already models it.
+
+## Code that should disappear
+
+Evaluate dead-code findings against runtime reachability and public exports before deletion. Configure framework/plugin entry points, generated sources and workspace aliases. Tests alone can keep otherwise unused production code appearing live: [Knip production mode](https://knip.dev/features/production-mode) provides a separate view of shipped code and does not replace its normal analysis. Validate a newly configured detector with an intentionally unused fixture and a legitimately reachable fixture in an isolated workspace.
+
+Use textual duplication reports such as [jscpd](https://github.com/kucherenko/jscpd) as candidates for inspection. Apply different policies to repeated markup/fixtures and business calculations. Search for semantic duplicates too. Consolidate only when copies represent the same rule and should evolve together; a shared abstraction must preserve callers' behavior. Record exclusions with a reason and review trigger, instead of growing blanket ignores to make a report green.
+
+## Tests and adoption
+
+When critical logic changes or existing tests appear weak, use the testing skill's `references/mutation-testing.md` if available. Mutation testing complements contract and user-flow tests; neither coverage nor a diagnostic score establishes acceptance.
+
+For each adopted control record: risk, configuration, exact workspace command, scope, baseline, enforcement status, evidence and owner/review trigger. Use `required`, `advisory`, `deferred` or `not_applicable`; record actual execution separately (`passed`, `failed`, `not_run`). Start noisy new controls as advisory, triage findings, then promote demonstrated checks. Existing required gates remain required. Typechecking, builds and dependency graphs often need the whole affected project even when lint or mutation analysis can target a diff.
+
+Local hooks may shorten feedback, but CI must execute required checks independently of editor or agent hooks. Keep failures identifiable; verify that deployment depends on successful required jobs and that repository rules actually require the intended status checks. Do not claim a workflow file alone establishes branch protection. Advisory mutation runs may publish findings without a score threshold; report execution failures explicitly. Never hide a required check behind `continue-on-error`, an empty selection or a silently skipped job.
+
+Record command, inputs, environment and analysis scope through `dw-verify` when available. Treat new ignores, disabled rules, changed generation/configuration and lost CI coverage as reviewable changes. Delivery still requires checking product behavior, architecture and accessibility; automated findings reduce review work without replacing that judgment.
+
+## Attribution
+
+Workflow adaptation prompted by Yuri Mikhin's [Evil Martians article](https://evilmartians.com/chronicles/ten-anti-ai-slop-moves-for-frontend-projects-going-faster-than-humans-can-review), September 1, 2026. Procedures are independently written for dev-workflow and supported by the primary documentation linked above (checked September 9, 2026). No article text, source code or third-party tool is bundled here.

package/scaffold/skills/dw-ui-discipline/references/the-four-grounding-questions-detail.md

@@ -0,0 +1,61 @@
+## The four grounding questions
+
+Answer all four before proposing colors, layouts, components, or any visual decision.
+
+### 1. Where do design decisions come from?
+
+Find the project's design source-of-truth in this order:
+1. `.dw/rules/<frontend-module>.md` design system section.
+2. `DESIGN.md`, `BRAND.md`, `STYLE_GUIDE.md` at project root.
+3. Design token config — Tailwind theme, CSS variables in `theme.css`/`globals.css`, MUI/Chakra theme.
+4. Component library config — `components.json` for shadcn, theme exports.
+5. Storybook stories (implicit canonical components).
+
+**Stop at the first match** in this list — that source is the authority; defer to it and do not override it with a lower rung or a training-data default. If a needed token is missing (e.g., a danger-secondary color), propose adding it to the authority FIRST, not inline.
+
+If **none exists**: read `curated-defaults.md` and pick one of the 10 neutral palettes + one of the 10 font pairings shipped there. Mark the choice in the techspec/PR description: "Design source: no project authority found; using curated default `<name>`; recommend establishing `DESIGN.md`."
+
+**Anti-patterns at this question:**
+- Inventing color hex values inline (`bg-[#FF6B35]`).
+- "I'll use Tailwind defaults" — that's training-data defaults, not project authority.
+- Copying values from "a site I like" without understanding what it solved.
+
+### 2. What does this surface help the user do?
+
+Write one sentence: **"This surface helps the user `<verb-phrase>` so that `<outcome>`."**
+
+Good examples:
+- "...helps the user filter overdue invoices so they can chase late payers in under 30 seconds."
+- "...helps the on-call engineer diagnose which deploy caused the spike so they can roll back without paging the team."
+- "...helps the manager approve or reject expense reports without leaving Slack."
+
+Bad examples:
+- "This surface displays invoice data." (no user, no outcome)
+- "Settings page for managing the account." (vague, no specificity)
+- "Dashboard." (one word)
+
+If you can't write the sentence, the requirements are unclear. Stop and clarify before proceeding.
+
+### 3. What states does the surface have?
+
+Enumerate all states before designing the happy path. Minimum nine, plus domain-specific ones — see `state-matrix.md`:
+
+`default`, `hover`, `active`, `focus-visible`, `disabled`, `loading`, `empty`, `error`, `success` plus any domain states (read/unread, online/offline, stale/fresh, pending/approved/rejected, draft/saved/dirty, partial/complete, etc.).
+
+Missing a state at design time = production bug later. The "we'll add empty state later" trap is real.
+
+### 4. Who uses this surface, where, and in what mood?
+
+One sentence: **"`<Who>` uses this on `<where>` in `<what light>` while `<what mood>`."**
+
+Good examples:
+- "An on-call engineer uses this on a dark-room laptop at 3am while troubleshooting a fire."
+- "A field nurse uses this on a phone in bright outdoor light while juggling clipboards."
+- "A receptionist uses this on a 24″ monitor at a busy front desk while talking to a visitor."
+
+Decisions cascade from the answer:
+- 3am dark room → dark mode, high contrast, no flashing animations.
+- Bright outdoor → minimum 7:1 contrast, larger touch targets, no thin fonts.
+- Busy front desk → glanceable info, no nested menus, large numbers.
+
+Without this sentence, defaults take over: light mode, default contrasts, animations, regular touch targets. Production users hate it; you can't articulate why.

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

@@ -1,173 +1,51 @@
 ---
 name: dw-verify
-description: Demands fresh verification evidence before any success claim or commit. No PASS report, no claim — no exceptions.
+description: Validate completion, commit or PR claims against acceptance criteria and applicable project checks, reusing evidence only while its inputs remain valid.
 allowed-tools:
-  - Bash
   - Read
+  - Bash
   - Grep
+  - Glob
 ---
 
-# dw-verify — Verification Before Completion
-
-## Overview
-
-Claiming work is complete without verification is dishonesty, not efficiency.
-
-**Core principle:** Evidence before claims, always.
-
-**Violating the letter of this rule is violating the spirit of this rule.**
-
-## The Iron Law
-
-```
-NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
-```
-
-If the verification command has not been run in the current message, the result cannot be claimed.
-
-## The Gate Function
-
-```
-BEFORE claiming any status or expressing satisfaction:
-
-1. IDENTIFY: What command proves this claim?
-2. RUN: Execute the FULL command (fresh, complete)
-3. READ: Full output, check exit code, count failures
-4. VERIFY: Does output confirm the claim?
-   - If NO: State actual status with evidence
-   - If YES: State claim WITH evidence
-5. ONLY THEN: Make the claim
-
-Skip any step = lying, not verifying
-```
-
-## Scope of Verification
-
-Match the verification scope to the claim scope.
-
-- **Narrow claim** (e.g., "this test passes"): run the specific test.
-- **Broad claim** (e.g., "task complete", "ready to commit"): run the full verification pipeline — formatting, linting, all tests, and build. If the project defines a single gate command (e.g., `npm test`, `make verify`, `pnpm check`), run that.
-
-A narrow verification does not support a broad claim. Running one test alone does not justify "task complete." The verification scope must be equal to or broader than the claim scope.
-
-**If in doubt, run the full pipeline.** Over-verification wastes minutes. Under-verification wastes hours.
-
-**Passing pipeline ≠ meeting requirements.** A green build proves the code compiles, lints, and passes existing tests. It does not prove the implementation matches the PRD. For "task complete" or "requirements met" claims, also verify deliverables against the task's acceptance criteria and the PRD — line by line, not by assumption.
-
-## Common Failures
-
-| Claim                 | Requires                         | Not Sufficient                  |
-| --------------------- | -------------------------------- | ------------------------------- |
-| Tests pass            | Test command output: 0 failures  | Previous run, "should pass"     |
-| Linter clean          | Linter output: 0 errors          | Partial check, extrapolation    |
-| Build succeeds        | Build command: exit 0            | Linter passing, logs look good  |
-| Bug fixed             | Test original symptom: passes    | Code changed, assumed fixed     |
-| Regression test works | Red-green cycle verified         | Test passes once                |
-| Task complete         | Acceptance criteria cross-check  | Tests passing                   |
-| Requirements met      | Line-by-line PRD checklist       | Tests passing                   |
-
-## Red Flags
-
-If you catch yourself using any of these, STOP and run verification:
-
-- "should", "probably", "seems to", "I'm confident"
-- Expressing satisfaction before verification
-- About to commit, push, or open a PR without verification
-- Trusting another agent's success report
-- Relying on partial verification
-- "Just this once"
-
-## Rationalization Prevention
-
-| Excuse                                  | Reality                |
-| --------------------------------------- | ---------------------- |
-| "Should work now"                       | Run the verification   |
-| "I'm confident"                         | Confidence ≠ evidence  |
-| "Just this once"                        | No exceptions          |
-| "Linter passed"                         | Linter ≠ compiler      |
-| "Agent said success"                    | Verify independently   |
-| "I'm tired"                             | Exhaustion ≠ excuse    |
-| "Partial check is enough"               | Partial proves nothing |
-| "Different words so rule doesn't apply" | Spirit over letter     |
-
-## When To Apply
-
-Apply this skill before:
-
-- any success or completion claim
-- any expression of satisfaction with the implementation state
-- any commit or PR creation
-- any handoff that implies correctness
-- moving to the next task based on completion
-
-## Pre-Commit and Pre-PR Gate
-
-Commits and PRs are permanent artifacts. They require the highest verification standard.
-
-**Before `git commit`:**
-1. Run the full verification pipeline. Not a subset. The full pipeline.
-2. Confirm zero errors, zero warnings, zero test failures in the output.
-3. Produce a Verification Report (template below) with verdict PASS.
-4. Only then run `git commit`.
+# Verification grounded in evidence
 
-**Before creating a PR:**
-1. All of the above, plus:
-2. Verify the diff matches the intended changes (`git diff` review).
-3. Confirm no unrelated files are staged.
+A claim must match observed evidence. Inspect output and acceptance criteria; do not infer success from code edits, confidence, a worker's self-score, or a green build alone.
 
-If the full pipeline has not passed in this session after the last code change, the commit or PR must not proceed.
+## Select checks
 
-## Verification Report Template
+Follow required project gates from applicable instructions, package scripts and CI. Use focused tests while implementing or correcting defects, then complete the project's required delivery checks. Run lint/build only when applicable or required; do not invent absent scripts or demand zero pre-existing warnings when the project does not.
 
-Verification is not complete until the agent **cites actual command output** in their response. "I ran it and it passed" is not evidence. If the verification output is not shown, the verification did not happen.
+For frontend changes, consult the module's documented quality baseline or TechSpec: distinguish required checks from advisory diagnostics and deferred proposals. Check generation drift, typechecking, architecture and test evidence where applicable. Tool presence, a high score or an empty analysis scope is not a passing result. A local hook does not prove CI enforcement or branch protection.
 
-Every verification must be reported using this structure. Do not deviate.
+For behavior changes, verify relevant acceptance criteria and meaningful failure cases. For a small prose/config edit, use an appropriate inspection or validator; lack of a test runner alone does not block that claim. Report limits honestly. New tests should detect a plausible defect, not mirror implementation or language behavior. Explicit TDD requests retain their red/green contract.
 
-```
-VERIFICATION REPORT
--------------------
-Claim: [What is being claimed — e.g., "tests pass", "build succeeds", "task complete"]
-Command: [Exact command run — e.g., `npm test`, `pnpm verify`]
-Executed: [Timestamp or "just now, after all changes"]
-Exit code: [0 or non-zero]
-Output summary: [Key lines from output — pass count, error count, build result]
-Warnings: [Any warnings, or "none"]
-Errors: [Any errors, or "none"]
-Verdict: PASS or FAIL
-```
+## Evidence validity
 
-If the verdict is FAIL, do not use completion language. State what failed and what remains.
+For every check record command, exit code, output/log path, time, revision and relevant diff/input fingerprint, environment fingerprint and scope covered. Include relevant untracked/generated files, dependencies/lockfiles, tool configuration, runtime and external fixtures. The fingerprint must represent actual inputs; a timestamp or HEAD alone is insufficient when the worktree is dirty.
 
-If the verdict is PASS, the claim may proceed — but only the specific claim supported by the evidence.
+Reuse a passing record when command, inputs, environment and claim scope remain equivalent and its output can be inspected. A new message, review stage or bookkeeping-only commit does not by itself invalidate checks. Unknown fingerprints/environment, changed inputs, new findings or broader claims require appropriate fresh checks. If uncertain which inputs matter, rerun the required check instead of inventing validity.
 
-## When Verification Fails
+The installed helper `.dw/scripts/lib/workflow-contract.mjs` exports `reusableEvidence(record, current)` for comparing known fingerprints and scopes; callers still gather the actual evidence. Store records in execution-state.json for planned tasks, or the existing verification/QA report for standalone work.
 
-Verification failure is information, not a dead end. Protocol:
+## Failures and delivery
 
-1. **Read the failure.** Identify the exact error. Quote the relevant output lines.
-2. **Diagnose the root cause.** Read the error. Trace it to the source. If multiple things failed, address them one at a time, starting with the first failure.
-3. **Fix the root cause.** Apply the minimal change that addresses the actual error. No workarounds, no suppressions, no skipped checks.
-4. **Re-verify from scratch.** Run the full verification command again. Do not assume the fix worked. Do not run only the previously-failing subset.
-5. **Report with evidence.** Use the Verification Report Template. If it passes, the claim may proceed. If it fails again, return to step 1.
+Read failures and diagnose production behavior before changing tests. Correct failures caused by the requested change; rerun affected checks, then any invalidated required delivery gates. Do not weaken assertions, hide blocking findings, or claim a skipped check passed. Unrelated failures are reported with attribution and handled under project policy.
 
-**Never:**
-- Claim partial success ("3 of 4 checks pass, close enough")
-- Skip re-verification after a fix
-- Blame the tooling without evidence of a false positive
-- Move on while verification is still failing
+Before commit/PR, inspect the scoped diff and acceptance criteria and confirm all applicable required checks have valid passing evidence. Reuse a verified worker/CI result under the same validity rules; independently inspect the delivery, not blindly trust a summary. Security and constitution gates remain in force. A passing pipeline does not itself authorize commit, merge or publication.
 
-## Project-Specific Verification Commands
+## Verification report
 
-Discover the project gate before claiming success. Prefer documented gates in `.dw/rules/`, then package scripts such as `verify`, `check`, `ci`, or `test`, then Makefile/just/pyproject equivalents. If no verification command exists, state that explicitly in the Verification Report and avoid completion language.
+Record a compact VERIFICATION REPORT with Claim, Command, Executed, Revision/inputs, Environment, Scope, Exit code, Output summary/log, Warnings, Errors and Verdict (`PASS`, `FAIL`, or `NOT_APPLICABLE`). Say which evidence was reused and why. The user-facing response may summarize these records with links; full logs need not be pasted into every message.
 
-Load `references/verification-discovery-and-attribution.md` for the discovery checklist and attribution notes, or `references/pre-check-and-status.md` for the cheap diff-hygiene grep and the compact polling status line.
+Read `references/verification-discovery-and-attribution.md` when project gate discovery or attribution is needed. Read `references/pre-check-and-status.md` only for diff-hygiene checks or polling format.
 
 ## Structured Return
 
-- **Status:** `PASS` fresh gates prove the claim, `FINDINGS` fail/incomplete, `BLOCKED` no valid gate, `NOT_APPLICABLE` no claim.
-- **Scope:** claim, files, gates, environment.
-- **Evidence:** commands, exit codes, output, timestamps.
-- **Artifacts:** report, logs, screenshots, CI link.
-- **Decisions:** selected gate and skipped-gate reason.
-- **Risks:** stale output, partial runs, unverified generated files.
-- **Next Step:** rerun, fix, add gate, or name blocker.
+- **Status:** `PASS` valid evidence supports the claim; `FINDINGS` failed/incomplete checks; `BLOCKED` a required check cannot run; `NOT_APPLICABLE` no verification claim.
+- **Scope:** claim, relevant files/inputs, checks and environment.
+- **Evidence:** commands, exit codes, inspectable logs, fingerprints and acceptance criteria.
+- **Artifacts:** verification report, task state, screenshots or CI link.
+- **Decisions:** selected checks, evidence reused and reasons for inapplicable checks.
+- **Risks:** unknown environment, stale inputs, missing checks or uncovered behavior.
+- **Next Step:** fix, required check, or validated handoff.

package/scaffold/skills/dw-verify/references/verification-discovery-and-attribution.md

@@ -7,7 +7,7 @@ dev-workflow does not hardcode a verification command. Discover it from the proj
 3. Check for `Makefile`/`make verify`, `pyproject.toml`/`just verify`, etc.
 4. If none is explicit, run the documented test + lint + build sequence.
 
-If no verification command exists for the project, state that explicitly in the Verification Report and avoid completion language.
+If no automated command applies, document the appropriate inspection and its limits. A missing required check blocks its claim; a prose-only task does not require an invented test runner.
 
 ## Integration With Other dev-workflow Commands
 
@@ -18,7 +18,7 @@ This skill is invoked transparently from:
 - `/dw-qa --fix` — before marking a bug as resolved in `QA/bugs.md`
 - `/dw-bugfix` — before claiming the bug is fixed (original symptom no longer reproduces)
 - `/dw-review --code-only` — before emitting an APPROVED verdict
-- `/dw-generate-pr` — blocks PR creation if the session has no passing VERIFICATION REPORT post-last-edit
+- `/dw-generate-pr` — requires valid passing evidence for the current inputs, environment and scope
 
 Callers should mention this skill in their "Skills Complementares" section so the user sees the dependency.
 

package/scaffold/skills/humanizer/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: humanizer
-version: 2.2.0
+metadata:
+  version: "2.2.0"
 description: Use when editing AI-generated text. Detects 24 'signs of AI writing' (em-dashes, rule-of-three, AI vocab, vague attributions). Triggers on docs, READMEs, blog posts, captions, marketing copy.
 allowed-tools:
   - Read