@brunosps00/dev-workflow 0.10.0 → 0.11.0

package/README.md

@@ -158,6 +158,31 @@ Shortcuts:
   /dw-redesign-ui "target"     Visual redesign of a page or component
 ```
 
+## Constitution
+
+A **constitution** is a declarative list of principles your team commits to (e.g., "every state-changing endpoint requires server-side authorization", "every bug fix ships with a regression test"). It lives at `.dw/constitution.md` and complements `.dw/rules/`:
+
+| File | Type | Authored by |
+|------|------|-------------|
+| `.dw/rules/` | Analytical — describes what the code IS (observed patterns) | `/dw-analyze-project` |
+| `.dw/constitution.md` | Declarative — describes what the code SHOULD BE (committed principles) | `/dw-analyze-project` (Step 8) or auto-installed defaults |
+
+**How it works:**
+
+- `/dw-analyze-project` offers three paths: synthesize from observed patterns (with your approval), install canonical defaults, or skip.
+- If `/dw-create-prd`, `/dw-create-techspec`, or `/dw-code-review` run **without** a constitution, they auto-install the defaults template (10 canonical principles at `severity: info`), notify in chat, and continue. Ausência nunca bloqueia.
+- Once principles exist:
+  - `severity: info` → reported, never blocks.
+  - `severity: high` → blocks PR/techspec when violated, unless an ADR justifies the deviation.
+  - `severity: critical` → blocks plus requires reviewer sign-off in the ADR.
+- Defaults start at `info`; you promote severities as your team trusts enforcement.
+
+**Tasks consistency check.** At the end of `/dw-create-tasks`, a 5-dimension consistency check validates PRD ↔ TechSpec ↔ Tasks alignment (FR coverage, task grounding, test coverage, dependency DAG, constitution alignment) and writes `.dw/spec/prd-<feature>/tasks-validation.md`. Any FAIL blocks user approval until resolved or explicitly overridden.
+
+## Template Overrides
+
+Customize templates locally without losing dev-workflow updates. Drop a file at `.dw/templates/overrides/<name>.md`; the override is used in place of the bundled core template on every `update`. Subdirectories work too (e.g., `.dw/templates/overrides/functional-doc/e2e-runbook.md`). See `.dw/templates/overrides/README.md` (created on init) for the workflow and `diff` cadence guidance.
+
 ## Platform Support
 
 | Platform | Wrapper Location | Status |
@@ -176,10 +201,12 @@ your-project/
 ├── .dw/
 │   ├── commands/          # 30 workflow command files
 │   ├── templates/         # Document templates (PRD, TechSpec, etc.)
+│   │   └── overrides/     # Project-local template customizations (override > core)
 │   ├── rules/             # Project-specific rules (run /dw-analyze-project)
+│   ├── constitution.md    # Declarative principles (auto-installed when missing)
 │   ├── references/        # Reference documentation
 │   ├── scripts/           # Utility scripts
-│   └── spec/              # PRD directories created by commands
+│   └── spec/              # PRD directories — each contains tasks-validation.md
 ├── .claude/
 │   ├── skills/            # Claude Code wrappers
 │   └── settings.json      # MCP servers (Context7, Playwright)
@@ -259,6 +286,8 @@ Codebase intelligence (`/dw-intel`, `/dw-map-codebase`, the `dw-codebase-intel`
 
 Source-driven development, code simplification, debugging discipline, and git workflow patterns adapted from [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) by Addy Osmani (MIT) into the bundled `dw-source-grounding`, `dw-simplification`, `dw-debug-protocol`, and `dw-git-discipline` skills. Performance-optimization workflow (`vercel-react-best-practices/references/perf-discipline.md`), API-design discipline (`dw-codebase-intel/references/api-design-discipline.md`), and browser-DevTools patterns (`webapp-testing/references/{security-boundary, three-workflow-patterns}`) also incorporated as enhancements to existing bundled skills.
 
+Spec-Driven Development patterns — declarative constitution (`.dw/constitution.md`), cross-artifact consistency check (PRD ↔ TechSpec ↔ Tasks), and template override layer (`.dw/templates/overrides/`) — adapted from [`github/spec-kit`](https://github.com/github/spec-kit) by GitHub (MIT). dev-workflow specifics: embedded into existing commands instead of new slash commands, severity-graded enforcement (`info`/`high`/`critical`) with ADR-justified deviation as the escape hatch, ausência-of-constitution never blocks (auto-installs defaults and continues), and integration with the analytical `.dw/rules/` already produced by `/dw-analyze-project`.
+
 ## License
 
 MIT

package/lib/init.js

@@ -48,18 +48,35 @@ async function run({ force = false, lang = null, mode = 'init' }) {
   totalOverwritten += cmdResults.overwritten;
   console.log(`    ${cmdResults.created} created, ${cmdResults.skipped} skipped, ${cmdResults.overwritten} overwritten\n`);
 
-  // 3. Copy templates
+  // 3. Copy templates (override-aware: .dw/templates/overrides/<name> wins over scaffold core)
   console.log('  Templates:');
+  const templatesDir = path.join(projectRoot, '.dw', 'templates');
+  const overridesDir = path.join(templatesDir, 'overrides');
   const tplResults = copyDir(
     path.join(langDir, 'templates'),
-    path.join(projectRoot, '.dw', 'templates'),
-    managedForce
+    templatesDir,
+    managedForce,
+    overridesDir
   );
   totalCreated += tplResults.created;
   totalSkipped += tplResults.skipped;
   totalOverwritten += tplResults.overwritten;
   console.log(`    ${tplResults.created} created, ${tplResults.skipped} skipped, ${tplResults.overwritten} overwritten\n`);
 
+  // 3.1. Seed .dw/templates/overrides/ with README on first init (never overwritten)
+  ensureDir(overridesDir);
+  const overridesReadmeSrc = path.join(SCAFFOLD_DIR, 'templates-overrides-readme.md');
+  const overridesReadmeDest = path.join(overridesDir, 'README.md');
+  if (require('fs').existsSync(overridesReadmeSrc)) {
+    const ovrStatus = writeFile(
+      overridesReadmeDest,
+      require('fs').readFileSync(overridesReadmeSrc, 'utf-8'),
+      false
+    );
+    if (ovrStatus === 'created') totalCreated++;
+    else totalSkipped++;
+  }
+
   // 3.5. Copy references (language-specific)
   const refsSrcDir = path.join(langDir, 'references');
   if (require('fs').existsSync(refsSrcDir)) {

package/lib/utils.js

@@ -29,7 +29,7 @@ function writeFile(filePath, content, force = false) {
   return exists ? 'overwritten' : 'created';
 }
 
-function copyDir(srcDir, destDir, force = false) {
+function copyDir(srcDir, destDir, force = false, overridesDir = null) {
   const results = { created: 0, skipped: 0, overwritten: 0 };
 
   if (!fs.existsSync(srcDir)) {
@@ -40,14 +40,19 @@ function copyDir(srcDir, destDir, force = false) {
   for (const entry of entries) {
     const srcPath = path.join(srcDir, entry.name);
     const destPath = path.join(destDir, entry.name);
+    const overridePath = overridesDir ? path.join(overridesDir, entry.name) : null;
 
     if (entry.isDirectory()) {
-      const sub = copyDir(srcPath, destPath, force);
+      const subOverrides = overridePath && fs.existsSync(overridePath) ? overridePath : null;
+      const sub = copyDir(srcPath, destPath, force, subOverrides);
       results.created += sub.created;
       results.skipped += sub.skipped;
       results.overwritten += sub.overwritten;
     } else {
-      const status = copyFile(srcPath, destPath, force);
+      // Override wins: copy from override path so dest reflects user customization.
+      // Always force-copy overrides so a manual edit to overrides/X.md propagates to templates/X.md on next update.
+      const effectiveSrc = overridePath && fs.existsSync(overridePath) ? overridePath : srcPath;
+      const status = copyFile(effectiveSrc, destPath, effectiveSrc === overridePath ? true : force);
       results[status]++;
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"

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-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

@@ -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/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 `webapp-testing/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.

