@brunosps00/dev-workflow 0.10.0 → 0.13.0

package/scaffold/en/agent-instructions.md

@@ -0,0 +1,68 @@
+<!-- dev-workflow:start -->
+# dev-workflow — AI Agent Instructions
+
+This project uses [`@brunosps00/dev-workflow`](https://www.npmjs.com/package/@brunosps00/dev-workflow) (`dw-*` commands) for structured AI-driven development. The commands compose into a PRD → TechSpec → Tasks → Implement → Review → Commit → PR pipeline with hard gates for security, constitution compliance, and verification.
+
+**The whole point of this file:** when the user states an intent that matches the Trigger Map below, run the matching `dw-*` command **without asking permission first** — unless the change is genuinely trivial (see Escape Hatches).
+
+## Trigger Map
+
+| User intent (literal or paraphrased) | Auto-trigger |
+|--------------------------------------|--------------|
+| "Implement X" / "Build Y" / "Add feature Z" / "I need ..." / "Create ..." | `/dw-autopilot "X"` |
+| Pasted error / "X is broken" / "Bug in Y" / failing test screenshot | `/dw-bugfix "X"` |
+| "Run this task" (with task ID) | `/dw-run-task <ID>` |
+| "Run all pending tasks" / "Execute the plan" | `/dw-run-plan` |
+| "Review my PR" / "Check code quality" / "Is this ready to ship?" | `/dw-code-review` |
+| "Time to commit" / changes are validated and ready | `/dw-commit` |
+| "Open a PR" / "Ship this" | `/dw-generate-pr` |
+| "Write a PRD for X" / "Spec out Y" | `/dw-create-prd` |
+| "Design the architecture" / "Make the techspec" | `/dw-create-techspec` |
+| "Break this into tasks" | `/dw-create-tasks` |
+| "Where is X?" / "What uses Y?" / "How is Z structured?" | `/dw-intel "<question>"` |
+| "Audit our dependencies" / "Are we behind on packages?" | `/dw-deps-audit` |
+| "Scan for vulnerabilities" / "Security check" | `/dw-security-check` |
+| "QA this feature" / "Run the test plan" | `/dw-run-qa` |
+| "Fix the QA bugs" | `/dw-fix-qa` |
+
+**Priority:** when in doubt between two commands, `/dw-autopilot` is the safest default for any non-trivial feature request — it composes the rest.
+
+## Hard Gates (the commands enforce these — don't bypass)
+
+- **`.dw/constitution.md`**: principles with `severity: high` or `critical` block PRs / techspecs without an ADR justifying the deviation. Missing constitution? Commands auto-install defaults at `severity: info` (non-blocking) and continue — never blocks on absence.
+- **`.dw/spec/<prd>/tasks-validation.md`**: auto-generated at the end of `/dw-create-tasks`. Any FAIL dimension blocks user approval until resolved or explicitly overridden.
+- **Verification**: `/dw-generate-pr` requires a fresh `dw-verify` PASS (tests + lint + build) after the last edit.
+- **Security**: TS / Python / C# / Rust projects must pass `/dw-security-check` (Trivy + OWASP + lockfile audit) before the PR opens.
+
+## Escape Hatches — do NOT auto-trigger
+
+When any of these apply, answer directly and do **not** invoke a `dw-*` command:
+
+- One-line typo, rename, import sort, comment fix.
+- Pure exploration: "how does this work?", "show me X", "explain Y".
+- Aesthetic preference: "I prefer this style" — apply, don't run a pipeline.
+- User explicitly says "do this directly" / "skip autopilot" / "no need for a PRD" — honor it.
+- The conversation is already inside a `dw-*` flow (you're already executing tasks; don't start a new pipeline).
+
+## Workflow Reference
+
+```
+/dw-autopilot "wish"  ────►  Runs entire pipeline automatically
+                              (3 gates: PRD approval, Tasks approval, PR confirmation)
+
+  --- OR step-by-step ---
+
+/dw-brainstorm ─► /dw-create-prd ─► /dw-create-techspec ─► /dw-create-tasks
+                                                              │
+                                                              ▼
+/dw-commit + /dw-generate-pr ◄──── /dw-code-review ◄──── /dw-run-plan
+```
+
+Full command list and contextual help: `/dw-help`.
+
+## Editing this section
+
+This block lives between `<!-- dev-workflow:start -->` and `<!-- dev-workflow:end -->` markers. Anything you write **outside** these markers in `CLAUDE.md` / `AGENTS.md` is preserved on every `dev-workflow update`. Anything **inside** is refreshed from the package — your edits inside the block will be overwritten.
+
+To customize the trigger map permanently, copy the block content to outside the markers (or to a separate file like `.dw/agent-instructions-custom.md`) and edit there.
+<!-- dev-workflow:end -->

package/scaffold/en/commands/dw-analyze-project.md

@@ -705,6 +705,67 @@ packages/auth → packages/db
 6. {apps/web} — depends on ui, db, auth
 ```
 
+### Step 8: Constitution Generation (Optional but Recommended)
+
+After `.dw/rules/` is written, offer to generate `.dw/constitution.md` — the declarative principles the team wants enforced on PRDs, TechSpecs, and Code Reviews.
+
+**Difference from `.dw/rules/`:**
+- `.dw/rules/` is **analytical** — what the code IS (observed patterns, anti-patterns, conventions).
+- `.dw/constitution.md` is **declarative** — what the code SHOULD BE (rules the team commits to).
+
+**Behavior:**
+
+If `.dw/constitution.md` already exists, print "Constitution already present at `.dw/constitution.md` — skipping (edit it manually if you want to update)" and finish.
+
+Otherwise, present 3 options in the chat (use the user's preferred question UI when available; otherwise plain text):
+
+```
+A constitution would help PRDs/TechSpecs/PRs stay aligned with project standards.
+Three options:
+
+  A) Synthesize from observed patterns (recommended)
+     I read `.dw/rules/` and propose 5–8 principles grounded in real code,
+     each with `Why:` linked to evidence and `severity: info` (won't block).
+     You review and approve before anything is written.
+
+  B) Install defaults template
+     Copy `templates/constitution-template.md` to `.dw/constitution.md` with
+     5 canonical principles (Code Quality, Testing, UX, Performance, Security)
+     pre-filled at `severity: info`. You customize manually.
+
+  C) Skip
+     No constitution. Downstream commands will operate without the gate.
+     You can run this step again later by re-running `/dw-analyze-project`.
+```
+
+**Option A — Synthesize:**
+
+1. Read `.dw/rules/index.md` + each `.dw/rules/{module}.md`.
+2. Propose 5–8 principles. Each must:
+   - Have a unique `P-NNN` ID.
+   - Map to an observation in `.dw/rules/` (cite the rule file + section).
+   - Start at `severity: info` (never propose `high`/`critical` automatically — that's the team's call).
+   - Follow the format: `**P-NNN — <name>** (severity: info): <rule>. **Why:** <ground in evidence>. **Enforcement:** <how to check>.`
+3. **Show the proposed principles in the chat as a markdown list** (do not write the file yet). Include the evidence citation for each.
+4. Ask: "Edit any of these before I write the file? Reply with the IDs to drop/edit, or 'approve' to write as-is."
+5. After user approves (with edits applied), write to `.dw/constitution.md` using the same template structure as `templates/constitution-template.md`.
+6. Set frontmatter `mode: custom` and `last_updated: <today's ISO date>`.
+
+**Option B — Defaults:**
+
+1. Locate `templates/constitution-template.md` (project-local at `.dw/templates/constitution-template.md`, falling back to the bundled scaffold).
+2. Copy to `.dw/constitution.md` verbatim. Set frontmatter `mode: defaults`.
+3. Print: "Installed defaults constitution at `.dw/constitution.md`. All 10 principles start at `severity: info` — they report but don't block. Edit the file to customize, then promote severities to `high`/`critical` when you trust the project enforces them."
+
+**Option C — Skip:**
+
+1. Do nothing.
+2. Print: "Skipped. PRD/TechSpec/CodeReview will run without the constitution gate. Re-run `/dw-analyze-project` later if you want to enable it."
+
+**No matter which option:**
+- Never write `.dw/constitution.md` without explicit user approval (option A) or explicit choice (options B/C).
+- Constitution file is committed to the repository like any other project artifact — never gitignored.
+
 ## Quality Checklist
 
 Before declaring the analysis complete, verify:

