@eltonssouza/development-utility-kit 0.10.0

package/dashboard/public/content/docs/plugins.en.md

@@ -0,0 +1,289 @@
+# External plugins — credit, choice rationale, integration
+
+`development-utility-kit` is **not a closed framework**. It is a curated harness that stands on the shoulders of four external pieces of Claude Code community work: **grill-me**, **caveman**, **impeccable**, and **rtk**. Each one was chosen deliberately, each one solves a specific problem, and each one is integrated in a way that preserves the original author's intent while making it useful inside this opinionated pipeline.
+
+This page exists because users frequently ask:
+
+- *"Why this plugin and not another?"*
+- *"How does it work inside `duk`?"*
+- *"What if I disable it — what breaks?"*
+- *"Who do I credit?"*
+
+The answer to all four questions is documented here, plugin by plugin. For end-to-end usage in real workflows, see [skills-reference](skills-reference) and [pipeline](pipeline). For our own internal architecture choices, see [architecture-overview](architecture-overview) and the ADR vault under `docs/brain/decisions/`.
+
+---
+
+## Selection principles
+
+Before listing the plugins, the four criteria used when accepting an external piece into the harness — applied retroactively to all current plugins and prospectively to any future ones:
+
+1. **Solves a problem the harness alone cannot solve well.** No NIH ("not invented here") — if someone built a better mousetrap, we use it. But also no "shiny new tool just because" — every plugin must be load-bearing in at least one pipeline stage.
+2. **Author is reachable and license is permissive.** Open source under MIT / Apache 2 / similar. Author publishes on GitHub. We can fork if upstream stalls, and we attribute clearly.
+3. **Drop-in integration without forking the harness.** Either invoked via `npx <plugin>@<pinned-version>` (Impeccable) or wrapped in a thin adapter (RTK, in `dashboard/rtk.js`). Skills like `grill-me` and `caveman` are adapted **once** at adoption time and become first-class `.claude/skills/` of the harness.
+4. **Distinct from our internal layer.** A plugin never overlaps with an existing skill or agent's primary responsibility. If a community plugin starts duplicating an internal piece, the internal one is the source of truth and the plugin is deprecated from the harness (with a clear ADR).
+
+A plugin that no longer satisfies one of those criteria gets removed, regardless of how widely used it is. ADR-018 documents the precedent (npx-style distribution for `duk` itself was inspired by `impeccable` — a meta-precedent of accepting external inspiration into our own architecture).
+
+---
+
+## grill-me — relentless discovery interview
+
+**Original author:** [Matt Pocock](https://github.com/mattpocock) — [aihero.dev](https://www.aihero.dev/my-grill-me-skill-has-gone-viral)
+**Upstream repo:** [mattpocock/skills](https://github.com/mattpocock/skills)
+**License:** MIT (verify upstream before any redistribution)
+**Where it lives in the harness:** `.claude/skills/grill-me/SKILL.md` (adapted)
+**Pinned version:** internal — we vendored the skill's interview mechanic and adapted it; we do not auto-update from upstream
+**Related ADR:** ADR-011, ADR-013, ADR-017, ADR-019
+
+### What it does
+
+`grill-me` is a discovery interview skill: it interrogates the user one decision branch at a time, before any code is written and before any technical plan is committed. For each question, it pre-computes a recommended answer the user can simply confirm (`y/n` style), and when the answer can come from the code or git history, it reads instead of asking. The interview ends when there is enough certainty to write down requirements without guessing.
+
+Matt's original design surfaced hidden requirements that prompt-only conversations missed. We kept the mechanic exactly as he designed it.
+
+### Why we picked it
+
+Three pre-existing problems in our pipeline made grill-me an obvious fit:
+
+- **PRD authoring used to start from a single user paragraph.** Result: under-specified scope, edge cases discovered late, sprint rework. Grill-me forces the user to confront ambiguity *before* the PRD exists.
+- **Planning agents (`analyst`, `architect`) need a structured input.** Free-form prompts make them hallucinate constraints. Grill-me produces a structured `DISCOVERY_*.md` that `analyst` can consume deterministically.
+- **The interview pattern was already proven viral.** Reproducing it from scratch would have taken weeks, with no clear UX improvement.
+
+We did not modify the interview mechanic, the recommended-answer pattern, the rubber-duck framing, or the conversational tone. Those are Matt's design.
+
+### How it integrates
+
+The `grill-me → to-prd → to-issues → analyst → run-sprint` chain is our pipeline's discovery → delivery spine (ADR-008). Our adaptation:
+
+| What we kept from Matt | What we added on top |
+|---|---|
+| One decision branch per question | Persistence to `docs/discovery/DISCOVERY_<NAME>.md` (ADR-017) |
+| Recommended answers user just confirms | Hand-off contract: `analyst` reads the discovery file and converts to `PLAN_*.md` with goal-ready DoD (ADR-013) |
+| Reading code / git log when possible | Caller signal (`caller: sprint-runner\|autonomous\|grill-me`) so autonomous flows skip the human interview gate (ADR-013) |
+| Brutal directness on hidden assumptions | Hard gate: `analyst` refuses to produce a PLAN without a `DISCOVERY_*.md` on the human path |
+
+### How to use it correctly
+
+- **Trigger from chat**: say `"grill me"`, `"me entrevista sobre <topic>"`, `"stress-test o plano"`, or any variant in the description triggers. The skill will start asking.
+- **Trigger from pipeline**: skipped if you say `"quick-feature"` (small change), or if you are already inside `sprint-runner`. The discovery gate is for new features, not for line edits.
+- **Stop early if the answer is obvious**: grill-me will not insist on questions where the recommended answer is high-confidence. Just confirm and move on.
+- **End artifact**: a `docs/discovery/DISCOVERY_<NAME>.md` file. From there: `"to-prd"` to materialise the PRD, then `"to-issues"` to break into GitHub issues, then `"executa Sprint 1"` to start coding.
+
+### What breaks if you disable it
+
+- `analyst` refuses to produce a `PLAN_*.md` on the human path (it requires a `DISCOVERY_*.md` per ADR-013). Workaround: produce the discovery manually and place it in `docs/discovery/` with the expected format.
+- `to-prd` has nothing to read. Workaround: write the PRD yourself.
+- Small features are unaffected (`quick-feature` bypasses discovery by design).
+
+### Alternatives considered
+
+- **Just prompt engineering** — works for trivial features but does not surface decision branches the user did not think to mention.
+- **Free-form interview by `analyst`** — analyst is biased toward "let's write the plan now" and tends to skip exploration. Grill-me's role separation (one tool that *only* explores) is the design choice.
+- **External requirements management (Jira, Linear)** — orthogonal; we still use these for storing the output (`to-issues` creates the tickets).
+
+---
+
+## caveman — telegraphic style as default
+
+**Original author:** [Julius Brussee](https://github.com/JuliusBrussee)
+**Upstream repo:** [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman)
+**License:** MIT (verify upstream before any redistribution)
+**Where it lives in the harness:** `.claude/skills/caveman/SKILL.md` (adapted)
+**Pinned version:** internal — same as grill-me, vendored and adapted
+**Related ADR:** none directly; ADR-018 references the `npx skills add` pattern that inspired our installer
+
+### What it does
+
+`caveman` compresses Claude's output by removing articles, fillers, redundant connectors, and stylistic flourishes — without removing technical substance. The compression levels (LITE, FULL, ULTRA) give the user control over how aggressive the cut is:
+
+- **LITE** — light cut, preserves sentence structure. Good for prose documents (`.md`).
+- **FULL** — standard cut, removes most fillers. Good for chat answers.
+- **ULTRA** — aggressive cut, telegraphic. Good for code, files, terminal output.
+
+Julius's original published results: ~65–75% token savings in typical Claude Code usage with zero loss of technical correctness.
+
+### Why we picked it
+
+Three reasons converged:
+
+- **Cost.** Opus inference is expensive. A 65–75% reduction in output tokens compounds across every session, every PR review, every plan. Real money over a year.
+- **Signal-to-noise ratio.** Long replies bury the actual answer in fluff. Senior developers using Claude Code as a thought-partner want answers, not essays. Caveman enforces that culture.
+- **No information loss.** This is the key. We tested it on stack traces, ADRs, code diffs, security audits — caveman preserves every technical token (paths, exact commands, schema, error codes). It removes "essentially", "basically", "as we discussed earlier", "it is worth noting that", which carry zero information.
+
+### How it integrates
+
+Caveman is the **default style** in the harness (ULTRA for `.java`, `.ts`, `.py`, `.sh`, `.yml`, `.json`; FULL for `.md`, LITE for prose responses). It is `always_on: true` in our adaptation.
+
+| What we kept from Julius | What we added on top |
+|---|---|
+| LITE / FULL / ULTRA levels with the same compression rules | Default-on policy in `.claude/skills/caveman/SKILL.md` |
+| Auto-clarity carve-outs (when the answer is genuinely complex, caveman steps back) | Disable command `"stop caveman"` / `"normal mode"` for moments the user needs full prose |
+| Preservation of YAML frontmatter, symbol names, paths, exact commands | Plugin-level interaction with `code-reviewer` (review feedback uses FULL by default for legibility) |
+
+### How to use it correctly
+
+- **Already on, by default.** You will see it in every reply. Nothing to enable.
+- **Switch level inline**: `"caveman lite"`, `"caveman full"`, `"caveman ultra"`.
+- **Disable for a single reply**: `"stop caveman"` or `"back to normal"`. The next prompt re-enables it.
+- **Never disable system-wide.** The default is the policy; disabling produces verbose output that costs more and conveys less. If you find caveman truncating something important, it is a bug in the compression — open an issue, do not just disable it.
+
+### What breaks if you disable it
+
+- Token cost rises 3–4× on typical tasks. Real number, measured on Java/Angular sessions.
+- Replies become harder to scan in the chat UI.
+- No functional regression — purely a cost/UX hit.
+
+### Alternatives considered
+
+- **Just asking for "concise" mode in the prompt** — works for one turn, decays over multi-turn conversations. Caveman is a skill, not a hint.
+- **Post-processing replies with a regex** — does not understand context (truncates valid technical content). Caveman is LLM-aware compression.
+- **No compression** — cost compounds. Not viable for production-grade harness use.
+
+---
+
+## impeccable — design refinement gate
+
+**Original author:** [Paul Bakaus](https://github.com/pbakaus)
+**Upstream repo:** [pbakaus/impeccable](https://github.com/pbakaus/impeccable)
+**License:** MIT (verify upstream before any redistribution)
+**Where it lives in the harness:** invoked at runtime via `npx impeccable@2.1.9` from `scripts/impeccable-gate.mjs` — **NOT vendored**
+**Pinned version:** `impeccable@2.1.9` (bump explicit only, via ADR — see `update-template/SKILL.md` §"Impeccable version pin")
+**Related ADR:** ADR-010 (Impeccable design gate), ADR-018 (npx distribution pattern)
+
+### What it does
+
+`impeccable` audits frontend code for visual design anti-patterns: inconsistent spacing, missing focus states, color contrast issues, missing aria-labels, unprincipled font scale jumps, etc. It runs in three modes:
+
+- **polish** — generate refactor suggestions inline
+- **harden** — make a passing build stricter (turn warnings into errors)
+- **audit** — full report, blocking findings flagged by severity
+
+We use **audit** in the senior+ gate (ADR-010) at WARN level first, BLOCK level once the catalog is clean. The gate runs only on changed files via `--changed-only`.
+
+### Why we picked it
+
+- **Filling a gap not covered by our existing gate.** Coverage, mutation, ESLint, Lighthouse, Playwright — all good, none catches "the button looks wrong but the test still passes". Impeccable does.
+- **Author's npx distribution pattern was elegant.** `npx skills add pbakaus/impeccable` directly inspired our own `npx @eltonssouza/development-utility-kit install` installer (ADR-018). When you copy someone else's architecture decision, you also credit them.
+- **Visual quality is a moving target.** The catalog of anti-patterns evolves. Impeccable is maintained by an active author; we get catalog updates for free by bumping the pin.
+
+### How it integrates
+
+| Layer | Integration point |
+|---|---|
+| Senior+ gate | `gate-keeper` agent runs `node scripts/impeccable-gate.mjs src --mode=warn` (or `--mode=block` once the catalog is clean) |
+| Frontend developer guidance | `.claude/agents/frontend-developer.md` instructs to use `/impeccable polish\|harden\|audit` inline before passing to `gate-keeper` |
+| Update policy | `.claude/skills/update-template/SKILL.md` §"Impeccable version pin" — bump explicit, via ADR; never silently |
+| Designer override | Decisions on visual identity still go to `ux-designer` and `product-owner`. Impeccable does not override design intent; it audits whether the intent is implemented consistently. |
+
+### How to use it correctly
+
+- **As a developer**: `/impeccable polish` inline while building a component; iterate suggestions.
+- **As a reviewer**: `/impeccable audit` before opening a PR; PR description references the report.
+- **In CI**: `gate-keeper` runs `--mode=warn` today; once frontend-developer adopts the catalog, switches to `--mode=block` via ADR-035 (pending).
+- **As a designer**: do **not** treat impeccable findings as design decisions. Decisions on visual identity are in design system docs, owned by `ux-designer` / `product-owner`. Impeccable enforces consistency, not creativity.
+
+### What breaks if you disable it
+
+- Visual regressions slip past the senior+ gate. Other quality gates (a11y, Lighthouse) catch *some* of them but not all.
+- `frontend-developer` loses an in-loop tool for self-correction.
+- The senior+ gate stays green more easily — which is a regression, not a win.
+
+### Alternatives considered
+
+- **ESLint plugins for accessibility / style** — catch a subset (a11y mostly). We still use them. Impeccable layers on top.
+- **Storybook + visual regression (Chromatic, Percy)** — orthogonal; great for catching diffs but not for *naming* the anti-pattern. Impeccable explains why; visual regression only shows what changed.
+- **Designers manually reviewing every PR** — does not scale; introduces a human gate where mechanical was possible (per ADR-034: mechanical → CLI).
+
+---
+
+## rtk — Rust Token Killer (CLI proxy)
+
+**Original author:** [rtk-ai](https://github.com/rtk-ai) team
+**Upstream repo:** [rtk-ai/rtk](https://github.com/rtk-ai/rtk)
+**License:** verify upstream before any redistribution
+**Where it lives in the harness:** invoked via `rtk` binary (must be on PATH); wrapper in `dashboard/rtk.js`; consumed by `duk dashboard`
+**Pinned version:** none — uses whatever `rtk` the user has installed; `rtk gain --format json` is the only call we make
+**Related ADR:** ADR-014 (Vanilla JS + Chart.js dashboard); the RTK widget itself was added later, no dedicated ADR
+
+### What it does
+
+RTK is a CLI proxy for LLM calls. It sits between Claude Code (or any LLM client) and the Anthropic API, cutting redundant tokens via local deduplication and other techniques. Operationally: you install `rtk`, you point your client at the proxy, and you get 60–90% savings on dev operations.
+
+It is independent of `caveman` (which compresses Claude's output before display). RTK compresses tokens at the API boundary. Both can run simultaneously and stack.
+
+### Why we picked it
+
+- **Dev-operation cost is a real budget line.** Caveman cuts output tokens; RTK cuts input tokens and redundant calls. Together they make Claude-Code-driven development financially sustainable at team scale.
+- **Already proven in the Claude Code community.** We did not build a wrapper; we built a *widget* that surfaces RTK's own metrics in the local dashboard, so the team sees the savings in real time.
+- **Zero coupling.** If RTK is not on PATH, the dashboard widget just shows `null` and life goes on. No hard dependency.
+
+### How it integrates
+
+| Layer | Integration point |
+|---|---|
+| CLI bootstrap | `bin/cli.js` runs `rtk gain` before booting the dashboard server; output prints once in the terminal as a status banner |
+| Dashboard widget | `dashboard/public/index.html` has an RTK card; `/api/rtk` endpoint calls `rtk.js` which spawns `rtk gain --format json` |
+| Daily metric | Same endpoint returns `getRtkDaily()` for the time-series chart |
+
+Safety design (`dashboard/rtk.js`):
+
+- 5-second hard timeout — if `rtk` hangs, the widget shows null instead of locking the dashboard.
+- Spawn with `stdio: 'ignore'` for stderr — RTK's status messages don't pollute the dashboard logs.
+- If `rtk` is not installed or fails, the endpoint returns `null`; the UI gracefully degrades to "no data".
+
+### How to use it correctly
+
+- **Install rtk separately** following the upstream README. We do not bundle it.
+- **Configure rtk-ai once per machine** (typically a token + endpoint config). After that, `rtk gain` works system-wide.
+- **Look at the dashboard widget** to see daily savings. The number is *yours*, not the harness's — RTK measures actual usage on your machine.
+- **Do not try to disable rtk from inside the harness.** It is an optional dependency by design — if you do not want it, do not install it; the widget will not appear and nothing else breaks.
+
+### What breaks if you disable it
+
+- The RTK widget on `duk dashboard` shows no data (just the chart container with empty state).
+- `bin/cli.js` line 600 prints "Note: rtk not found or returned no output — skipping gain report." in the terminal once at startup. Harmless.
+- No functional regression to any pipeline stage. Pure observability feature.
+
+### Alternatives considered
+
+- **Helicone, Langfuse, OpenLLMetry** — full observability platforms. Heavier (require a backend), give you more (request-level tracing). We chose RTK because the harness's value proposition is local + zero-config — RTK respects that, the others do not.
+- **Anthropic's own usage reports** — only shows total spend, not redundancy savings. Different question.
+- **No widget at all** — the team would not know the savings exist. Visibility drives adoption of the cost-cutting practices.
+
+---
+
+## Roadmap — future plugins
+
+Plugins we are watching but have not adopted yet. Each entry includes the criterion blocking adoption (per §"Selection principles") so the decision is auditable.
+
+| Plugin | What it does | Blocking criterion |
+|---|---|---|
+| **anthropic-claude-skills** (multiple authors) | Catalog of community skills | Need a curation step — adopting wholesale dilutes the harness's design; cherry-pick after evaluating each against ADR-025 |
+| **claude-flow** (rUv-FANN) | Multi-agent swarm orchestration | Overlaps with `project-manager` orchestrate mode (ADR-033); revisit if our orchestrate hits a hard cap |
+| **awesome-claude-code skills** | Various productivity skills | Per-skill evaluation needed; no blanket integration policy |
+
+If you have a plugin candidate, the path is: open an issue on the harness repo, document which problem it solves that the harness currently solves badly or not at all, and which criterion of §"Selection principles" it satisfies. The `tech-lead` agent (Opus) makes the final call, recorded as an ADR.
+
+---
+
+## Credits and attribution
+
+`development-utility-kit` is a meta-skill harness — it ships its own skills and agents but stands on the four plugins above. The integration is ours; the credit is theirs.
+
+If you build on top of this harness:
+
+- **Star the upstream repos**: [grill-me](https://github.com/mattpocock/skills) · [caveman](https://github.com/JuliusBrussee/caveman) · [impeccable](https://github.com/pbakaus/impeccable) · [rtk](https://github.com/rtk-ai/rtk)
+- **Cite the original authors** in any redistribution or derived work.
+- **Open issues upstream** when you find bugs in the plugins' core behavior — not on our repo. We only own the integration shim.
+
+Any mistake in the way we describe or integrate these plugins' work is ours, not theirs.
+
+---
+
+## See also
+
+- [skills-reference](skills-reference) — how `grill-me` and `caveman` behave as harness skills (operational details)
+- [pipeline](pipeline) — where `grill-me` and impeccable plug into the discovery → delivery flow
+- [quality-gate](quality-gate) — where impeccable runs in the senior+ gate
+- [architecture-overview](architecture-overview) — the 3-layer model that hosts these plugins
+- ADR-010 (impeccable gate), ADR-011 (grill-me as opt-in), ADR-014 (dashboard), ADR-018 (npx distribution pattern), ADR-034 (mechanical → CLI principle)

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