package/scaffold/pt-br/commands/dw-analyze-project.md

@@ -645,6 +645,67 @@ packages/auth → packages/db
 - Crie o diretório .dw/rules/ se não existir
 </critical>
 
+### Step 8: Constitution Generation (Opcional, mas Recomendado)
+
+Após escrever `.dw/rules/`, oferecer gerar `.dw/constitution.md` — os princípios declarativos que o time quer ver enforçados em PRDs, TechSpecs e Code Reviews.
+
+**Diferença vs `.dw/rules/`:**
+- `.dw/rules/` é **analítico** — o que o código É (padrões observados, anti-patterns, convenções).
+- `.dw/constitution.md` é **declarativo** — o que o código DEVE SER (regras às quais o time se compromete).
+
+**Comportamento:**
+
+Se `.dw/constitution.md` já existir, imprimir "Constituição já existe em `.dw/constitution.md` — pulando (edite manualmente se quiser atualizar)" e encerrar.
+
+Caso contrário, apresentar 3 opções no chat (use a UI de pergunta preferida quando disponível; caso contrário texto puro):
+
+```
+Uma constitution ajudaria PRDs/TechSpecs/PRs a permanecerem alinhados aos padrões.
+Três opções:
+
+  A) Sintetizar dos padrões observados (recomendado)
+     Leio `.dw/rules/` e proponho 5–8 princípios fundamentados no código real,
+     cada um com `Why:` ligado a evidência e `severity: info` (não bloqueia).
+     Você revisa e aprova antes de qualquer escrita.
+
+  B) Instalar template de defaults
+     Copia `templates/constitution-template.md` para `.dw/constitution.md` com
+     5 princípios canônicos (Qualidade, Testes, UX, Performance, Segurança)
+     pré-preenchidos em `severity: info`. Você customiza manualmente.
+
+  C) Pular
+     Sem constitution. Comandos downstream operam sem o gate.
+     Você pode rodar este step novamente re-executando `/dw-analyze-project`.
+```
+
+**Opção A — Sintetizar:**
+
+1. Ler `.dw/rules/index.md` + cada `.dw/rules/{module}.md`.
+2. Propor 5–8 princípios. Cada um deve:
+   - Ter ID único `P-NNN`.
+   - Mapear para uma observação em `.dw/rules/` (citar o arquivo + seção).
+   - Começar em `severity: info` (nunca propor `high`/`critical` automaticamente — isso é decisão do time).
+   - Seguir formato: `**P-NNN — <nome>** (severity: info): <regra>. **Why:** <fundamentar em evidência>. **Enforcement:** <como checar>.`
+3. **Mostrar os princípios propostos no chat como lista markdown** (não escreva o arquivo ainda). Incluir a citação de evidência para cada um.
+4. Perguntar: "Edita algum antes de eu gravar? Responda com os IDs para descartar/editar, ou 'aprovar' para escrever como está."
+5. Após aprovação (com edits aplicados), gravar em `.dw/constitution.md` usando a mesma estrutura de `templates/constitution-template.md`.
+6. Setar frontmatter `mode: custom` e `last_updated: <data ISO de hoje>`.
+
+**Opção B — Defaults:**
+
+1. Localizar `templates/constitution-template.md` (projeto-local em `.dw/templates/constitution-template.md`, com fallback para scaffold bundled).
+2. Copiar para `.dw/constitution.md` literalmente. Setar frontmatter `mode: defaults`.
+3. Imprimir: "Constituição defaults instalada em `.dw/constitution.md`. Todos os 10 princípios começam em `severity: info` — reportam mas não bloqueiam. Edite o arquivo para customizar, depois promova severities para `high`/`critical` quando confiar."
+
+**Opção C — Pular:**
+
+1. Nada a fazer.
+2. Imprimir: "Pulado. PRD/TechSpec/CodeReview rodarão sem o constitution gate. Re-rode `/dw-analyze-project` mais tarde se quiser habilitar."
+
+**Em qualquer opção:**
+- Nunca escrever `.dw/constitution.md` sem aprovação explícita (opção A) ou escolha explícita (opções B/C).
+- Constitution é commitada ao repositório como qualquer outro artefato do projeto — nunca gitignored.
+
 ## Checklist de Qualidade
 
 - [ ] Estrutura do repositório escaneada

