forgedev 1.1.3 → 1.3.0

package/templates/claude-code/claude-md/base.md

@@ -13,7 +13,7 @@
 
 ## RULES
 - Never commit `.env` files or secrets
-- Never modify migration files directly — generate new migrations instead
+- Never modify migration files directly. Generate new migrations instead
 - All API responses use structured error format: `{ "error": { "code": "ERR_CODE", "message": "..." } }`
 - Never leak stack traces to clients
 - Health check endpoints must always be available
@@ -22,11 +22,11 @@
 {{STACK_SPECIFIC_RULES}}
 
 ## Pitfalls
-- Never commit lock file merge conflicts — delete and regenerate
-- Never use loose types (`any` in TS, `Any` in Python) — use strict types and narrow explicitly
-- Never hardcode URLs, ports, or credentials — use environment variables
-- Never catch errors silently — always log or re-throw
-- Never push directly to main — always use feature branches
+- Never commit lock file merge conflicts. Delete and regenerate
+- Never use loose types (`any` in TS, `Any` in Python). Use strict types and narrow explicitly
+- Never hardcode URLs, ports, or credentials. Use environment variables
+- Never catch errors silently. Always log or re-throw
+- Never push directly to main. Always use feature branches
 - Run `{{TEST_COMMAND}}` before marking any task complete
 
 ## Agents
@@ -48,9 +48,17 @@ Delegate to specialized agents for complex tasks:
 | `chief-of-staff` | Orchestrate multi-agent complex tasks |
 | `loop-operator` | Run autonomous improvement loops |
 | `harness-optimizer` | Audit and optimize Claude Code setup |
+| `product-strategist` | Research competitors, evaluate maturity, recommend improvements |
+| `prompt-auditor` | Audit agent prompts for clarity, consistency, and intent protocol compliance |
+| `spec-validator` | Validate implementation matches specification |
+| `production-readiness` | Verify project is ready for production deployment |
+| `uat-validator` | Map UAT scenarios to tests and report coverage gaps |
+| `frontend-builder` | Build frontend UI with Google Stitch and UI UX Pro Max, preview for acceptance |
+| `deep-reviewer` | Deep code review with multi-pass analysis |
+| `enforcement-gate` | Independently verify agent claims before issuing verdict |
 
 ## Skills
-Framework-specific knowledge is in `.claude/skills/` — reference these for deep patterns:
+Framework-specific knowledge is in `.claude/skills/`. Reference these for deep patterns:
 {{SKILLS_LIST}}
 
 ## Completion Protocol

package/templates/claude-code/claude-md/fastapi.md

@@ -1,8 +1,8 @@
 ## FastAPI Conventions
 - Pydantic v2 for all request/response schemas (use model_config, not class Config)
-- SQLAlchemy 2.0 async style — use `select()` not `query()`, `async with session` not `session.query`
+- SQLAlchemy 2.0 async style. Use `select()` not `query()`, `async with session` not `session.query`
 - Dependency injection via `Depends()` for DB sessions, auth, etc.
-- All endpoints return Pydantic models — never return raw dicts
+- All endpoints return Pydantic models. Never return raw dicts
 - Use `@asynccontextmanager` lifespan for startup/shutdown
 - Database session via `get_db()` dependency (backend/app/db/session.py)
 - Error responses use `AppError` classes (backend/app/core/errors.py)
@@ -12,9 +12,9 @@
 - Ruff for linting, pyright for type checking
 
 ## FastAPI Pitfalls
-- Never use `session.query()` — that's SQLAlchemy 1.x; use `select()` with `session.execute()`
-- Never return raw dicts from endpoints — always use a Pydantic response model
-- Always use `Depends()` for DB session injection — never create sessions manually
-- Never use `from module import *` — always use explicit imports
-- Never use `session.commit()` inside a route — let the dependency handle transaction lifecycle
-- Never store passwords as plaintext — always use bcrypt or argon2 hashing
+- Never use `session.query()`. That's SQLAlchemy 1.x; use `select()` with `session.execute()`
+- Never return raw dicts from endpoints. Always use a Pydantic response model
+- Always use `Depends()` for DB session injection. Never create sessions manually
+- Never use `from module import *`. Always use explicit imports
+- Never use `session.commit()` inside a route. Let the dependency handle transaction lifecycle
+- Never store passwords as plaintext. Always use bcrypt or argon2 hashing