package/scaffold/en/commands/dw-autopilot.md

@@ -141,7 +141,7 @@ Present to the user:
 ### Step 7: Design Contract (Conditional)
 
 Evaluate whether tasks involve frontend:
-- **YES** (run `/dw-redesign-ui`): if there are tasks with visual components AND the `ui-ux-pro-max` skill is available
+- **YES** (run `/dw-redesign-ui`): if there are tasks with visual components AND the `dw-ui-discipline` skill is available
   - Generate the design contract in `.dw/spec/prd-[name]/design-contract.md`
   - Present a summary of the design contract to the user (palette, typography, mobile/desktop layout) as a visual checkpoint before proceeding
 - **NO** (skip to step 8): purely backend/infra tasks

package/scaffold/en/commands/dw-brainstorm.md

@@ -41,7 +41,7 @@ digraph brainstorm_decision {
 When available in the project under `./.agents/skills/`, use these skills to enrich ideation:
 
 - `dw-council` (opt-in via `--council`): multi-advisor stress-test of the most promising options with mandatory steel-manning and concession tracking. **DO NOT invoke by default** — only when the flag is present or when consensus forms too quickly (false-consensus signal).
-- `ui-ux-pro-max`: use when brainstorming involves frontend, UI style direction, design system choices, or visual identity exploration
+- `dw-ui-discipline`: use when brainstorming involves frontend or UI direction — its hard-gate (scene sentence, surface job) is a generative forcing function during ideation, not just a review check
 - `vercel-react-best-practices`: use when brainstorming React/Next.js architecture or performance trade-offs
 - `security-review`: use when brainstorming touches auth, data handling, or security-sensitive features
 

package/scaffold/en/commands/dw-bugfix.md

@@ -18,7 +18,7 @@
     - `dw-debug-protocol`: **ALWAYS** — runs the bug through the six-step triage (Reproduce → Localize → Reduce → Fix Root Cause → Guard → Verify End-to-End). Stop-the-line discipline; root-cause over symptom; regression test committed in the same atomic commit. Non-reproducible bugs follow the instrument-first sub-protocol — no guess fixes without explicit acknowledgement.
     - `dw-verify`: **ALWAYS** — in Direct mode, invoked before committing the fix. The VERIFICATION REPORT must show the original bug symptom no longer reproduces (not just that tests pass).
     - `vercel-react-best-practices`: use when the bug affects React/Next.js and there is suspicion of render, hydration, fetching, waterfall, bundle, or re-render issues
-    - `webapp-testing`: use when the fix requires a reproducible E2E/retest flow in a web app
+    - `dw-testing-discipline`: use when the fix requires a reproducible E2E/retest flow in a web app — `references/playwright-recipes.md` for recipes, Iron Laws + 7 AI Gates for any test the fix adds, flaky-discipline if the bug surfaces intermittently.
     - `security-review`: use when the root cause touches auth, authorization, external input, upload, secrets, SQL, XSS, SSRF, or other sensitive surfaces
 
     ## Input Variables
@@ -159,7 +159,7 @@
     - Related error messages
     - Stack traces
     - Recently modified files
-    - If the bug is UI-related or depends on browser flow, supplement collection with `webapp-testing`
+    - If the bug is UI-related or depends on browser flow, supplement collection with `dw-testing-discipline` (playwright-recipes + three-workflow-patterns to pick the right verification mode)
 
     ### 3. Clarification Questions (MANDATORY - EXACTLY 3)
 
@@ -197,7 +197,7 @@
     - **Probable Cause**: Based on the evidence
     - **Affected Files**: List of files to modify
     - **Impact**: Other components that may be affected
-    - **Skills used**: explicitly record if the analysis used `vercel-react-best-practices`, `webapp-testing`, or `security-review`
+    - **Skills used**: explicitly record if the analysis used `vercel-react-best-practices`, `dw-testing-discipline`, or `security-review`
 
     ### 4.1 Scope Checkpoint (MANDATORY)
 

package/scaffold/en/commands/dw-code-review.md

@@ -166,6 +166,34 @@ For each impacted project, verify project-specific rules from `.dw/rules/`:
 - [ ] API calls use project fetch utilities
 - [ ] UI follows project design system
 
+### 4.1. Constitution Compliance (Required when `.dw/constitution.md` exists)
+
+<critical>**Auto-create if missing**: if `.dw/constitution.md` does NOT exist, copy `templates/constitution-template.md` (project-local `.dw/templates/constitution-template.md` first, falling back to bundled scaffold) verbatim with frontmatter `mode: defaults`. Print in chat: "Installed defaults constitution at `.dw/constitution.md` (all principles at `severity: info` — reported but not blocking this review). Continuing." Then proceed.</critical>
+
+For each principle in `.dw/constitution.md`, check the diff for violations:
+
+1. **Parse principles**: read each `**P-NNN — <name>** (severity: <S>)` entry; capture `P-NNN`, `severity`, and the `Enforcement` description.
+2. **Apply enforcement**: for each principle, run the enforcement check against the diff (grep, file inspection, or pattern match per the Enforcement line).
+3. **Classify violations**:
+   - Principle severity `info` → add row to "Issues Found" table with severity `low`. **Does not block** the verdict.
+   - Principle severity `high` → add row with severity `critical`. **Blocks** the verdict to `REJECTED` UNLESS an ADR in the same PRD's `adrs/` directory documents the deviation (look for `Deviates: P-NNN` in any ADR body).
+   - Principle severity `critical` → add row with severity `critical` AND require the ADR to have a non-empty `Approved by:` field. Missing field = still `REJECTED`.
+4. **No silent skips**: if the diff is too large to analyze every principle, report which were checked and which were skipped due to scope.
+
+**Output format in the report:**
+
+```markdown
+## Constitution Compliance
+
+| Principle | Severity | Status | Evidence | ADR escape |
+|-----------|----------|--------|----------|------------|
+| P-001 — No `any` casts | info | VIOLATED | src/foo.ts:42 | n/a |
+| P-009 — Server-side auth | high | VIOLATED | src/api/order.ts:18 missing auth middleware | none → BLOCKS |
+| P-010 — Secrets in repo | critical | PASS | — | — |
+```
+
+If any `high`/`critical` violation has no ADR escape: append to the verdict line "REJECTED — constitution violation(s) without ADR (see Constitution Compliance section)".
+
 ### 5. Code Quality Analysis (Required)
 
 | Aspect | Verification |

package/scaffold/en/commands/dw-create-prd.md

@@ -50,6 +50,22 @@
     - Use `.dw/rules/` as context, falling back to grep
     - Suggest running `/dw-map-codebase` for richer downstream context
 
+    ## Constitution Gate
+
+    <critical>BEFORE the clarification questions, check `.dw/constitution.md`:
+
+    **If MISSING**: copy `templates/constitution-template.md` (project-local at `.dw/templates/constitution-template.md`, falling back to bundled scaffold) verbatim to `.dw/constitution.md`. Set frontmatter `mode: defaults` and `last_updated` to today's ISO date. Print in chat:
+
+    > "I noticed `.dw/constitution.md` was missing. Installed defaults at `.dw/constitution.md` (10 canonical principles, all `severity: info` — they report but don't block). You can customize anytime — or re-run `/dw-analyze-project` for a tailored version. Continuing with PRD."
+
+    Then proceed normally, treating the new file as the constitution.
+
+    **If PRESENT**: read it before drafting requirements. Each FR in the PRD MUST include a "Constitution Alignment" line mapping to ≥1 relevant principle (`Respects: P-001, P-009`) OR explicitly declaring "no applicable principle" with a one-line reason. Missing alignment = the FR is incomplete.
+
+    **Severity rules** (applied by downstream commands, not enforced here):
+    - `severity: info` violations → reported, never block.
+    - `severity: high` / `critical` violations → block in `dw-create-techspec` and `dw-code-review` unless an ADR justifies the deviation.</critical>
+
     ## Multi-Project Features
 
     Many features may involve more than one project in the workspace (e.g., a feature may impact both frontend and backend, or multiple services).

package/scaffold/en/commands/dw-create-tasks.md

@@ -149,5 +149,47 @@
     3. Create PR when all tasks are completed
     ```
 
+    ## Final Consistency Check (Auto-invoked before user approval)
+
+    <critical>BEFORE presenting tasks to the user, run a 5-dimension consistency check. This is mandatory; do not skip even if you're confident the tasks are clean.</critical>
+
+    Run these 5 checks against the generated PRD + TechSpec + tasks set:
+
+    1. **FR coverage** — every numbered FR in the PRD maps to ≥1 task. Orphan FRs (PRD has it; no task covers it) are a FAIL.
+    2. **Task grounding** — every generated task body references ≥1 FR (`Covers: FR-N.M`). Tasks without FR reference signal scope creep.
+    3. **Test coverage** — every FR with user-facing behavior (UI, API endpoint, data mutation) has ≥1 task that adds a test (subtask containing "test", "spec", "e2e", or equivalent).
+    4. **Dependency graph** — task dependencies (X.0 → Y.0 declared as "Depends on") form a DAG. No cycles. Topological order valid.
+    5. **Constitution alignment** (only if `.dw/constitution.md` exists) — every task lists `Constitution: respects P-NNN, P-MMM` OR `Constitution: deviates P-NNN — ADR planned: <slug>` OR `Constitution: n/a — reason: <one-liner>`. Missing line = FAIL.
+
+    Write findings to `.dw/spec/prd-[feature-name]/tasks-validation.md` with this exact structure:
+
+    ```markdown
+    # Tasks Validation Report
+
+    Generated by /dw-create-tasks on YYYY-MM-DD.
+
+    | Dimension | Status | Findings |
+    |-----------|--------|----------|
+    | 1. FR coverage | PASS / FAIL | <orphan FR list or "all FRs covered"> |
+    | 2. Task grounding | PASS / FAIL | <ungrounded task list or "all tasks reference FRs"> |
+    | 3. Test coverage | PASS / FAIL | <FRs missing tests or "all user-facing FRs covered"> |
+    | 4. Dependency graph | PASS / FAIL | <cycles or "DAG valid"> |
+    | 5. Constitution alignment | PASS / FAIL / N/A | <unaligned tasks or "all aligned" or "no constitution"> |
+
+    ## Detailed Findings
+
+    <one section per FAILing dimension with concrete fixes; empty if all PASS>
+    ```
+
+    **Gate behavior:**
+
+    - **All 5 dimensions PASS (or N/A)** → present tasks to the user normally and ask for approval.
+    - **Any dimension FAIL** → STOP. Show the table in chat as markdown (do NOT bury it in the validation file; the user must see it before approving). Then ask the user:
+      - "(a) Want me to fix tasks automatically?" → regenerate the affected tasks, re-run the check.
+      - "(b) Will you edit tasks.md manually?" → wait for the user to signal completion, re-run the check.
+      - "(c) Override and proceed despite FAIL?" → require an explicit override message ("override: I accept the gap because <reason>"). Persist the override in `tasks-validation.md` so it's auditable.
+
+    The `tasks-validation.md` file is committed alongside `tasks.md`. Downstream commands (`/dw-run-plan`, `/dw-code-review`, `/dw-review-implementation`) may reference it.
+
     After completing the analysis and generating all necessary files, present the results to the user and wait for confirmation to proceed with implementation.
 </system_instructions>

package/scaffold/en/commands/dw-create-techspec.md

@@ -25,7 +25,7 @@
     - `dw-council` (opt-in via `--council`): multi-advisor debate on the primary architectural decision with steel-manning. **DO NOT invoke by default**.
     - `dw-source-grounding` (**ALWAYS**): every framework/library decision must follow Detect → Fetch → Implement → Cite. The techspec emits inline citations `[source: <url>, version: X.Y, retrieved: YYYY-MM-DD]` next to each architectural decision.
     - `vercel-react-best-practices`: use when defining frontend architecture for React/Next.js projects
-    - `ui-ux-pro-max`: use when defining design system decisions, color palettes, typography, and UI style for the TechSpec
+    - `dw-ui-discipline`: use when the TechSpec includes UI sections — enforces the 4-checkpoint hard-gate (brand authorities / surface job / state matrix / scene sentence), the 14 anti-slop patterns, and the WCAG 2.2 AA floor BEFORE design decisions land.
     - `security-review`: use when the feature touches auth, authorization, or sensitive data handling
 
     ## Codebase Intelligence
@@ -39,6 +39,23 @@
     - Use `.dw/rules/` as context, falling back to grep
     - Suggest running `/dw-map-codebase` to enrich downstream context
 
+    ## Constitution Gate
+
+    <critical>BEFORE drafting architectural decisions, check `.dw/constitution.md`:
+
+    **If MISSING**: copy `templates/constitution-template.md` (project-local at `.dw/templates/constitution-template.md`, falling back to bundled scaffold) verbatim to `.dw/constitution.md`. Set frontmatter `mode: defaults`. Print in chat: "Installed defaults constitution at `.dw/constitution.md` (severity: info — won't block this techspec). Continuing." Then proceed.
+
+    **If PRESENT**: read it. Every framework / library / architectural choice in the techspec MUST carry one of:
+    - `Respects: P-NNN` — the decision actively honors the named principle(s).
+    - `Deviates: P-NNN — justification: <ADR slug or one-line rationale>` — the decision intentionally departs from the principle.
+
+    **Severity-graded gate:**
+    - Deviation from a `severity: info` principle → record only, never blocks.
+    - Deviation from a `severity: high` principle without a linked ADR (`.dw/spec/<prd>/adrs/adr-NNN.md`) → BLOCK the techspec. Instruct the user to either revise the decision OR create an ADR via `/dw-adr` documenting the trade-off.
+    - Deviation from a `severity: critical` principle → BLOCK the techspec with the same ADR requirement, additionally requiring reviewer acknowledgment captured in the ADR's `Approved by` field.
+
+    No exceptions for `high`/`critical` without an ADR. If the user pushes back, point them to `/dw-adr` — that's the escape hatch by design.</critical>
+
     ## Multi-Project Decision Flowchart
 
     ```dot

package/scaffold/en/commands/dw-deps-audit.md

@@ -31,7 +31,7 @@ This command is **distinct** from `/dw-security-check`:
 | `security-review` (`references/supply-chain.md`) | **ALWAYS** when classifying findings — gives OWASP A06 (Vulnerable & Outdated Components) framing for the brainstorm trade-offs |
 | `dw-source-grounding` | **ALWAYS** in the brainstorm phase — each per-package update option (Conservative/Balanced/Bold) cites the official changelog/release notes for the target version: `[source: <url>, version: X.Y, retrieved: YYYY-MM-DD]`. Catches "agent recommends v5 because it sounds modern, but v5 dropped Node 18 support" errors. |
 | `dw-council` | Auto opt-in when ≥3 packages land in tier COMPROMISED — multi-advisor stress-test on remediation order and scope |
-| `webapp-testing` | Optional — when the project is frontend and the scoped test phase needs Playwright-aware test selection |
+| `dw-testing-discipline` | Optional — when the scoped test phase needs Playwright recipes for frontend projects. Iron Laws + anti-patterns apply to any test added during the audit. |
 
 ## Input Variables
 

package/scaffold/en/commands/dw-fix-qa.md

@@ -20,7 +20,7 @@ When available in the project under `./.agents/skills/`, use these skills as ope
 
 - `dw-debug-protocol`: **ALWAYS** — every bug-shaped finding (failing scenario, not missing feature) flows through the six-step triage. The retest evidence is the step-6 verification artifact; the regression test added in step 5 is what allows `Fixed` status to stick.
 - `dw-verify`: **ALWAYS** — invoked before marking any bug as `Fixed` or `Closed` in `QA/bugs.md`. Without a VERIFICATION REPORT PASS (test + lint + build) **and** retest evidence (screenshot in UI mode OR JSONL log line in API mode), status stays `Reopened` or `Under review`.
-- `webapp-testing`: (UI mode) support for structuring retests, captures, and scripts when complementary to Playwright MCP
+- `dw-testing-discipline`: (UI mode) consult `references/playwright-recipes.md` for retest structures, captures, scripts. Apply Iron Laws + flaky discipline when retesting bug fixes — quarantine and SLOs from the doctrine apply.
 - `vercel-react-best-practices`: (UI mode) use only if the fix affects React/Next.js frontend and there is risk of rendering, hydration, fetching, or performance regression
 - `api-testing-recipes`: **(API mode — ALWAYS)** source of the recipe used at QA time. Re-execute the original `.http`/pytest/supertest/etc. file for the bug's RF; append the retest result to a fresh JSONL log under `QA/logs/api/BUG-NN-retest.log`
 

package/scaffold/en/commands/dw-functional-doc.md

@@ -55,10 +55,10 @@ Works best with project analyzed by `/dw-analyze-project`
 
 When available in the project under `./.agents/skills/`, use these skills as operational support without replacing this command as source of truth:
 
-- `webapp-testing`: support for structuring E2E flows, local retests, and evidence collection
+- `dw-testing-discipline`: support for structuring E2E flows (`references/playwright-recipes.md`), evidence collection patterns, and applying Iron Laws + selector hierarchy to any test the doc references
 - `remotion-best-practices`: mandatory support when there is a final human video, captions, composition, transitions, FFmpeg, or Remotion
 - `humanizer`: mandatory support for reviewing and naturalizing all captions, `.srt` files, descriptive texts, and any human-facing writing before final delivery
-- `ui-ux-pro-max`: use when documenting visual patterns, design system choices, and UI style consistency across screens
+- `dw-ui-discipline`: use when documenting visual patterns — the state matrix and scene sentence become part of each screen's overview section
 
 ## Mandatory Browser Tools
 

package/scaffold/en/commands/dw-help.md

@@ -380,7 +380,7 @@ Commands work across multiple AI tools, all pointing to the same source `.dw/com
 - For comprehensive multi-source analysis, technology comparisons, state-of-the-art reviews, or any topic requiring cited evidence. Not for simple lookups or debugging.
 
 **Q: Does `/dw-redesign-ui` work with Angular?**
-- Yes. The command is framework-agnostic. For React it uses react-doctor and `vercel-react-best-practices`; for Angular it uses `ng lint` and Angular DevTools. Visual design (`ui-ux-pro-max`) works with any framework.
+- Yes. The command is framework-agnostic. For React it uses react-doctor and `vercel-react-best-practices`; for Angular it uses `ng lint` and Angular DevTools. UI discipline (`dw-ui-discipline`) works with any framework — enforces the hard-gate, anti-slop catalog, and WCAG floor regardless of stack.
 
 **Q: How do I get codebase intelligence and parallel execution?**
 - Both are native to dev-workflow. Run `/dw-map-codebase` to build the queryable index in `.dw/intel/`, then `/dw-intel "<question>"` to query it. For parallel execution, `/dw-run-plan` invokes the bundled phase-execution agents (executor + plan-checker) directly to dispatch tasks in waves with atomic commits per task. No external dependency needed.

package/scaffold/en/commands/dw-redesign-ui.md

@@ -40,9 +40,9 @@ digraph redesign_decision {
 
 When available in the project under `./.agents/skills/`, use these to guide the redesign:
 
-- `ui-ux-pro-max`: **REQUIRED** — use for all design decisions (color palette, typography, visual style, layout, WCAG accessibility)
+- `dw-ui-discipline`: **REQUIRED** — runs the 4-checkpoint hard-gate (brand authorities OR curated defaults; surface job sentence; complete state matrix; scene sentence) BEFORE any design proposal. The 14 anti-slop patterns are checked against each proposed direction. The WCAG 2.2 AA floor is non-negotiable at the validate step.
 - `vercel-react-best-practices`: use when the project is React/Next.js for performance and implementation patterns
-- `webapp-testing`: use to capture before/after screenshots and visual validation with Playwright
+- `dw-testing-discipline`: consult `references/playwright-recipes.md` for before/after screenshot capture and visual validation. Iron Laws + selector hierarchy apply to any tests generated alongside the redesign.
 - `security-review`: use if the redesign touches authentication flows or sensitive forms
 
 ## Analysis Tools
@@ -56,12 +56,12 @@ Use diagnostic tools based on the project's framework:
 ## Required Behavior
 
 1. Identify the target: page, component, or route to be redesigned.
-2. **AUDIT**: read the current implementation, identify the CSS stack (Tailwind, CSS Modules, styled-components, etc.), capture screenshot if `webapp-testing` is available, run react-doctor if React project.
+2. **AUDIT**: read the current implementation, identify the CSS stack (Tailwind, CSS Modules, styled-components, etc.), capture screenshot using `dw-testing-discipline`/playwright-recipes if available, run react-doctor if React project.
 3. Ask 3 to 5 questions about redesign goals: style direction, brand constraints, inspirations, target audience, priority devices.
-4. **PROPOSE**: present 2 to 3 design directions using `ui-ux-pro-max` — each with color palette, typography pairing, layout style, and rationale. For EACH direction, explicitly describe the mobile layout (<=768px) and desktop layout (>=1024px), including how elements reorganize, stack, or hide between breakpoints.
+4. **PROPOSE**: present 2 to 3 design directions after passing the `dw-ui-discipline` hard-gate (brand authorities or curated defaults selected; surface job sentence written; state matrix enumerated; scene sentence written). Each direction lists color palette, typography pairing, layout style, and rationale. Self-check each direction against the 14 anti-slop patterns. For EACH direction, explicitly describe the mobile layout (<=768px) and desktop layout (>=1024px), including how elements reorganize, stack, or hide between breakpoints.
 5. Wait for explicit user approval before implementing.
 6. **IMPLEMENT**: apply the chosen design with a mobile-first approach — implement the mobile layout first, then add media queries/breakpoints for tablet and desktop. Respect the existing stack. Use `vercel-react-best-practices` for React/Next.js. Maintain the project's CSS methodology.
-7. **VALIDATE**: capture after-state in BOTH resolutions (mobile and desktop), compare before/after, verify accessibility (WCAG 2.2 via `ui-ux-pro-max`), run react-doctor `--diff` if React. If `webapp-testing` is available, capture screenshots at 375px viewport (mobile) and 1440px viewport (desktop).
+7. **VALIDATE**: capture after-state in BOTH resolutions (mobile and desktop), compare before/after, verify accessibility against `dw-ui-discipline/references/accessibility-floor.md` (WCAG 2.2 AA — non-negotiable: contrast, focus-visible, keyboard nav, ARIA, no traps), run react-doctor `--diff` if React. Use `dw-testing-discipline/references/playwright-recipes.md` to capture screenshots at 375px viewport (mobile) and 1440px viewport (desktop).
 8. **PERSIST CONTRACT**: if the user approved a direction, generate `design-contract.md` in the PRD directory (`.dw/spec/prd-[name]/design-contract.md`) with: approved direction, color palette, typography pairing, layout rules, accessibility rules, and component rules. This contract will be read by `dw-run-task` and `dw-run-plan` to ensure visual consistency.
 
 ## Codebase Intelligence
@@ -82,8 +82,8 @@ Use diagnostic tools based on the project's framework:
 
 ### 2. Design Proposal
 - 2 to 3 directions with visual rationale
-- Color palette (via `ui-ux-pro-max`)
-- Typography pairing (via `ui-ux-pro-max`)
+- Color palette (from brand authority OR `dw-ui-discipline/references/curated-defaults.md`)
+- Typography pairing (same source)
 - Layout pattern
 - Effort level per direction
 

package/scaffold/en/commands/dw-run-qa.md

@@ -20,9 +20,9 @@ You are an AI assistant specialized in Quality Assurance. Your task is to valida
 
 When available in the project under `./.agents/skills/`, use these skills as operational support without replacing this command:
 
-- `webapp-testing`: (UI mode) support for structuring test flows, retests, screenshots, and logs when complementary to Playwright MCP
+- `dw-testing-discipline`: (UI mode) **ALWAYS** — Iron Laws and 25 anti-patterns apply to every QA test authored. `references/playwright-recipes.md` for tactical patterns. `references/three-workflow-patterns.md` to pick the right verification mode (UI / network / perf). `references/security-boundary.md` for any flow that crosses an auth boundary.
 - `vercel-react-best-practices`: (UI mode) use only if the frontend under test is React/Next.js and there is indication of regression related to rendering, fetching, hydration, or perceived performance
-- `ui-ux-pro-max`: (UI mode) use when validating design consistency, color palettes, typography, spacing, and visual hierarchy against industry standards
+- `dw-ui-discipline`: (UI mode) use when validating design consistency — the anti-slop catalog and WCAG accessibility floor are checked as part of QA evidence
 - `api-testing-recipes`: **(API mode — ALWAYS)** validated snippets for `.http`, pytest+httpx, supertest, WebApplicationFactory, reqwest. Composes per-RF test files in `QA/scripts/api/` and JSONL logs in `QA/logs/api/` per its references
 
 ## Analysis Tools
@@ -149,7 +149,7 @@ If NO credentials are found, STOP and ask the user before continuing. Do NOT gue
 - Verify the application is running on localhost
 - Use `browser_navigate` from Playwright MCP to access the application
 - Confirm the page loaded correctly with `browser_snapshot`
-- If persistent session, auth import, or network inspection beyond MCP is needed, complement with `webapp-testing`
+- If persistent session, auth import, or network inspection beyond MCP is needed, complement with `dw-testing-discipline/references/playwright-recipes.md`
 
 ### 3. Menu Page Verification (UI mode only -- Required, Execute BEFORE RF tests)
 
@@ -222,7 +222,7 @@ For each functional requirement from the PRD:
 8. Mark as PASSED or FAILED
 9. Save the Playwright flow script in `{{PRD_PATH}}/QA/scripts/` with standardized name: `RF-XX-[slug].spec.ts` (or `.js`)
 10. Record in the report which credentials (user/profile) were used in each permission-sensitive flow
-11. When the MCP flow becomes unstable or insufficient for operational evidence, complement with `webapp-testing`, recording this explicitly in the report
+11. When the MCP flow becomes unstable or insufficient for operational evidence, complement with `dw-testing-discipline/references/playwright-recipes.md`, recording this explicitly in the report
 
 <critical>It is not enough to validate only the happy path. Each requirement must be exercised against its boundary states and most likely regressions</critical>
 <critical>If a requirement cannot be fully validated via E2E, QA must be marked as REJECTED or BLOCKED, never APPROVED</critical>

package/scaffold/en/commands/dw-run-task.md

@@ -21,7 +21,7 @@ When available in the project at `./.agents/skills/`, use these skills as specia
 | `dw-verify` | **ALWAYS** — invoked before the commit to produce a Verification Report with fresh evidence |
 | `dw-memory` | **ALWAYS** — reads workflow memory at task start and updates it at task end (promotion test) |
 | `vercel-react-best-practices` | Task touches React rendering, hydration, data fetching, bundle, cache, or performance |
-| `webapp-testing` | Task has interactive frontend needing E2E validation in a real browser |
+| `dw-testing-discipline` | Task needs tests (any layer) — applies Iron Laws, 7 AI Gates, anti-patterns catalog. Use `references/playwright-recipes.md` when the task has interactive frontend needing E2E validation. |
 
 ## Codebase Intelligence
 
@@ -93,7 +93,7 @@ After providing the summary and approach, **begin implementation immediately**:
 - Follow established project patterns
 - Ensure all requirements are met
 - **Run tests**: use the project's test command
-- If there is interactive frontend, also validate real behavior with `webapp-testing` when doing so reduces the risk of invisible regression in unit tests
+- If there is interactive frontend, also validate real behavior using `dw-testing-discipline/references/playwright-recipes.md` when doing so reduces the risk of invisible regression in unit tests
 
 **YOU MUST** start the implementation right after the process above.
 

package/scaffold/en/templates/constitution-template.md

@@ -0,0 +1,111 @@
+---
+schema_version: "1.0"
+generated_by: dev-workflow
+last_updated: YYYY-MM-DD
+mode: defaults | custom
+---
+
+# Project Constitution
+
+> Declarative principles this team has chosen to follow. PRDs, TechSpecs, and Code Reviews read this file as a hard gate. Anything that violates a principle with `severity: critical` or `high` is blocked unless explicitly justified by an ADR.
+
+## How this file works
+
+- **Each principle has an ID (`P-NNN`), a severity, a rule, a `Why`, and an `Enforcement`.**
+- **Severity ladder:** `info` (reports only, never blocks) → `high` (blocks PR without ADR) → `critical` (blocks PR without ADR, requires reviewer sign-off).
+- **Edit freely.** This file is yours to evolve. Promote principles from `info` to `high` once you trust the project enforces them.
+- **ADR escape hatch.** A PR that violates a `high`/`critical` principle is unblocked only when an ADR in the same feature documents the deviation and trade-off.
+- **Regenerate analytical version** anytime via `/dw-analyze-project` (offers to synthesize principles from observed code patterns).
+
+---
+
+## Code Quality
+
+**P-001 — No `any` / `unknown` casts in TypeScript without justification** (severity: info)
+**Rule:** Production code must not use `as any`, `as unknown`, or `// @ts-ignore` without an inline `// @ts-ignore — reason: <X>` comment naming the constraint.
+**Why:** Silent type escapes leak runtime bugs that the type system was meant to catch. Each escape is a contract the type system stops enforcing.
+**Enforcement:** `dw-code-review` greps the diff for `as any`/`@ts-ignore`/`@ts-expect-error` without an accompanying reason comment.
+
+**P-002 — Functions must be testable in isolation** (severity: info)
+**Rule:** A function that touches network, filesystem, database, or system clock must accept its dependency as a parameter (or via a factory) instead of importing it directly.
+**Why:** Code that constructs its own dependencies cannot be tested without integration setup. Tests slow down, get skipped, and bugs ship.
+**Enforcement:** `dw-code-review` flags functions importing `fs`, `axios`, `prisma`, `Date.now`, etc., directly inside business logic modules.
+
+---
+
+## Testing Standards
+
+**P-003 — Every bug fix ships with a regression test** (severity: info)
+**Rule:** A commit with type `fix:` must add or modify at least one test that would have caught the bug before the fix.
+**Why:** Without the test, the bug returns the next time someone refactors the area. The fix decays.
+**Enforcement:** `dw-code-review` checks that `fix:` commits include diff under `**/*test*` or `**/*spec*` paths.
+
+**P-004 — Tests must be deterministic** (severity: info)
+**Rule:** No sleep-based waits, no real-clock comparisons, no network calls to live services in unit tests. Mock at boundaries.
+**Why:** Flaky tests train the team to ignore failures. The next real failure goes unnoticed.
+**Enforcement:** `dw-code-review` greps tests for `setTimeout`, real fetch/axios calls, and `Date.now()` without `vi.useFakeTimers()`/`jest.useFakeTimers()`.
+
+---
+
+## UX Consistency
+
+**P-005 — User-facing strings live in a single source** (severity: info)
+**Rule:** All visible copy (labels, error messages, empty states) goes through a centralized i18n / strings module — not inline in components.
+**Why:** Inline strings drift in tone, break i18n efforts, and cause duplicate-but-different copies of the same message.
+**Enforcement:** `dw-code-review` flags JSX text nodes and error messages declared inside components instead of imported from `src/strings/`, `src/i18n/`, or equivalent.
+
+**P-006 — Loading + empty + error states are mandatory for any data-fetching UI** (severity: info)
+**Rule:** Any component or page that fetches data must explicitly render loading, empty, and error states — not just the happy path.
+**Why:** "Just the spinner" experiences and silent error states are the #1 source of user-reported bugs.
+**Enforcement:** `dw-review-implementation` checks data-fetching components for all three states in JSX or equivalent.
+
+---
+
+## Performance
+
+**P-007 — Performance changes must cite a measurement** (severity: info)
+**Rule:** Any commit that claims to improve performance must include the metric, the tool, and the before/after numbers in the commit body OR in the techspec.
+**Why:** Without measurement, "performance" optimization is guesswork — and usually wrong (see `dw-simplification` + `perf-discipline.md`).
+**Enforcement:** `dw-code-review` checks `perf:` commits for a numeric before/after; flags if missing.
+
+**P-008 — N+1 queries are flagged at code review** (severity: info)
+**Rule:** Loops or list operations that issue per-item database/HTTP calls must batch (e.g., `IN (...)`, `findMany`, DataLoader) or be explicitly justified.
+**Why:** N+1 patterns scale linearly with data size and silently degrade until production load reveals them.
+**Enforcement:** `dw-code-review` and `dw-refactoring-analysis` detect await-in-loop patterns against repository / API client modules.
+
+---
+
+## Security
+
+**P-009 — Server-side authorization on every state-changing endpoint** (severity: info)
+**Rule:** Any endpoint that creates, updates, or deletes data must verify caller authorization on the server. UI-level gating (hidden buttons, disabled forms) is not security.
+**Why:** Browsers are untrusted (see `dw-testing-discipline/references/security-boundary.md`). UI gating is convenience; only server checks protect data.
+**Enforcement:** `dw-code-review` and `dw-security-check` require an explicit auth check (decorator, middleware, or in-handler assertion) on POST/PUT/PATCH/DELETE routes.
+
+**P-010 — Secrets never enter the repository** (severity: info)
+**Rule:** No API keys, passwords, signing keys, tokens, or production endpoints checked into source. `.env.example` documents shape only.
+**Why:** Repository history is permanent. A secret committed once is leaked even if reverted next commit.
+**Enforcement:** `dw-security-check` runs Trivy + secret scanners on the diff.
+
+---
+
+## Custom Principles
+
+> Add your team's specific principles below. Follow the same format: `**P-NNN — <name>** (severity: info|high|critical): <rule>. **Why:** <reason>. **Enforcement:** <how>.`
+
+<!-- Example:
+**P-100 — All financial calculations use Decimal, never Number** (severity: critical)
+**Rule:** Money values must use `Decimal` / `BigDecimal` types end-to-end. No `parseFloat`, no `Number` arithmetic.
+**Why:** IEEE 754 rounding errors accumulate to cents lost over millions of transactions; audited environments mandate exact arithmetic.
+**Enforcement:** `dw-code-review` greps for `Number(`/`parseFloat(` in any file under `src/billing/`, `src/payments/`, `src/finance/`.
+-->
+
+---
+
+## How to evolve this file
+
+1. **Live in `info` for at least one release.** Watch how often each principle is violated organically; the data tells you if it's worth promoting.
+2. **Promote to `high` once violations are rare and the team agrees.** PRs that violate a `high` principle now need an ADR.
+3. **Promote to `critical` for principles that protect users / data / compliance.** Treat these as load-bearing; the ADR escape requires reviewer sign-off, not just author opt-out.
+4. **Demote or remove principles that don't earn their weight.** A constitution is a tool, not a museum.
+5. **Re-run `/dw-analyze-project`** when the codebase shifts substantially (new stack, major refactor); it can propose updates grounded in fresh observation.