package/scaffold/pt-br/commands/dw-code-review.md

@@ -159,6 +159,34 @@ Para cada projeto impactado, verificar rules específicas em `.dw/rules/`:
 - [ ] Chamadas de API usam utilitários fetch do projeto
 - [ ] UI segue o design system do projeto
 
+### 4.1. Constitution Compliance (Obrigatório quando `.dw/constitution.md` existe)
+
+<critical>**Auto-create se ausente**: se `.dw/constitution.md` NÃO existir, copie `templates/constitution-template.md` (project-local `.dw/templates/constitution-template.md` primeiro, com fallback para scaffold bundled) literalmente com frontmatter `mode: defaults`. Imprimir no chat: "Constituição defaults instalada em `.dw/constitution.md` (todos os princípios em `severity: info` — reportam mas não bloqueiam este review). Seguindo." Depois prossiga.</critical>
+
+Para cada princípio em `.dw/constitution.md`, verificar o diff por violações:
+
+1. **Parsear princípios**: ler cada entrada `**P-NNN — <nome>** (severity: <S>)`; capturar `P-NNN`, `severity` e descrição de `Enforcement`.
+2. **Aplicar enforcement**: para cada princípio, rodar a checagem de enforcement contra o diff (grep, inspeção de arquivo ou pattern match conforme a linha Enforcement).
+3. **Classificar violações**:
+   - Princípio `severity: info` → adicione linha à tabela "Issues Found" com severity `low`. **Não bloqueia** o verdict.
+   - Princípio `severity: high` → adicione linha com severity `critical`. **Bloqueia** o verdict como `REJECTED` EXCETO se um ADR no `adrs/` do mesmo PRD documenta o desvio (busque `Deviates: P-NNN` no corpo de qualquer ADR).
+   - Princípio `severity: critical` → adicione linha com severity `critical` E exigir que o ADR tenha campo `Approved by:` não-vazio. Campo ausente = ainda `REJECTED`.
+4. **Sem skip silencioso**: se o diff for grande demais para analisar todos os princípios, reportar quais foram checados e quais foram pulados por escopo.
+
+**Formato de saída no relatório:**
+
+```markdown
+## Constitution Compliance
+
+| Princípio | Severity | Status | Evidência | ADR escape |
+|-----------|----------|--------|-----------|------------|
+| P-001 — Sem `any` casts | info | VIOLATED | src/foo.ts:42 | n/a |
+| P-009 — Auth server-side | high | VIOLATED | src/api/order.ts:18 sem auth middleware | none → BLOQUEIA |
+| P-010 — Secrets no repo | critical | PASS | — | — |
+```
+
+Se houver violação `high`/`critical` sem ADR escape: adicionar à linha de verdict "REPROVADO — violação(ões) de constitution sem ADR (ver seção Constitution Compliance)".
+
 ### 5. Análise de Qualidade de Código (Obrigatório)
 
 | Aspecto | Verificação |