package/templates/claude-code/claude-md/fullstack.md

@@ -1,20 +1,20 @@
 ## Polyglot Full-Stack Conventions
-- `frontend/` contains the Next.js application — follow Next.js conventions above
-- `backend/` contains the FastAPI application — follow FastAPI conventions above
+- `frontend/` contains the Next.js application. Follow Next.js conventions above
+- `backend/` contains the FastAPI application. Follow FastAPI conventions above
 - Frontend and backend communicate via REST API only
 - API base URL configured in frontend via `NEXT_PUBLIC_API_URL` environment variable
 - Shared types: define API contracts in backend Pydantic schemas, mirror in frontend TypeScript types
 - Never import between frontend and backend directories
 - Docker Compose orchestrates both services + PostgreSQL
 - Frontend runs on port 3000, backend on port 8000
-- Database owned by backend — frontend never accesses DB directly
+- Database owned by backend. Frontend never accesses DB directly
 - Authentication: NextAuth on frontend, JWT validation on backend
 - E2E tests in root `e2e/` directory test the full stack together
 
 ## Polyglot Pitfalls
-- Never import between `frontend/` and `backend/` — they are separate applications
+- Never import between `frontend/` and `backend/`. They are separate applications
 - Always define API contracts in backend Pydantic schemas first, then mirror in frontend TypeScript types
-- Always use `NEXT_PUBLIC_API_URL` for backend calls — never hardcode `localhost:8000`
-- Never run migrations from the frontend — database is owned by backend
+- Always use `NEXT_PUBLIC_API_URL` for backend calls. Never hardcode `localhost:8000`
+- Never run migrations from the frontend. Database is owned by backend
 - Never share `node_modules` or `__pycache__` between frontend and backend
 - Always test both services together with Docker Compose before deploying

package/templates/claude-code/claude-md/hono.md

@@ -0,0 +1,18 @@
+## Hono Conventions
+- Hono app with typed routes. Use `c.json()` for responses, `c.req.json()` for request bodies
+- Prisma client accessed via singleton (includes retry + graceful shutdown)
+- Route handlers in `src/routes/`. Each file exports a Hono instance mounted by `app.route()`
+- Use Hono middleware for CORS, auth, logging. Register with `app.use()`
+- Error responses via `app.onError()` global handler. Never leak stack traces
+- TypeScript strict mode. Use Zod for request validation
+- Environment variables via `process.env`. Validate required vars at startup
+- Build with `tsc`, run with `node dist/index.js`
+- Prisma for database: `npx prisma db push` for dev, `npx prisma migrate` for production
+
+## Hono Pitfalls
+- Never return raw strings from API endpoints. Always use `c.json()` with typed objects
+- Never use `app.onError()` to return stack traces. Log server-side, return generic error to client
+- Never hardcode ports. Always use `process.env.PORT` with a fallback
+- Never skip `c.req.valid()` for user input. Always validate with Zod middleware
+- Never use synchronous file I/O in route handlers. Use async operations
+- Never forget graceful shutdown. Register SIGTERM/SIGINT handlers to close server and DB

package/templates/claude-code/claude-md/nextjs.md

@@ -1,19 +1,19 @@
 ## Next.js Conventions
-- Use App Router (src/app/) — no pages/ directory
+- Use App Router (src/app/). No pages/ directory
 - Server Components by default; add 'use client' only when needed (event handlers, hooks, browser APIs)
 - Use server actions for mutations, not API routes
 - Colocate loading.tsx, error.tsx, not-found.tsx with page.tsx
 - Use `@/` path alias for imports from src/
-- Tailwind CSS for styling — use `cn()` from `@/lib/utils` for conditional classes
+- Tailwind CSS for styling. Use `cn()` from `@/lib/utils` for conditional classes
 - Prisma client accessed via `@/lib/db` singleton (includes retry + graceful shutdown)
 - Form validation with Zod schemas shared between client and server
 - Images via `next/image`, links via `next/link`
 - Environment variables: NEXT_PUBLIC_ prefix for client-side, plain for server-side
 
 ## Next.js Pitfalls
-- Never use `useEffect` for data fetching in Server Components — use `async` component functions
-- Never use `router.push()` when `<Link>` works — Link enables prefetching
+- Avoid Client Components with `useEffect` for data fetching. Prefer async Server Components instead
+- Never use `router.push()` when `<Link>` works. Link enables prefetching
 - Always add `loading.tsx` for pages with async data fetching
 - Never add `'use client'` unless the component actually uses browser APIs, event handlers, or hooks
