/nw-quality-framework

name: nw-quality-framework
description: Quality gates - 11 commit readiness gates, build/test protocol, validation checkpoints, and quality metrics
user-invocable: false
disable-model-invocation: true

Quality Framework

Commit Readiness Gates (11)

All pass before committing:

1. Active acceptance test passes (not skipped, not ignored) 2. All unit tests pass 3. All integration tests pass 4. All other enabled tests pass 5. Code formatting validation passes 6. Static analysis passes 7. Build validation passes (all projects) 8. No test skips in execution (ignores OK during progressive implementation) 9. Test count within behavior budget 10. No mocks inside hexagon 11. Business language in tests verified

Note: Reviewer approval (formerly Gate 12) and Testing Theater detection (formerly Gate 13) enforced at deliver-level Phase 4 (Adversarial Review via /nw-review), not per step.

Quality Gates by Category

• **Architecture**: all layers touched | integration points validated | stack proven E2E | pipeline functional
• **Implementation**: real functionality (not placeholders) | automated pipeline | happy path coverage | production patterns
• **Business Value**: meaningful user value | testable AC | measurable success metrics
• **Real Data**: golden masters present | edge cases tested | no silent errors | API assumptions documented
• **Test Integrity**: every test falsifiable | behavioral assertions only | no circular verification | no mock-dominated tests | no assertion-free tests | no fixture theater (see below)

Testing Theater Pattern 8: Fixture Theater

**Definition**: Acceptance tests pass because test fixtures create the expected end-state directly, rather than exercising production code through the driving port. Tests verify the correct outcome from the WRONG source.

**Detection**: After GREEN phase, run `git diff --name-only`. If `files_to_modify` from the roadmap step have NO changes but tests flipped from RED to GREEN, this is Fixture Theater. The test fixtures are implementing the feature, not production code.

**Litmus test**: Delete the new production code (or revert production files to pre-GREEN state). If tests still pass, it's Fixture Theater.

**Prevention**: 1. Post-GREEN wiring check: every file in `files_to_modify` MUST appear in `git diff` 2. Acceptance test Given steps set up PRECONDITIONS, never the expected end-state 3. If `git diff --stat` shows only test files changed after GREEN, BLOCK the COMMIT

Extension Justification (Mandate against Parallel Implementations)

**Provenance**: 2026-05-02, RCA `docs/analysis/rca-systematic-duplication-despite-design.md`. Outcomes-registry catches duplicate *outcomes* (same input/output contract). It does NOT catch the failure mode where a NEW outcome is genuinely different but should have *extended* an existing component instead of being shipped as a parallel implementation in a new file.

This rule is **language-agnostic**: it applies to any source file regardless of host language. Examples in this section use multiple languages to underscore that.

**Rule**: before creating a NEW source file under a path that already contains ≥1 file in the same role/layer, the crafter MUST emit an Extension Justification block. The block has exactly four lines:

WHY-NEW-FILE: <relative-path-of-new-file>
  CLOSEST-EXISTING: <relative-path-of-the-most-similar-existing-file>
  EXTENSION-COST: <one sentence on what extending CLOSEST-EXISTING would require>
  PARALLEL-RATIONALE: <one sentence on why a separate file is justified instead>

**Trigger**: applies when ANY of these are true for the proposed new file:

• The parent directory exists and has ≥1 sibling file in the same architectural role (e.g. new `domain/rules/e3b_cherry_pick.<ext>` when `e3_non_empty.<ext>` exists; or new `internal/handlers/login.go` when `signup.go` exists; or new `src/services/Email.cs` when `Sms.cs` exists)
• The new file's dependency surface (top imports / `use` / `require` / `using` / `include` / `import`) overlaps an existing sibling by ≥50%
• The new file's primary class/function naming follows a sibling pattern (`E3Rule` ↔ `E3bRule`, `LoginHandler` ↔ `SignupHandler`, `EmailService` ↔ `SmsService`, `PgRepository` ↔ `MysqlRepository`)

**Not triggered** when:

• Parent directory is empty (greenfield — no extension candidate exists)
• The new file is a language-mandated boilerplate marker with no behavior of its own — examples by language: Python `__init__.py` / `conftest.py`; Go `doc.go`; Rust `mod.rs`; TypeScript `index.ts` re-export shim; Ruby `version.rb`; Java/Kotlin empty `package-info.java`. The rule of thumb: if removing the file's *contents* (keeping the empty file) leaves the package importable, it is a marker — not a component.
• The new file is in a path explicitly listed in the DESIGN wave's component table with rationale already captured

**Enforcement**: the crafter's PREPARE phase MUST inventory existing files in `<target-path>/` before producing the first file-write. If the inventory is non-empty for a target path AND the new file is not a marker per the exclusion above, the Extension Justification block is mandatory before each new-file write. Reviewer agents flag missing blocks as a HIGH severity finding.

**Self-test for the rationale**: a valid PARALLEL-RATIONALE answers the question "what would break or what would become awkward if this lived inside CLOSEST-EXISTING?". Non-answers like "different concern", "cleaner separation", "single responsibility" are rejected — those are the phrases a parallel-creation bias produces without effort. Concrete answers cite at least one of: incompatible interface/signature, different lifecycle (init order, hot-reload, deployment unit), incompatible dependency set, divergent target/runtime (e.g. server-side vs client-side, native vs WASM), or DESIGN-table-recorded boundary that already adjudicated the split.

**Why this is a discipline rule, not a structural detector**: structural dete