package/scaffold/pt-br/commands/dw-create-prd.md

@@ -50,6 +50,22 @@
     - Use `.dw/rules/` como contexto, caindo para grep
     - Sugira rodar `/dw-map-codebase` para enriquecer contexto downstream
 
+    ## Constitution Gate
+
+    <critical>ANTES das clarification questions, cheque `.dw/constitution.md`:
+
+    **Se AUSENTE**: copie `templates/constitution-template.md` (project-local em `.dw/templates/constitution-template.md`, com fallback para scaffold bundled) literalmente para `.dw/constitution.md`. Setar frontmatter `mode: defaults` e `last_updated` para data ISO de hoje. Imprimir no chat:
+
+    > "Notei que `.dw/constitution.md` estava ausente. Instalei defaults em `.dw/constitution.md` (10 princípios canônicos, todos em `severity: info` — reportam mas não bloqueiam). Pode customizar a qualquer momento — ou re-rodar `/dw-analyze-project` para versão sob medida. Seguindo com o PRD."
+
+    Depois prossiga normalmente, tratando o arquivo recém-criado como a constitution.
+
+    **Se PRESENTE**: leia antes de redigir requisitos. Cada FR no PRD DEVE incluir linha "Constitution Alignment" mapeando para ≥1 princípio relevante (`Respects: P-001, P-009`) OU declarando explicitamente "no applicable principle" com motivo em uma linha. Sem alignment = FR está incompleto.
+
+    **Regras de severity** (aplicadas pelos comandos downstream, não enforçadas aqui):
+    - Violações `severity: info` → reportadas, nunca bloqueiam.
+    - Violações `severity: high` / `critical` → bloqueiam em `dw-create-techspec` e `dw-code-review` exceto se ADR justificar.</critical>
+
     ## Features Multi-Projeto
 
     Muitas funcionalidades podem envolver mais de um projeto no workspace.

package/scaffold/pt-br/commands/dw-create-tasks.md