-- Never use `fetch()` without error handling — always check `response.ok`
+- Never use `fetch()` without error handling. Always check `response.ok`
 - Never store server-only secrets in `NEXT_PUBLIC_` variables

package/templates/claude-code/claude-md/remix.md

@@ -0,0 +1,18 @@
+## Remix Conventions
+- File-based routing in `app/routes/`. Use Remix v2 flat route convention
+- Loaders for data fetching (`loader`), actions for mutations (`action`)
+- Use `useLoaderData()` and `useActionData()` for typed data access in components
+- Server-only code stays in loaders/actions and `.server.ts` files
+- Tailwind CSS for styling. Import styles in `app/root.tsx`
+- Prisma client accessed via singleton in `app/lib/db.server.ts`
+- Form submissions via `<Form>` component, not `fetch()`. Remix handles progressive enhancement
+- API resource routes in `app/routes/api.*.ts` for REST endpoints
+- Environment variables: server-side only by default. Use `loader` to pass to client
+
+## Remix Pitfalls
+- Never use `useEffect` for data fetching. Use `loader` functions instead
+- Never import server-only modules (Prisma, fs) in client components. Use `.server.ts` suffix
+- Never use `fetch()` for mutations when `<Form>` works. Form enables progressive enhancement
+- Never skip error boundaries. Add `ErrorBoundary` exports to route modules
+- Never use `redirect()` outside loaders/actions. It only works in server context
+- Never access `process.env` in client code. Pass values through `loader` data

package/templates/claude-code/commands/audit-security.md

@@ -1,5 +1,19 @@
 Run a focused security audit on all changed files.
 
+## Intent Contract
+
+Before invoking any agent, construct this block and pass it as context:
+
+```
+INTENT_CONTRACT:
+  INTENT: "[User's original request verbatim]"
+  SCOPE: "[Files/areas to examine]"
+  SUCCESS_CRITERIA: "[What done looks like]"
+  INTENT_HASH: "[First 8 chars of SHA256(INTENT|SCOPE|SUCCESS_CRITERIA)]"
+```
+
+Every agent invocation MUST include this block. If an agent's output does not echo back the INTENT_HASH, its results are considered unverified.
+
 1. Get list of changed files: `git diff --name-only`
 2. Launch the security-reviewer agent on those files
 3. Additionally check:

package/templates/claude-code/commands/audit-spec.md

@@ -1,5 +1,19 @@
 Run the spec-validator agent against the specification.
 
+## Intent Contract
+
+Before invoking any agent, construct this block and pass it as context:
+
+```
+INTENT_CONTRACT:
+  INTENT: "[User's original request verbatim]"
+  SCOPE: "[Files/areas to examine]"
+  SUCCESS_CRITERIA: "[What done looks like]"
+  INTENT_HASH: "[First 8 chars of SHA256(INTENT|SCOPE|SUCCESS_CRITERIA)]"
+```
+
+Every agent invocation MUST include this block. If an agent's output does not echo back the INTENT_HASH, its results are considered unverified.
+
 1. Find spec files in `docs/` (look for files with "spec", "requirements", or "PRD" in the name)
 2. If no spec found, ask the user to provide the spec file path
 3. Launch the spec-validator agent with the spec file

package/templates/claude-code/commands/audit-wiring.md

@@ -1,5 +1,19 @@
 Verify that all API endpoints are properly wired between frontend and backend.
 
+## Intent Contract
+
+Before invoking any agent, construct this block and pass it as context:
+
+```
+INTENT_CONTRACT:
+  INTENT: "[User's original request verbatim]"
+  SCOPE: "[Files/areas to examine]"
+  SUCCESS_CRITERIA: "[What done looks like]"
+  INTENT_HASH: "[First 8 chars of SHA256(INTENT|SCOPE|SUCCESS_CRITERIA)]"
+```
+
+Every agent invocation MUST include this block. If an agent's output does not echo back the INTENT_HASH, its results are considered unverified.
+
 1. Find all backend API endpoints (route handlers, FastAPI routers)
 2. Find all frontend API calls (fetch, axios, server actions)
 3. Cross-reference: every backend endpoint should have at least one frontend caller

