@eltonssouza/development-utility-kit 1.0.0

package/dashboard/public/content/docs/quality-gate.en.md

@@ -0,0 +1,315 @@
+# Quality Gate Senior+
+
+The senior+ gate is **non-negotiable**. A task is only complete after `auto-test-guard` GREEN on **all** items. No exception. `tech-lead` blocks the merge if any item fails.
+
+This policy exists because the harness was built to deliver production code, not a fragile MVP. Coverage below threshold, high vulnerability, broken a11y, or poor Lighthouse score do not pass — regardless of deadline pressure. When the gate blocks, the correct path is to **fix the code**, not lower the threshold.
+
+## Full threshold table
+
+| Metric | Threshold | Tool |
+|---|---|---|
+| Backend coverage (lines) | >= **85%** | JaCoCo |
+| Backend coverage (branches) | >= **80%** | JaCoCo |
+| **Backend mutation score** | >= **70%** in `domain/` + `application/` | **PIT (Pitest)** |
+| Frontend coverage (statements) | >= **85%** | Jest --coverage |
+| Frontend coverage (branches) | >= **80%** | Jest --coverage |
+| SpotBugs | 0 CRITICAL, 0 HIGH | SpotBugs Maven plugin |
+| SonarLint/SonarQube (if configured) | 0 CRITICAL, 0 HIGH, 0 unreviewed hotspot | Sonar |
+| OWASP dependency-check | 0 CVE with CVSS >= 7.0 | OWASP DC plugin |
+| npm audit | 0 HIGH, 0 CRITICAL | `npm audit --audit-level=high` |
+| ESLint frontend | 0 errors, 0 warnings on new code | `eslint --max-warnings 0` |
+| Playwright E2E | 100% green, critical flows covered | Playwright |
+| Browser console in E2E | 0 errors | Chrome MCP |
+| **A11y violations (component)** | 0 `serious` / 0 `critical` | jest-axe |
+| **A11y violations (E2E)** | 0 `serious` / 0 `critical` | @axe-core/playwright |
+| **Performance score (Lighthouse)** | >= **0.80** (median of 3 runs) | @lhci/cli |
+| **LCP (Largest Contentful Paint)** | <= **2500ms** | @lhci/cli |
+| **CLS (Cumulative Layout Shift)** | <= **0.1** | @lhci/cli |
+| **TBT (Total Blocking Time)** | <= **300ms** | @lhci/cli |
+| **Testing pyramid ratio (E2E)** | <= **30%** of total (hard-fail above; ideal <= 15%) | `auto-test-guard` count |
+
+## How to run each validation
+
+The commands below are run automatically by `gate-keeper`; they are documented here so devs can reproduce locally before the gate.
+
+### Backend (Java + Spring Boot)
+
+```bash
+# Unit tests + JaCoCo coverage
+./mvnw test
+
+# Mutation testing (PIT) — enable pitest profile
+./mvnw verify -Ppitest
+
+# SpotBugs static analysis
+./mvnw spotbugs:check
+
+# OWASP dependency audit
+./mvnw dependency-check:check
+
+# Sonar (if configured)
+./mvnw verify sonar:sonar -Dsonar.host.url=<url>
+```
+
+### Frontend (Angular)
+
+```bash
+# Jest with coverage
+npm test -- --coverage
+
+# Dependency audit
+npm audit --audit-level=high
+
+# ESLint with no warnings
+npx eslint src --max-warnings 0
+
+# Playwright E2E
+npx playwright test
+
+# Lighthouse CI
+npx lhci autorun
+```
+
+### Test pyramid
+
+```bash
+# Count done by gate-keeper
+# total_e2e / (total_unit + total_integration + total_e2e) <= 0.30
+```
+
+## Minimal configuration
+
+Projects generated by the harness already come configured. For legacy projects adopted (`update-template`), check the following.
+
+### pom.xml — JaCoCo + PIT + SpotBugs + OWASP
+
+```xml
+<!-- JaCoCo -->
+<plugin>
+  <groupId>org.jacoco</groupId>
+  <artifactId>jacoco-maven-plugin</artifactId>
+  <executions>
+    <execution>
+      <goals><goal>prepare-agent</goal></goals>
+    </execution>
+    <execution>
+      <id>report</id>
+      <phase>verify</phase>
+      <goals><goal>report</goal></goals>
+    </execution>
+    <execution>
+      <id>jacoco-check</id>
+      <goals><goal>check</goal></goals>
+      <configuration>
+        <rules>
+          <rule>
+            <element>BUNDLE</element>
+            <limits>
+              <limit><counter>LINE</counter><value>COVEREDRATIO</value><minimum>0.85</minimum></limit>
+              <limit><counter>BRANCH</counter><value>COVEREDRATIO</value><minimum>0.80</minimum></limit>
+            </limits>
+          </rule>
+        </rules>
+      </configuration>
+    </execution>
+  </executions>
+</plugin>
+
+<!-- PIT (mutation testing) -->
+<profile>
+  <id>pitest</id>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.pitest</groupId>
+        <artifactId>pitest-maven</artifactId>
+        <configuration>
+          <targetClasses>
+            <param>com.company.project.domain.*</param>
+            <param>com.company.project.application.*</param>
+          </targetClasses>
+          <mutationThreshold>70</mutationThreshold>
+          <outputFormats><param>HTML</param><param>XML</param></outputFormats>
+        </configuration>
+        <executions>
+          <execution>
+            <goals><goal>mutationCoverage</goal></goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+</profile>
+
+<!-- SpotBugs -->
+<plugin>
+  <groupId>com.github.spotbugs</groupId>
+  <artifactId>spotbugs-maven-plugin</artifactId>
+  <configuration>
+    <effort>Max</effort>
+    <threshold>High</threshold>
+    <failOnError>true</failOnError>
+  </configuration>
+</plugin>
+
+<!-- OWASP dependency-check -->
+<plugin>
+  <groupId>org.owasp</groupId>
+  <artifactId>dependency-check-maven</artifactId>
+  <configuration>
+    <failBuildOnCVSS>7</failBuildOnCVSS>
+  </configuration>
+</plugin>
+```
+
+### Jest config (jest.config.ts)
+
+```typescript
+export default {
+  coverageThreshold: {
+    global: {
+      statements: 85,
+      branches: 80,
+      functions: 85,
+      lines: 85,
+    },
+  },
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.spec.ts',
+    '!src/main.ts',
+  ],
+};
+```
+
+### Playwright + axe-core (playwright.config.ts)
+
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  reporter: [['html'], ['list']],
+  use: {
+    baseURL: 'http://localhost:4200',
+    trace: 'on-first-retry',
+  },
+  projects: [
+    { name: 'chromium', use: { browserName: 'chromium' } },
+  ],
+});
+```
+
+### Lighthouse CI (lighthouserc.json)
+
+```json
+{
+  "ci": {
+    "collect": {
+      "url": ["http://localhost:4200"],
+      "numberOfRuns": 3
+    },
+    "assert": {
+      "assertions": {
+        "categories:performance": ["error", { "minScore": 0.80 }],
+        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
+        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
+        "total-blocking-time": ["error", { "maxNumericValue": 300 }]
+      }
+    }
+  }
+}
+```
+
+## Test pyramid
+
+The pyramid is a structural rule, not just a metric. Hard-fail if E2E exceeds 30% of total.
+
+```
+                  /\
+                 /  \
+                /E2E \   <= 30% of total (ideal <= 15%)
+               /------\
+              /        \
+             /Integration\  ~20-30%
+            /------------\
+           /              \
+          /     Unit       \  ~50-70%
+         /------------------\
+```
+
+Why this ratio?
+- **Unit**: fast, isolated, great coverage of domain rules.
+- **Integration**: validates boundaries (HTTP, DB, queue). Slower than unit, cheaper than E2E.
+- **E2E**: expensive, fragile, validates user flow end-to-end. Use sparingly.
+
+When E2E exceeds 30%, it usually means domain rules are being tested via UI clicks — anti-pattern. The fix is to move logic to a domain service and cover with unit tests.
+
+## Blocking flow
+
+```
+sprint-runner finishes task
+      │
+      ▼
+gate-keeper runs all checks
+      │
+      ├─ all GREEN ──────────────► code-reviewer ──► tech-lead ──► merge
+      │
+      └─ any failure ─────────────► block + return to responsible task
+                                                  │
+                                                  ▼
+                                       developer fixes
+                                                  │
+                                                  ▼
+                                       gate-keeper runs again
+```
+
+At the end of the PLAN, before the final merge, `prd-ready-check` re-runs the full gate + adds:
+- Zero `@Disabled` / `.skip()` in tests
+- Zero `// TODO` in production code
+- Zero hardcoded secrets (regex against common patterns + ggshield if available)
+- ADRs referenced by the PLAN have Status: Accepted
+
+## How to request an exception
+
+**You do not request one.** There is no exception to the senior+ gate.
+
+What exists is the path of **documented technical debt**:
+
+1. If a threshold genuinely cannot be reached this sprint (e.g. external legacy lib with no way to mock), `tech-lead` creates an entry in `docs/brain/tech-debt.md` with:
+   - Threshold that fell below
+   - Technical reason
+   - Recovery plan (sprint, owner)
+   - Risk explicitly accepted
+2. An ADR is created documenting the temporary exception.
+3. Even so, the gate **runs** — the exception shows in the report as "P0 deferred".
+
+Without an ADR + tech-debt entry, no exception. `gate-keeper` has no key to open the door.
+
+## ADR references
+
+- **ADR-007**: a11y + Lighthouse + test pyramid thresholds.
+- **ADR-008**: standard senior+ flow (V5.18.0+).
+
+Both live in the harness `docs/decisions/` and are copied to new projects via scaffold.
+
+## Standard senior+ flow
+
+Summary of what `gate-keeper` enforces, in order:
+
+1. `product-owner` decides requirements.
+2. `analyst` produces PLAN_*.md with goal-ready DoD.
+3. `architect` proposes ADR when there is a macro decision; `tech-lead` approves.
+4. `sprint-runner` executes Sprint N delegating to `backend-developer` + `frontend-developer` + `database-engineer` in parallel; `qa-engineer` writes tests.
+5. `gate-keeper` generates missing tests + runs the full senior+ gate (coverage, mutation, a11y, Lighthouse, pyramid).
+6. `code-reviewer` does initial review.
+7. `tech-lead` does final review → approves merge OR returns.
+
+**Human never interrupted** — except in the 4 PO cases or 3 TL cases (see [Autonomy matrix](autonomy-matrix)).
+
+## Cross-references
+
+- [Pipeline](pipeline) — where the gate runs in the end-to-end flow
+- [Agents reference](agents-reference) — role of `gate-keeper`, `qa-engineer`, `tech-lead`
+- [Stack rules](stack-rules) — test conventions per stack
+- [Architecture overview](architecture-overview) — macro model
+- [Autonomy matrix](autonomy-matrix) — authority of `gate-keeper` to block without human