@@ -149,5 +149,47 @@
     3. /dw-generate-pr [branch-alvo] quando todas tasks concluídas
     ```
 
+    ## Final Consistency Check (Auto-invocado antes da aprovação do usuário)
+
+    <critical>ANTES de apresentar tasks ao usuário, rode um check de consistência em 5 dimensões. Isto é mandatório; não pule mesmo se confiante de que as tasks estão limpas.</critical>
+
+    Rode estes 5 checks contra o conjunto PRD + TechSpec + tasks gerado:
+
+    1. **Cobertura de RF** — cada RF numerada no PRD mapeia para ≥1 task. RFs órfãs (PRD tem; nenhuma task cobre) são FAIL.
+    2. **Grounding das tasks** — cada task gerada referencia ≥1 RF em seu corpo (`Cobre: RF-N.M`). Tasks sem referência a RF sinalizam scope creep.
+    3. **Cobertura de teste** — cada RF com comportamento user-facing (UI, endpoint de API, mutação de dado) tem ≥1 task que adiciona teste (subtask contendo "test", "spec", "e2e" ou equivalente).
+    4. **Grafo de dependências** — dependências entre tasks (X.0 → Y.0 declarado como "Depende de") formam DAG. Sem ciclos. Ordem topológica válida.
+    5. **Alinhamento com constitution** (só se `.dw/constitution.md` existir) — cada task lista `Constitution: respects P-NNN, P-MMM` OU `Constitution: deviates P-NNN — ADR planejado: <slug>` OU `Constitution: n/a — motivo: <one-liner>`. Linha ausente = FAIL.
+
+    Escreva findings em `.dw/spec/prd-[nome-funcionalidade]/tasks-validation.md` com esta estrutura exata:
+
+    ```markdown
+    # Relatório de Validação de Tasks
+
+    Gerado por /dw-create-tasks em YYYY-MM-DD.
+
+    | Dimensão | Status | Findings |
+    |----------|--------|----------|
+    | 1. Cobertura de RF | PASS / FAIL | <lista de RFs órfãs ou "todas RFs cobertas"> |
+    | 2. Grounding de tasks | PASS / FAIL | <lista de tasks sem RF ou "todas tasks referenciam RFs"> |
+    | 3. Cobertura de teste | PASS / FAIL | <RFs sem testes ou "todas RFs user-facing cobertas"> |
+    | 4. Grafo de dependências | PASS / FAIL | <ciclos ou "DAG válido"> |
+    | 5. Alinhamento constitution | PASS / FAIL / N/A | <tasks não-alinhadas ou "todas alinhadas" ou "sem constitution"> |
+
+    ## Findings Detalhados
+
+    <uma seção por dimensão FAIL com fixes concretos; vazio se tudo PASS>
+    ```
+
+    **Comportamento do gate:**
+
+    - **Todas as 5 dimensões PASS (ou N/A)** → apresente tasks ao usuário normalmente e peça aprovação.
+    - **Qualquer dimensão FAIL** → PARE. Mostre a tabela no chat como markdown (NÃO esconda no arquivo de validação; o usuário precisa ver antes de aprovar). Depois pergunte ao usuário:
+      - "(a) Quer que eu conserte as tasks automaticamente?" → regenerar tasks afetadas, re-rodar o check.
+      - "(b) Vai editar tasks.md manualmente?" → aguardar usuário sinalizar conclusão, re-rodar o check.
+      - "(c) Override e seguir mesmo com FAIL?" → exigir mensagem de override explícita ("override: aceito o gap porque <motivo>"). Persistir o override em `tasks-validation.md` para auditabilidade.
+
+    O arquivo `tasks-validation.md` é commitado junto com `tasks.md`. Comandos downstream (`/dw-run-plan`, `/dw-code-review`, `/dw-review-implementation`) podem referenciá-lo.
+
     Após completar a análise e gerar todos os arquivos necessários, apresente os resultados ao usuário e aguarde confirmação para prosseguir com a implementação.
 </system_instructions>

package/scaffold/pt-br/commands/dw-create-techspec.md

@@ -39,6 +39,23 @@
     - Use `.dw/rules/` como contexto, caindo para grep
     - Sugira rodar `/dw-map-codebase` para enriquecer contexto downstream
 
+    ## Constitution Gate
+
+    <critical>ANTES de redigir decisões arquiteturais, cheque `.dw/constitution.md`:
+
+    **Se AUSENTE**: copie `templates/constitution-template.md` (project-local em `.dw/templates/constitution-template.md`, com fallback para scaffold bundled) literalmente para `.dw/constitution.md`. Setar frontmatter `mode: defaults`. Imprimir no chat: "Constituição defaults instalada em `.dw/constitution.md` (severity: info — não bloqueia este techspec). Seguindo." Depois prossiga.
+
+    **Se PRESENTE**: leia. Toda escolha de framework / library / arquitetura no techspec DEVE carregar uma de:
+    - `Respects: P-NNN` — a decisão honra ativamente o(s) princípio(s) nomeado(s).
+    - `Deviates: P-NNN — justification: <slug do ADR ou racional em uma linha>` — a decisão se afasta intencionalmente do princípio.
+
+    **Gate graduado por severity:**
+    - Desvio de princípio `severity: info` → apenas registra, nunca bloqueia.
+    - Desvio de princípio `severity: high` sem ADR linkado (`.dw/spec/<prd>/adrs/adr-NNN.md`) → BLOQUEIA o techspec. Instrua o usuário a revisar a decisão OU criar ADR via `/dw-adr` documentando o trade-off.
+    - Desvio de princípio `severity: critical` → BLOQUEIA o techspec com mesma exigência de ADR, adicionalmente exigindo acknowledgment de reviewer no campo `Approved by` do ADR.
+
+    Sem exceções para `high`/`critical` sem ADR. Se o usuário resistir, aponte para `/dw-adr` — esse é o escape hatch por design.</critical>
+
     ## Fluxograma de Decisão Multi-Projeto
 
     ```dot