package/templates/claude-code/commands/build-fix.md

@@ -1,5 +1,19 @@
 Incrementally fix build, lint, and type errors with minimal, safe changes.
 
+## Intent Contract
+
+Before invoking any agent, construct this block and pass it as context:
+
+```
+INTENT_CONTRACT:
+  INTENT: "[User's original request verbatim]"
+  SCOPE: "[Files/areas to examine]"
+  SUCCESS_CRITERIA: "[What done looks like]"
+  INTENT_HASH: "[First 8 chars of SHA256(INTENT|SCOPE|SUCCESS_CRITERIA)]"
+```
+
+Every agent invocation MUST include this block. If an agent's output does not echo back the INTENT_HASH, its results are considered unverified.
+
 ## Step 1: Detect and Run Build
 
 Run the build and capture errors:
@@ -41,3 +55,17 @@ Show results:
 - Suggested next steps for unresolved issues
 
 Fix one error at a time. Prefer minimal diffs over refactoring.
+
+## Step 6: Recommend Next Step
+
+After the fix summary, always recommend the single best next action. Evaluate in this order:
+
+1. **Remaining errors** — if any build/lint/type errors remain, recommend the specific fix
+2. **Test gaps** — if the fix touched untested code, recommend writing tests
+3. **Security review** — if the fix touched auth, input handling, or API routes, recommend `/audit-security`
+4. **Code review** — if significant logic changed, recommend `/code-review`
+5. **UAT impact** — if the fix affects user-facing behavior, flag which UAT scenarios need re-verification
+6. **Performance** — if the fix introduced new queries, loops, or async patterns, flag for perf review
+7. **All clean** — if everything passes, recommend `/pre-pr` or the next feature to build
+
+Format: **Next step:** one sentence with the specific command or action to take.

package/templates/claude-code/commands/build-ui.md

@@ -0,0 +1,59 @@
+Build frontend UI components using AI-powered generation with Google Stitch and UI UX Pro Max design intelligence.
+
+## Intent Contract
+
+Before invoking any agent, construct this block and pass it as context:
+
+```
+INTENT_CONTRACT:
+  INTENT: "[User's original request - e.g., 'Build a login page with social auth buttons']"
+  SCOPE: "[Components to generate, target directory, framework]"
+  SUCCESS_CRITERIA: "[Component renders, matches design system, user accepts preview]"
+  INTENT_HASH: "[First 8 chars of SHA256(INTENT|SCOPE|SUCCESS_CRITERIA)]"
+```
+
+## Step 1: Gather Requirements
+
+Ask the user (if not already specified):
+1. **What to build**: page, component, section, layout?
+2. **Functionality**: what does it do?
+3. **Style preference**: any aesthetic direction? (minimal, bold, playful, corporate, etc.)
+
+Detect automatically:
+- Project framework (check package.json, tsconfig, etc.)
+- Existing design system or component library
+- CSS approach (Tailwind, CSS Modules, styled-components)
+
+## Step 2: Launch Frontend Builder
+
+Invoke the **frontend-builder** agent with:
+- The user's request
+- Detected framework and conventions
+- The Intent Contract
+
+The agent will:
+1. Generate a design system (via UI UX Pro Max if available)
+2. Generate UI code (via Google Stitch if available, or manually)
+3. Preview the result for user approval
+4. Write accepted components to the project
+
+## Step 3: Post-Build Verification
+
+After the agent completes:
+1. Run the project's dev server if not already running
+2. Verify the component renders without console errors
+3. Check responsive layout (mobile, tablet, desktop)
+4. Run lint and type check to ensure no issues introduced
+
+## Quick Examples
+
+```
+# Generate a landing page
+/build-ui Create a SaaS landing page with hero, features grid, pricing table, and CTA
+
+# Generate a specific component
+/build-ui Build a data table component with sorting, filtering, and pagination
+
+# Generate with style direction
+/build-ui Build a dashboard sidebar with glassmorphism style and dark mode support
+```

package/templates/claude-code/commands/code-review.md