package/scaffold/pt-br/templates/constitution-template.md

@@ -0,0 +1,111 @@
+---
+schema_version: "1.0"
+generated_by: dev-workflow
+last_updated: YYYY-MM-DD
+mode: defaults | custom
+---
+
+# Constituição do Projeto
+
+> Princípios declarativos que este time escolheu seguir. PRDs, TechSpecs e Code Reviews leem este arquivo como hard gate. Qualquer coisa que viole um princípio com `severity: critical` ou `high` é bloqueada — exceto quando justificada por um ADR explícito.
+
+## Como este arquivo funciona
+
+- **Cada princípio tem um ID (`P-NNN`), severity, regra, `Why` e `Enforcement`.**
+- **Escala de severity:** `info` (apenas reporta, nunca bloqueia) → `high` (bloqueia PR sem ADR) → `critical` (bloqueia PR sem ADR + exige aprovação de reviewer).
+- **Edite à vontade.** Este arquivo é seu para evoluir. Promova princípios de `info` para `high` quando confiar que o projeto cumpre.
+- **Escape via ADR.** Um PR que viola princípio `high`/`critical` é desbloqueado quando um ADR na mesma feature documenta o desvio e o trade-off.
+- **Versão analítica regenerável** a qualquer momento via `/dw-analyze-project` (oferece sintetizar princípios a partir dos padrões observados no código).
+
+---
+
+## Qualidade de Código
+
+**P-001 — Sem `any` / `unknown` em TypeScript sem justificativa** (severity: info)
+**Regra:** Código de produção não pode usar `as any`, `as unknown` ou `// @ts-ignore` sem comentário inline `// @ts-ignore — motivo: <X>` nomeando a restrição.
+**Why:** Escapes silenciosos do tipo vazam bugs de runtime que o type system existia para pegar. Cada escape é um contrato que o type system para de garantir.
+**Enforcement:** `dw-code-review` greppa o diff por `as any`/`@ts-ignore`/`@ts-expect-error` sem comentário-razão correspondente.
+
+**P-002 — Funções devem ser testáveis isoladamente** (severity: info)
+**Regra:** Função que toca rede, filesystem, banco de dados ou system clock deve receber a dependência como parâmetro (ou via factory) em vez de importar diretamente.
+**Why:** Código que constrói suas próprias dependências não pode ser testado sem setup de integração. Testes ficam lentos, são pulados, e bugs vão pra produção.
+**Enforcement:** `dw-code-review` flagueia funções importando `fs`, `axios`, `prisma`, `Date.now`, etc., diretamente em módulos de business logic.
+
+---
+
+## Padrões de Teste
+
+**P-003 — Todo bug fix carrega um regression test** (severity: info)
+**Regra:** Commit com tipo `fix:` deve adicionar ou modificar pelo menos um teste que teria pego o bug antes do fix.
+**Why:** Sem o teste, o bug volta na próxima vez que alguém refatora a área. O fix se deteriora.
+**Enforcement:** `dw-code-review` verifica se commits `fix:` incluem diff em paths `**/*test*` ou `**/*spec*`.
+
+**P-004 — Testes devem ser determinísticos** (severity: info)
+**Regra:** Sem `sleep`-based waits, sem comparações de relógio real, sem chamadas a serviços live em unit tests. Mockar em boundaries.
+**Why:** Testes flaky treinam o time a ignorar falhas. A próxima falha real passa despercebida.
+**Enforcement:** `dw-code-review` greppa testes por `setTimeout`, chamadas reais de fetch/axios, e `Date.now()` sem `vi.useFakeTimers()`/`jest.useFakeTimers()`.
+
+---
+
+## Consistência de UX
+
+**P-005 — Strings user-facing vivem em fonte única** (severity: info)
+**Regra:** Toda copy visível (labels, mensagens de erro, empty states) passa por um módulo centralizado de i18n / strings — não inline em componentes.
+**Why:** Strings inline driftam no tom, quebram esforços de i18n e causam duplicatas da mesma mensagem em variações sutis.
+**Enforcement:** `dw-code-review` flagueia text nodes JSX e mensagens de erro declarados dentro de componentes em vez de importados de `src/strings/`, `src/i18n/`, ou equivalente.
+
+**P-006 — Estados de loading + empty + error são obrigatórios em qualquer UI que busca dados** (severity: info)
+**Regra:** Componente ou página que faz fetch deve renderizar explicitamente loading, empty e error — não só o happy path.
+**Why:** Experiências "só com spinner" e estados de erro silencioso são a #1 fonte de bugs reportados por usuários.
+**Enforcement:** `dw-review-implementation` verifica componentes de data-fetching pelos três estados em JSX ou equivalente.
+
+---
+
+## Performance
+
+**P-007 — Mudanças de performance carregam medição** (severity: info)
+**Regra:** Qualquer commit que afirme melhorar performance deve incluir a métrica, a ferramenta e os números antes/depois no body do commit OU no techspec.
+**Why:** Sem medição, "otimização" de performance é palpite — e geralmente errado (ver `dw-simplification` + `perf-discipline.md`).
+**Enforcement:** `dw-code-review` verifica commits `perf:` por números antes/depois; flagueia se ausente.
+
+**P-008 — Queries N+1 são flagueadas em code review** (severity: info)
+**Regra:** Loops ou operações em lista que disparam chamadas DB/HTTP por item devem batchar (ex: `IN (...)`, `findMany`, DataLoader) ou ser explicitamente justificadas.
+**Why:** Padrões N+1 escalam linearmente com tamanho dos dados e silenciosamente degradam até que a carga de produção revele.
+**Enforcement:** `dw-code-review` e `dw-refactoring-analysis` detectam padrões await-em-loop contra módulos de repository / API client.
+
+---
+
+## Segurança
+
+**P-009 — Authorization server-side em todo endpoint que altera estado** (severity: info)
+**Regra:** Endpoint que cria, atualiza ou deleta dado deve verificar autorização do caller no servidor. Gating em UI (botões escondidos, formulários disabled) não é segurança.
+**Why:** Browsers são untrusted (ver `webapp-testing/security-boundary.md`). Gating em UI é conveniência; só checks server-side protegem dado.
+**Enforcement:** `dw-code-review` e `dw-security-check` exigem check de auth explícito (decorator, middleware ou assertion in-handler) em rotas POST/PUT/PATCH/DELETE.
+
+**P-010 — Secrets nunca entram no repositório** (severity: info)
+**Regra:** Nenhuma API key, password, signing key, token ou endpoint de produção commitado em source. `.env.example` documenta forma apenas.
+**Why:** Histórico de repositório é permanente. Um secret commitado uma vez está vazado mesmo que revertido no commit seguinte.
+**Enforcement:** `dw-security-check` roda Trivy + secret scanners no diff.
+
+---
+
+## Princípios Customizados
+
+> Adicione princípios específicos do seu time abaixo. Mesmo formato: `**P-NNN — <nome>** (severity: info|high|critical): <regra>. **Why:** <motivo>. **Enforcement:** <como>.`
+
+<!-- Exemplo:
+**P-100 — Todo cálculo financeiro usa Decimal, nunca Number** (severity: critical)
+**Regra:** Valores monetários devem usar tipos `Decimal` / `BigDecimal` end-to-end. Sem `parseFloat`, sem aritmética com `Number`.
+**Why:** Erros de arredondamento IEEE 754 acumulam centavos perdidos em milhões de transações; ambientes auditados exigem aritmética exata.
+**Enforcement:** `dw-code-review` greppa por `Number(`/`parseFloat(` em qualquer arquivo sob `src/billing/`, `src/payments/`, `src/finance/`.
+-->
+
+---
+
+## Como evoluir este arquivo
+
+1. **Viva em `info` por pelo menos um release-ciclo.** Observe quão frequentemente cada princípio é violado organicamente; o dado te diz se vale promover.
+2. **Promova para `high` quando violações forem raras e o time concordar.** PRs que violarem princípio `high` agora precisam de ADR.
+3. **Promova para `critical` os princípios que protegem usuários / dados / compliance.** Trate-os como load-bearing; o escape via ADR exige aprovação de reviewer, não só opt-out do autor.
+4. **Demote ou remova princípios que não ganharam seu peso.** Constitution é ferramenta, não museu.
+5. **Re-rode `/dw-analyze-project`** quando o codebase mudar substancialmente (nova stack, refactor grande); ele pode propor updates fundamentados em observação fresca.