@@ -1,4 +1,20 @@
-Review uncommitted changes for security issues and code quality.
+Review uncommitted changes for security issues and code quality. This is the required review step before committing.
+
+The pre-commit gate will block commits until this review completes. After review, the commit will be allowed.
+
+## Intent Contract
+
+Before invoking any agent, construct this block and pass it as context:
+
+```
+INTENT_CONTRACT:
+  INTENT: "[User's original request verbatim]"
+  SCOPE: "[Files/areas to examine]"
+  SUCCESS_CRITERIA: "[What done looks like]"
+  INTENT_HASH: "[First 8 chars of SHA256(INTENT|SCOPE|SUCCESS_CRITERIA)]"
+```
+
+Every agent invocation MUST include this block. If an agent's output does not echo back the INTENT_HASH, its results are considered unverified.
 
 ## Step 1: Get Changed Files
 
@@ -6,39 +22,51 @@ Review uncommitted changes for security issues and code quality.
 git diff --name-only HEAD
 ```
 
-## Step 2: Review Each File
-
-For each changed file, check:
+If no changes, report "Nothing to review" and exit.
 
-**Security (CRITICAL):**
-- Hardcoded credentials, API keys, tokens
-- SQL injection vulnerabilities
-- XSS vulnerabilities
-- Missing input validation
-- Path traversal risks
+## Step 2: Launch Review Agents (in parallel)
 
-**Code Quality (HIGH):**
-- Functions > 50 lines
-- Files > 800 lines
-- Nesting depth > 4 levels
-- Missing error handling
-- console.log / print statements left in
-- TODO/FIXME comments without tracking
+Launch all three agents on the changed files:
 
-**Best Practices (MEDIUM):**
-- Missing tests for new code
-- Mutation of shared state (use immutable patterns)
-- Missing accessibility attributes (a11y)
+| Agent | Focus |
+|-------|-------|
+| `code-quality-reviewer` | Code patterns, complexity, maintainability, naming |
+| `security-reviewer` | Vulnerabilities, injection, credential exposure, input validation |
+| `deep-reviewer` | Behavioral integrity, runtime correctness, configuration validity, dependency quality, user-facing text, regression and scalability risks |
 
-## Step 3: Generate Report
+## Step 3: Collect and Report Findings
 
 For each issue found:
-- **Severity**: CRITICAL, HIGH, MEDIUM
+- **Severity**: CRITICAL, HIGH, MEDIUM, LOW
 - **File**: path and line number
 - **Issue**: what's wrong
 - **Fix**: how to fix it
+
 ## Step 4: Verdict
 
-- If CRITICAL issues found → block commit, list required fixes
-- If only MEDIUM/LOW → approve with suggestions
-- Never approve code with security vulnerabilities
+- If CRITICAL issues found: list required fixes, do NOT mark as reviewed
+- If HIGH issues found (no CRITICAL): strongly recommend fixes, mark as reviewed with warnings
+- If only MEDIUM/LOW: approve with suggestions, mark as reviewed
+
+## Step 5: Update Review Marker
+
+After review completes (with no CRITICAL findings), write the review marker so the pre-commit gate knows these files have been reviewed:
+
+```bash
+echo '{"files": [<list of reviewed files>], "timestamp": "<ISO timestamp>", "verdict": "<APPROVED|APPROVED_WITH_WARNINGS>"}' > .claude/.last-review
+```
+
+This marker is checked by the pre-commit gate. If new files are staged after review, the gate will require re-review.
+
+## Step 6: Recommend Next Step
+
+After the review, always recommend the single best next action:
+
+1. **CRITICAL fixes** — if any CRITICAL findings, recommend the specific fix with file:line
+2. **HIGH fixes** — if HIGH findings with clear fixes, recommend `/build-fix` or manual fix
+3. **Test coverage** — if reviewed code lacks tests, recommend writing tests for the specific functions
+4. **Security hardening** — if security findings exist, recommend `/audit-security` for a deeper pass
+5. **Ready to commit** — if review is clean, recommend committing with a suggested commit message
+6. **Ready for PR** — if already committed, recommend `/pre-pr`
+
+Format: **Next step:** one sentence with the specific command or action to take.

package/templates/claude-code/commands/fix-loop.md

@@ -0,0 +1,211 @@
+Run an automated fix-review-regression loop with enforcement gates until all tests pass, code is verified clean, and every agent's work is independently confirmed.
+
+## Intent Contract
+
+Before invoking any agent, construct this block and pass it as context:
+
+```
+INTENT_CONTRACT:
+  INTENT: "[User's original request verbatim]"
+  SCOPE: "[Files/areas to examine]"
+  SUCCESS_CRITERIA: "All tests pass, no lint/type errors, no CRITICAL or HIGH review findings, no regressions, all agents APPROVED by enforcement gate"
+  INTENT_HASH: "[First 8 chars of SHA256(INTENT|SCOPE|SUCCESS_CRITERIA)]"
+```
+
+Every agent invocation MUST include this block. If an agent's output does not echo back the INTENT_HASH, its results are considered unverified.
+
+## Enforcement Protocol
+
+**After every phase that involves an agent doing work**, invoke the `enforcement-gate` agent with:
+1. The Intent Contract
+2. The agent's full output (including PROOF_OF_INTENT)
+3. The baseline metrics from Phase 0
+
+**Gate rules:**
+- `APPROVED` (confidence >= 99.99%) → proceed to next phase
+- `NEEDS_REVIEW` (confidence 75-99.98%) → surface discrepancies to user, ask whether to proceed or halt
+- `REJECTED` (confidence < 75% OR false claim OR regression) → halt the loop, report what failed and why
+
+No phase transition happens without an APPROVED or explicit user override.
+
+## Phase 0: Baseline
+
+Run all checks and capture the starting state:
+
+```bash
+{{TEST_COMMAND}}
+{{LINT_COMMAND}}
+{{TYPE_CHECK_COMMAND}}
+```
+
+Record as structured baseline:
+```
+BASELINE:
+  TESTS: [total, passing, failing]
+  LINT_ERRORS: [count]
+  TYPE_ERRORS: [count]
+  TIMESTAMP: [ISO 8601]
+```
+
+If everything passes already, skip to Phase 2 (deep review only).
+
+## Phase 1: Fix (build-error-resolver agent)
+
+Delegate to the `build-error-resolver` agent with the Intent Contract:
+
+1. Group errors by file, sorted by dependency order
+2. Fix one error at a time with the smallest possible change
+3. Re-run all checks after each fix to confirm no regressions
+4. Continue until all errors are resolved
+
+**Stop conditions** (bail out and report to user):
+- Same error persists after 3 attempts
+- A fix introduces more errors than it resolves
+- Fix requires architectural changes beyond a simple repair
+- No progress across 2 consecutive iterations
+- Maximum 5 fix iterations reached
+
+### Enforcement Gate 1
+
+After build-error-resolver completes, invoke `enforcement-gate`:
+- Verify all claimed fixes are real (re-run `{{TEST_COMMAND}}`, `{{LINT_COMMAND}}`, `{{TYPE_CHECK_COMMAND}}`)
+- Verify no regressions against baseline
+- Verify scope coverage (did the agent touch only files it claimed?)
+
+If REJECTED → halt and report. If APPROVED → proceed to Phase 2.
+
+## Phase 2: Deep Review (deep-reviewer agent)
+
+Run `git diff` to capture all changes since baseline.
+
+Invoke the `deep-reviewer` agent with the Intent Contract and the full diff. The deep reviewer will:
+
+1. Read every changed hunk line-by-line
+2. Analyze for: correctness, security, data integrity, performance, edge cases, API contract, readability
+3. For each finding: exact file/line, severity, description, suggested fix, and a runnable test case
+4. Return structured findings with confidence scores
+
+### Triage Findings
+
+Categorize the deep reviewer's output:
+
+| Finding Type | Action |
+|-------------|--------|
+| CRITICAL with fix + test case | → Phase 3 (auto-fix) |
+| HIGH with fix + test case | → Phase 3 (auto-fix) |
+| CRITICAL/HIGH needing human judgment | → Halt loop, surface to user |
+| MEDIUM/LOW | → Collect for final report |
+| Confidence < 70% | → Collect for final report, mark as uncertain |
+
+## Phase 3: Fix Review Findings (build-error-resolver agent)
+
+For each CRITICAL/HIGH finding from Phase 2 that has an auto-fixable suggestion:
+
+1. Apply the suggested fix from the deep reviewer
+2. Run the test case the deep reviewer generated — it must pass
+3. Run `{{TEST_COMMAND}}` — all existing tests must still pass
+4. Move to next finding
+
+**Cap**: Maximum 2 iterations of fix-review. If findings keep appearing, halt and report.
+
+### Enforcement Gate 2
+
+After fixing review findings, invoke `enforcement-gate`:
+- Verify every applied fix resolves its finding
+- Verify all generated test cases pass
+- Verify no regressions against baseline
+- Verify the deep reviewer's test cases actually test what they claim
+
+If REJECTED → revert the fixes from this phase, report findings to user as manual tasks. If APPROVED → proceed to Phase 4.
+
+## Phase 4: Regression + New Test Validation
+
+Run the full test suite:
+
+```bash
+{{TEST_COMMAND}}
+```
+
+Compare against Phase 0 baseline:
+- If any previously passing test now fails → **REGRESSION DETECTED**
+  - Delegate to `build-error-resolver` to fix (max 2 iterations)
+  - Run through `enforcement-gate` again
+  - If regression persists after gate, halt and report
+- If test count decreased (tests were deleted) → flag as **WARNING**
+- If all tests pass and count is stable or increased → **GREEN**
+
+Then verify any new test cases generated by the deep reviewer:
+- Each test must target a specific finding
+- Each test must fail WITHOUT the fix and pass WITH the fix (if we can verify this)
+- Tests that pass regardless of the fix are flagged as `WEAK_TEST`
+
+### Enforcement Gate 3 (Final)
+
+Invoke `enforcement-gate` one last time on the entire session:
+- Re-run all checks from scratch: `{{TEST_COMMAND}}`, `{{LINT_COMMAND}}`, `{{TYPE_CHECK_COMMAND}}`
+- Verify final state against baseline (test count, pass rate, error counts)
+- Verify every agent's PROOF_OF_INTENT hash matches the original INTENT_HASH
+- Produce final confidence score
+
+If REJECTED → report what failed. If APPROVED → proceed to report.
+
+## Phase 5: Final Report
+
+```
+## Fix Loop Report
+
+**Baseline**: X tests (Y passing, Z failing), L lint errors, T type errors
+**Result**:   X tests (Y passing, Z failing), L lint errors, T type errors
+
+### Phase Results
+| Phase | Agent | Enforcement Verdict | Confidence |
+|-------|-------|-------------------|------------|
+| 1. Fix | build-error-resolver | APPROVED/REJECTED | XX% |
+| 2. Deep Review | deep-reviewer | N/A (read-only) | N/A |
+| 3. Fix Findings | build-error-resolver | APPROVED/REJECTED | XX% |
+| 4. Regression | enforcement-gate | APPROVED/REJECTED | XX% |
+
+### Deep Review Findings
+| ID | File:Line | Severity | Category | Status |
+|----|-----------|----------|----------|--------|
+| DR-001 | path:line | CRITICAL | Correctness | FIXED / DEFERRED / MANUAL |
+
+### Test Cases Generated
+| Finding | Test File | Status |
+|---------|-----------|--------|
+| DR-001 | path/to/test | PASSING / WEAK / FAILING |
+
+### Enforcement Audit Trail
+[For each gate: what was checked, what passed, what failed, confidence score]
+
+### Remaining Items (MEDIUM/LOW)
+[Non-blocking findings for user to address at their discretion]
+
+### Intent Verification Summary
+[Each agent's INTENT_MATCH status, any DRIFT_DETECTED flags]
+```
+
+## Guardrails
+
+- **Max total iterations across all phases**: 10 (prevents infinite loops)
+- **Regression tolerance**: 0 (no previously passing test may break)
+- **Review-fix cap**: 2 iterations (prevents review-fix ping-pong)
+- **Enforcement gates**: 3 mandatory (after Phase 1, after Phase 3, final)
+- **No phase transition without APPROVED or explicit user override**
+- Never suppress or skip a failing test to make the loop pass
+- Never mark a finding as resolved without the enforcement gate confirming it
+- If any phase halts, the report must still be generated with what was completed
+
+## Phase 6: Recommend Next Step
+
+After the final report, always recommend the single best next action:
+
+1. **Manual findings** — if CRITICAL/HIGH findings were deferred, recommend fixing them with specific file:line references
+2. **Weak tests** — if any generated test cases were flagged WEAK, recommend strengthening them
+3. **Security** — if changes touched auth, input handling, or API routes, recommend `/audit-security`
+4. **UAT** — if changes affect user-facing behavior, recommend `/run-uat` with specific scenarios
+5. **PR readiness** — if everything is green, recommend `/pre-pr`
+6. **Dependency check** — if the fix revealed outdated deps, recommend updating them
+7. **Architecture** — if fixes were workarounds, recommend the proper architectural fix
+
+Format: **Next step:** one sentence with the specific command or action to take.