package/scaffold/templates-overrides-readme.md

@@ -0,0 +1,75 @@
+# Template Overrides
+
+Files in this directory override the corresponding templates in `.dw/templates/`. Use this when your team needs a customized PRD/TechSpec/Task/etc. shape **without** losing the ability to receive `dev-workflow` updates.
+
+## How it works
+
+- During `dev-workflow init` or `dev-workflow update`, the CLI copies templates from the package into `.dw/templates/`.
+- Before writing each file, the CLI checks `.dw/templates/overrides/` for a same-named file.
+- If found, **the override is preserved and the core template is skipped**. Your customization wins.
+- If not found, the core template is installed/updated normally.
+
+## How to override a template
+
+```bash
+# 1. Copy the template you want to customize from .dw/templates/ to .dw/templates/overrides/
+cp .dw/templates/prd-template.md .dw/templates/overrides/prd-template.md
+
+# 2. Edit the override to fit your team's process
+$EDITOR .dw/templates/overrides/prd-template.md
+
+# 3. Commit it. Future updates won't touch this file.
+git add .dw/templates/overrides/prd-template.md
+git commit -m "chore(templates): customize PRD template for our team"
+```
+
+The override takes effect immediately. Commands that consume the template (`/dw-create-prd`, etc.) will read from `.dw/templates/<name>.md`, which is preserved as your edited copy.
+
+## How to revert an override
+
+```bash
+# 1. Delete the override
+rm .dw/templates/overrides/prd-template.md
+
+# 2. Re-run dev-workflow update to restore the core template
+npx @brunosps00/dev-workflow update
+```
+
+## When an override is appropriate
+
+- Adding required sections specific to your industry (compliance, finance, healthcare).
+- Removing sections that don't apply.
+- Renaming sections to match your team's vocabulary.
+- Embedding links to internal tools, dashboards, runbooks.
+
+## When an override is **not** appropriate
+
+- Removing critical-path sections like FR numbering or test plans — downstream commands rely on these.
+- Adding fields that conflict with the YAML frontmatter schema.
+- Anything that breaks `/dw-create-techspec` or `/dw-create-tasks` cross-references.
+
+If in doubt, run the workflow end-to-end after editing — the consistency check at the end of `/dw-create-tasks` will surface most structural breakages.
+
+## Versioning your overrides
+
+When `dev-workflow` releases a new minor version, the core templates may change shape (new sections, renamed fields). Your override will continue to work, but it might lack the new sections.
+
+Recommended cadence: when you upgrade `dev-workflow`, `diff` your override against the new core template:
+
+```bash
+diff .dw/templates/overrides/prd-template.md .dw/templates/prd-template.md
+```
+
+Merge in anything you want from upstream. The override stays canonical; the core template is just a reference.
+
+## Subdirectories
+
+Overrides can mirror the directory structure of `.dw/templates/`. For example, to override a file inside `functional-doc/`:
+
+```
+.dw/templates/overrides/
+└── functional-doc/
+    └── e2e-runbook.md
+```
+
+The resolver descends recursively — each leaf file is checked independently against its corresponding path under `overrides/`.