forge-orkes 0.3.7 → 0.3.9

package/template/.claude/skills/reviewing/SKILL.md

@@ -0,0 +1,437 @@
+---
+name: reviewing
+description: "Use after verifying passes to assess codebase health and catalog improvement opportunities. Combines security audit (10 categories), architecture audit (4 dimensions), and refactoring scan (6 categories) into a single review pass. This is the pre-completion gate — it answers 'is this healthy enough to ship, and what could be better?'"
+---
+
+# Reviewing: Health Audit + Refactoring Review
+
+You are the pre-completion gate. After `verifying` confirms the work delivers what was promised, you assess codebase health AND catalog improvement opportunities in a single review pass. Three parallel scans — security, architecture, and refactoring — produce a structured report that determines whether the milestone can complete.
+
+## When to Trigger
+
+- **Automatically** after `verifying` returns a PASSED verdict (Standard and Full tiers)
+- **On-demand** at any time via user request
+
+## Process Overview
+
+1. Read project context (`.forge/project.yml`) to determine tech stack
+2. Scope the review — glob all source files, determine milestone diff
+3. Spawn three parallel subagents: Security Audit + Architecture Audit + Refactoring Scan
+4. Collect results, score per-category, determine overall status
+5. Write health report to `.forge/audits/milestone-{id}-health-report.md`
+6. Write accepted refactoring items to `.forge/refactor-backlog.yml`
+7. Route based on results: healthy → complete, critical issues → user decides
+
+## Step 1: Read Context
+
+```
+Read: .forge/project.yml → tech stack, framework, database, dependencies
+Read: .forge/state/milestone-{id}.yml → milestone ID and name
+Read: .forge/constitution.md → active architectural gates (if exists)
+Read: .forge/refactor-backlog.yml → existing backlog items (if any)
+```
+
+Determine which security categories apply based on the tech stack. For example:
+- No database → SQL/NoSQL Injection is N/A
+- No frontend → XSS Prevention is N/A
+- No CI/CD config → Pipeline Security is N/A
+
+Determine the milestone's starting point for the git diff (for refactoring scan):
+- Check git log for the commit tagged or noted as the milestone start
+- If unavailable, use the first commit after the previous milestone's completion date
+- Fallback: ask the user for the starting commit or branch
+
+## Step 2: Scope the Review
+
+```
+Glob: src/**/*.{ts,tsx,js,jsx,py,go,rs,java} (adapt to project language)
+Glob: **/*.env*, **/docker-compose*, **/.github/workflows/*
+Glob: **/next.config*, **/vite.config*, **/webpack.config*
+```
+
+Also get the diff file list for the refactoring scan:
+```
+git diff --name-only {milestone_start}..HEAD
+```
+
+Present scope summary to user:
+*"Review scope: {N} source files, {N} config files, {N} files changed in this milestone. Scanning security (10 categories), architecture (4 dimensions), and refactoring opportunities (6 categories). This will take a moment."*
+
+Build explicit file lists for each subagent — pass file paths, not globs, so nothing is missed.
+
+## Step 3: Spawn Parallel Scans
+
+Spawn all three scans as fresh-context subagents. Each receives the explicit file list for their scope, the tech stack from `project.yml`, and their specific instructions below.
+
+### Part 1: Security Audit (subagent)
+
+Spawn a security auditor agent with a fresh context window.
+
+**10 Security Categories:**
+
+| # | Category | What It Checks |
+|---|----------|---------------|
+| 1 | Authentication & Authorization | Every endpoint has auth middleware; role checks before data access |
+| 2 | Data Scoping / Tenant Isolation | Queries scoped to correct user/tenant; no cross-tenant data leaks |
+| 3 | Input Validation | Request bodies/params validated before use in queries or logic |
+| 4 | Error Information Leakage | No stack traces, DB schemas, or internal details in API responses |
+| 5 | XSS Prevention | No unsanitized user content injected into DOM |
+| 6 | SQL/NoSQL Injection | All queries use parameterized placeholders, no string interpolation |
+| 7 | Secrets Management | No hardcoded keys/tokens; `.env` in `.gitignore`; `process.env` usage |
+| 8 | CORS Policy | No wildcard `*` origins in production; appropriate method restrictions |
+| 9 | HTTP Security Headers | CSP, X-Frame-Options, HSTS, X-Content-Type-Options, Referrer-Policy |
+| 10 | CI/CD Pipeline Security | Secrets via secrets context, not hardcoded in workflow files |
+
+**Agent behavior rules:**
+- Read every file in the provided list. No sampling or skipping.
+- Every finding must have: file path, line number, what's wrong, severity, remediation.
+- Understand context before flagging — read surrounding code, check for middleware, wrappers, and higher-order protections.
+- Document intentionally public endpoints; don't flag them as vulnerabilities.
+- Severity is firm: `critical` = exploitable vulnerability, `warning` = defense-in-depth gap, `info` = observation.
+- Prefer false negatives over false positives — only flag what you're confident about.
+- Categories that don't apply to this project's stack → mark as N/A with brief explanation.
+
+**Project adaptation:** Adapt checks to the detected stack:
+- Express vs Next.js vs Fastify endpoint patterns
+- PostgreSQL vs MongoDB vs SQLite query patterns
+- GitHub Actions vs GitLab CI vs other CI systems
+- React vs Vue vs Svelte frontend patterns
+
+**Output format** (return to orchestrator):
+
+```yaml
+security_audit:
+  files_scanned: N
+  categories:
+    - id: 1
+      name: "Authentication & Authorization"
+      status: passed | warning | critical | na
+      findings:
+        - file: "src/api/users.ts"
+          line: 42
+          severity: critical | warning | info
+          issue: "Description of what's wrong"
+          remediation: "How to fix it"
+      notes: "Optional context about intentional decisions"
+```
+
+### Part 2: Architecture Audit (subagent)
+
+Spawn an architecture auditor agent with a fresh context window.
+
+**4 Architecture Dimensions:**
+
+| Dimension | What It Checks |
+|-----------|---------------|
+| **Scalability** | Synchronous blocking calls, missing pagination, unbounded queries, N+1 query patterns, missing caching opportunities, single points of failure, hardcoded limits |
+| **Maintainability** | Code complexity hotspots (files >300 lines, deeply nested logic >4 levels, god components/classes), circular dependencies, duplicated logic that warrants abstraction |
+| **Code Health** | Dead code / unused exports, TODO/FIXME inventory with age, test coverage gaps (untested critical paths), stale/vulnerable dependencies |
+| **Structural Quality** | Separation of concerns violations (business logic in UI layer), inconsistent patterns across similar features, missing error boundaries, API contract consistency |
+
+**Agent behavior rules:**
+- Check actual code, not theoretical concerns.
+- Every finding references specific files with evidence.
+- Severity: `critical` = architectural debt that will cause production issues or block future work, `warning` = quality concern worth addressing, `info` = improvement opportunity.
+- Respect existing ADRs in `.forge/decisions/` — don't flag intentional architectural choices as issues.
+- Respect constitutional articles in `.forge/constitution.md` — if the constitution permits a pattern, don't flag it.
+
+**Output format** (return to orchestrator):
+
+```yaml
+architecture_audit:
+  files_scanned: N
+  dimensions:
+    - name: "Scalability"
+      status: passed | warning | critical
+      findings:
+        - file: "src/api/products.ts"
+          line: 87
+          severity: critical | warning | info
+          issue: "Unbounded query with no pagination"
+          remediation: "Add limit/offset parameters"
+    - name: "Maintainability"
+      status: passed | warning | critical
+      findings: []
+    - name: "Code Health"
+      status: passed | warning | critical
+      findings: []
+    - name: "Structural Quality"
+      status: passed | warning | critical
+      findings: []
+```
+
+### Part 3: Refactoring Scan (subagent)
+
+Spawn a refactoring scanner agent with a fresh context window. Pass it only the files changed during the milestone (from the git diff).
+
+**6 Refactoring Categories:**
+
+| # | Category | What to Look For |
+|---|----------|-----------------|
+| 1 | **Duplication** | Similar logic in 2+ places that could be extracted into a shared function, hook, or utility |
+| 2 | **Complexity hotspots** | Functions >50 lines, nesting >3 levels deep, high cyclomatic complexity, overly long files |
+| 3 | **Naming & clarity** | Unclear variable/function names, misleading abstractions, functions that do more than their name suggests |
+| 4 | **Pattern inconsistency** | Same thing done differently across the milestone's files (e.g., error handling, data fetching, state management) |
+| 5 | **Dead code** | Unused functions, unreachable branches, commented-out code left behind, unused imports |
+| 6 | **Abstraction issues** | Over-engineered helpers used once, repeated inline code that warrants extraction, premature or missing abstractions |
+
+**Agent behavior rules:**
+- Read every file in the diff. No sampling.
+- Every finding must reference a specific file and line range.
+- Understand context — don't flag intentional patterns documented in the constitution.
+- Don't duplicate findings from the security or architecture audits.
+- Estimate effort for each item: `quick` (< 30 min, under 50 lines) or `standard` (needs planning).
+- Suggest a concrete approach for each finding, not just "refactor this."
+- Prefer fewer high-quality findings over many low-signal ones.
+
+**Output format** (return to orchestrator):
+
+```yaml
+refactoring_scan:
+  files_scanned: N
+  findings:
+    - category: duplication
+      file: "src/api/users.ts"
+      lines: "42-67"
+      description: "Duplicate validation logic — same email check in createUser and updateUser"
+      effort: quick
+      suggested_approach: "Extract shared validateEmail() helper to src/utils/validation.ts"
+```
+
+## Step 4: Score Results
+
+After all three subagents return, compute scores.
+
+**Per-category scoring (security + architecture):**
+
+| Status | Meaning |
+|--------|---------|
+| `passed` | No issues found |
+| `warning` | Non-critical issues (info-level also maps here) |
+| `critical` | Real vulnerabilities or architectural blockers |
+| `na` | Category doesn't apply to this project |
+
+**Overall health status:**
+
+| Overall | Condition |
+|---------|-----------|
+| `passed` | ALL categories and dimensions passed or N/A |
+| `warnings_only` | One or more warnings, zero critical |
+| `issues_found` | One or more critical findings |
+
+**Refactoring findings** are separate from the health status — they never block completion.
+
+## Step 5: Write Health Report
+
+Create `.forge/audits/` directory if needed. Write to `.forge/audits/milestone-{id}-health-report.md`.
+
+**YAML frontmatter:**
+
+```yaml
+---
+milestone_id: {id}
+milestone_name: "{name}"
+reviewed: "{ISO 8601 timestamp}"
+status: passed | warnings_only | issues_found
+security:
+  status: passed | warnings_only | issues_found
+  categories_passed: N
+  categories_warning: N
+  categories_critical: N
+  categories_na: N
+architecture:
+  status: passed | warnings_only | issues_found
+  scalability: passed | warning | critical
+  maintainability: passed | warning | critical
+  code_health: passed | warning | critical
+  structural_quality: passed | warning | critical
+refactoring:
+  findings_count: N
+  quick_count: N
+  standard_count: N
+total_files_scanned: N
+---
+```
+
+**Body structure:**
+
+```markdown
+# Review Report: {milestone name}
+
+## Executive Summary
+{1-3 sentences: overall health assessment, key findings, refactoring highlights, recommendation}
+
+## Security Findings
+
+### Category 1: Authentication & Authorization — {STATUS}
+| File | Line | Severity | Issue | Remediation |
+|------|------|----------|-------|-------------|
+| ... | ... | ... | ... | ... |
+
+{Repeat for each category. N/A categories get a single line: "N/A — {reason}"}
+
+## Architecture Findings
+
+### Scalability — {STATUS}
+| File | Line | Severity | Issue | Remediation |
+|------|------|----------|-------|-------------|
+| ... | ... | ... | ... | ... |
+
+{Repeat for each dimension}
+
+## Refactoring Opportunities
+
+### Duplication ({N} items)
+| File | Lines | Description | Effort | Approach |
+|------|-------|-------------|--------|----------|
+| ... | ... | ... | quick/standard | ... |
+
+{Repeat for each refactoring category with findings}
+
+## Public Endpoints
+{List of intentionally public endpoints documented during security audit}
+
+## Files Scanned
+{Count and list of all files scanned across all three scans}
+```
+
+**Health trend tracking:** If a previous audit exists for an earlier milestone (check `.forge/audits/` for prior reports), compare results and note improvements or regressions in the executive summary.
+
+## Step 6: Present Results + Triage Refactoring
+
+### Health Results
+
+Present the health status first — this is the gate.
+
+**If HEALTHY (all passed):**
+*"Health audit passed. No security vulnerabilities or architectural concerns found."*
+
+**If NEEDS ATTENTION (critical issues):**
+*"Review found critical issues that should be addressed before shipping:"*
+Inline the top 3 findings per critical category so the user sees them immediately.
+
+**If WARNINGS ONLY:**
+*"Review passed with warnings — no critical issues, but {N} items worth noting. See the full report at `.forge/audits/milestone-{id}-health-report.md`."*
+
+### Refactoring Triage
+
+After presenting health results, show refactoring findings for triage. Group by category, max 10 initially:
+
+*"I also found {N} refactoring opportunities in the code built during this milestone:"*
+
+For each category with findings:
+*"**Duplication** ({N} items):*
+*1. `src/api/users.ts:42-67` — Duplicate email validation in createUser and updateUser. Quick fix: extract shared helper. [Accept / Dismiss]*
+*2. ...*"
+
+The user can respond with:
+- **Accept** (individual item) → add to backlog
+- **Dismiss** (individual item) → skip, not a real issue or intentional
+- **Accept all** → bulk add all remaining items to backlog
+- **Dismiss all** → skip everything, no backlog items added
+
+For dismissed items, optionally ask for a brief reason (helps calibrate future scans).
+
+## Step 7: Write Backlog + Route
+
+### Write Refactoring Backlog
+
+Read existing `.forge/refactor-backlog.yml` (if any). Determine the next item ID by incrementing from the highest existing ID.
+
+Append accepted items to `.forge/refactor-backlog.yml`:
+
+```yaml
+items:
+  - id: R001
+    milestone: 1
+    category: duplication
+    file: "src/api/users.ts"
+    lines: "42-67"
+    description: "Duplicate validation logic — same email check in createUser and updateUser"
+    effort: quick
+    suggested_approach: "Extract shared validateEmail() helper"
+    status: pending
+    added: "2026-03-18"
+    completed: null
+```
+
+If the file doesn't exist yet, create it from the template at `.forge/templates/refactor-backlog.yml`.
+
+### Route Based on Health Status
+
+#### HEALTHY or WARNINGS ONLY (user accepts)
+
+Update `.forge/state/milestone-{id}.yml`:
+- Set `current.status` to `complete`
+
+Update `.forge/state/index.yml`:
+- Set milestone status to `complete`
+- Update `last_updated` timestamp
+
+Present to user:
+*"Milestone [{name}] is complete. {N} refactoring items are in the backlog for whenever you want to tackle them."*
+
+If Beads is installed, run `bd complete` to update the dependency graph.
+
+#### NEEDS ATTENTION (critical issues found)
+
+Do NOT mark milestone complete. Present choices:
+
+*"Options:"*
+- **A. Fix critical issues** — return to `planning` in fix mode with findings as requirements
+- **B. Accept risk and continue** — document accepted risks in report, complete the milestone
+
+If user chooses A:
+- Create fix requirements from critical findings
+- Route to `planning` skill in fix mode
+- After fix execution + re-verification, re-run `reviewing` (not full verification — just this review)
+
+If user chooses B:
+- Append "Accepted Risks" section to the health report with user's acknowledgment
+- Complete the milestone (same as HEALTHY path above)
+
+#### WARNINGS ONLY (user wants to fix)
+
+If user wants to fix warnings instead of accepting:
+- Create fix requirements from warning findings
+- Route to `planning` in fix mode
+- After fix execution, re-run `reviewing`
+
+## Gate Type: Mixed
+
+- **Security critical findings** → soft gate (user can accept risk, but strongly recommended to fix)
+- **Architecture critical findings** → soft gate (same — user has final authority)
+- **Warnings** → advisory (noted in report, user chooses)
+- **Refactoring items** → never block (cataloged to backlog for future work)
+
+The report documents the decision either way, creating an audit trail.
+
+## Backlog Lifecycle
+
+Backlog items follow this lifecycle:
+
+```
+pending → in_progress → done
+pending → dismissed (during triage or later review)
+```
+
+Items with `effort: quick` can be picked up directly via `quick-tasking`.
+Items with `effort: standard` should go through the Standard tier flow.
+
+When working a backlog item:
+1. `forge` surfaces it as an available task
+2. User selects it
+3. Route to `quick-tasking` or Standard tier based on effort
+4. On completion, update the item's `status` to `done` and set `completed` date
+
+## Phase Handoff
+
+After reviewing completes (all paths: HEALTHY, accepted risk, accepted warnings):
+
+1. **Verify persistence** — Confirm health report is written to `.forge/audits/milestone-{id}-health-report.md` and refactoring backlog is updated
+2. **Update state** — Set `current.status` to `complete` in `.forge/state/milestone-{id}.yml`
+3. **Present completion:**
+
+*"Milestone [{name}] complete. Review report at `.forge/audits/milestone-{id}-health-report.md`. {N} refactoring items in backlog.*
+
+*Start new work with `/forge` or tackle backlog items anytime."*

package/template/.claude/skills/verifying/SKILL.md

@@ -128,7 +128,7 @@ Based on all verification levels:
 
 ### PASSED
 All truths verified, all artifacts substantive and wired, all key links connected, requirements covered.
-→ Route to `auditing` skill for health audit before milestone completion.
+→ Route to `reviewing` skill for health audit + refactoring review before milestone completion.
 
 ### GAPS FOUND
 Some truths failed or artifacts are stubs.
@@ -219,10 +219,10 @@ Only suggest changes when there's clear evidence (3+ occurrences). One-off issue
 After verification completes with a PASSED verdict:
 
 1. **Verify persistence** — Confirm verification results are documented, desire paths retrospective is logged to `.forge/state/index.yml`
-2. **Update state** — Set `current.status` to `auditing` in `.forge/state/milestone-{id}.yml`
+2. **Update state** — Set `current.status` to `reviewing` in `.forge/state/milestone-{id}.yml`
 3. **Recommend context clear:**
 
-*"Verification phase complete — all truths verified, artifacts substantive and wired. I recommend clearing context (`/clear`) before the health audit — the auditing skill spawns fresh subagents anyway, and a clean orchestrator context ensures nothing is missed.*
+*"Verification phase complete — all truths verified, artifacts substantive and wired. I recommend clearing context (`/clear`) before the review — the reviewing skill spawns fresh subagents anyway, and a clean orchestrator context ensures nothing is missed.*
 
 *Ready to continue? Clear context and invoke `/forge` to resume."*
 

package/template/.forge/templates/project.yml

@@ -30,6 +30,17 @@ constraints:
     - ""                            # e.g., "No custom auth — use Clerk"
     - ""                            # e.g., "No server-side rendering"
 
+verification:
+  commands:                           # Shell commands run after each task commit
+    - ""                              # e.g., "npm run lint"
+    - ""                              # e.g., "npm test"
+    - ""                              # e.g., "npx tsc --noEmit"
+  auto_fix: true                      # On failure, agent fixes and retries
+  max_retries: 2                      # Max auto-fix attempts per command (0 = fail immediately)
+  # Commands are auto-detected during init from package.json scripts.
+  # Advisory mode: commands that were already failing before Forge started
+  # run but don't block — they log warnings only.
+
 success_criteria:                   # How do we know we're done?
   - ""                              # e.g., "User can create and edit posts"
   - ""                              # e.g., "All tests pass with >80% coverage"

package/template/CLAUDE.md

@@ -29,11 +29,11 @@ Forge auto-detects complexity. Override with: "Use Quick/Standard/Full tier."
 
 ### Standard (hours)
 **Triggers:** new feature, component, significant refactor, multi-file change
-**Flow:** → `researching` → `discussing` → `planning` → `executing` → `verifying` → `auditing` → `refactoring` → done
+**Flow:** → `researching` → `discussing` → `planning` → `executing` → `verifying` → `reviewing` → done
 
 ### Full (days)
 **Triggers:** new project, major milestone, complex multi-system feature, architectural decisions needed
-**Flow:** → `researching` → `discussing` → `architecting` → `planning` → `executing` → `verifying` → `auditing` → `refactoring` → done
+**Flow:** → `researching` → `discussing` → `architecting` → `planning` → `executing` → `verifying` → `reviewing` → done
 **Optional additions:** `designing` (UI work), `securing` (auth/data/API), `debugging` (stuck on issue)
 
 ## Skill Routing
@@ -48,8 +48,7 @@ Forge auto-detects complexity. Override with: "Use Quick/Standard/Full tier."
 | Break work into executable tasks with gates | `planning` | Standard, Full |
 | Build code with deviation rules + atomic commits | `executing` | All |
 | Prove work actually delivers on goals | `verifying` | Standard, Full |
-| Audit application health before shipping | `auditing` | Standard, Full |
-| Review refactoring opportunities after milestone audit | `refactoring` | Standard, Full |
+| Audit health + catalog refactoring opportunities | `reviewing` | Standard, Full |
 | Fix a small, scoped issue fast | `quick-tasking` | Quick |
 | Build UI with design system consistency | `designing` | When UI involved |
 | Review security before shipping | `securing` | When auth/data/API involved |
@@ -71,7 +70,7 @@ Forge auto-detects complexity. Override with: "Use Quick/Standard/Full tier."
 When a task touches 20+ files or a complex subsystem, spawn a fresh executor agent with isolated context. This prevents context rot — the #1 cause of quality degradation in long sessions.
 
 ### Context Handoff Between Phases
-Each phase writes its outputs to `.forge/` before completing. At every phase boundary (researching → discussing → planning → executing → verifying → auditing → refactoring), the completing skill recommends clearing context (`/clear`) before the next phase begins. The next phase loads what it needs from disk. This is advisory — skip for short phases where context is under 40%. See the `forge` skill's "Context Handoff Protocol" for full details.
+Each phase writes its outputs to `.forge/` before completing. At every phase boundary (researching → discussing → planning → executing → verifying → reviewing), the completing skill recommends clearing context (`/clear`) before the next phase begins. The next phase loads what it needs from disk. This is advisory — skip for short phases where context is under 40%. See the `forge` skill's "Context Handoff Protocol" for full details.
 
 ### Lazy Loading
 Skills load only when invoked. CLAUDE.md stays in context; skill details load on demand. This keeps base context lean (~300 lines) while making full framework available.
@@ -84,9 +83,7 @@ Skills load only when invoked. CLAUDE.md stays in context; skill details load on
 | `planner` | Planning with constitutional gates | Read + Write (plan files only) | Planning phases |
 | `executor` | Building with deviation rules | All dev tools | Execution phases |
 | `verifier` | Goal-backward verification | Read + Bash (test execution) | Verification phases |
-| `security-auditor` | Security vulnerability scanner | Read, Bash, Grep, Glob | Auditing phase |
-| `architecture-auditor` | Structural health assessor | Read, Grep, Glob | Auditing phase |
-| `reviewer` | Security + code quality audit | Read-only + npm audit | Before shipping |
+| `reviewer` | Security + architecture + refactoring audit | Read, Bash, Grep, Glob | Reviewing phase |
 
 ## Project Init (First Run)
 
@@ -115,7 +112,7 @@ For Quick tier tasks, init is skipped — just do the work.
 ## State Management
 
 Project state lives in `.forge/`:
-- `project.yml` — Vision, stack, design system, constraints (< 5 KB)
+- `project.yml` — Vision, stack, design system, verification commands, constraints (< 5 KB)
 - `constitution.md` — Active architectural gates (selected during init)
 - `design-system.md` — Component mapping table (generated during init)
 - `requirements.yml` — Structured requirements with `[NEEDS CLARIFICATION]` markers
@@ -124,7 +121,7 @@ Project state lives in `.forge/`:
 - `state/milestone-{id}.yml` — Per-milestone cursor: current position, progress, decisions, blockers, deviations
 - `context.md` — Locked user decisions + deferred ideas (created during discuss phase)
 - `plan.md` — Per-phase task plans with must_haves frontmatter
-- `refactor-backlog.yml` — Refactoring opportunities cataloged after milestone audits, worked via quick-tasking
+- `refactor-backlog.yml` — Refactoring opportunities cataloged during milestone reviews, worked via quick-tasking
 
 ### Milestones
 Milestones group phases into concurrent work streams. Each milestone has its own state file, so different sessions can work on different milestones without conflicts. On resume, Forge shows active milestones and asks which one to work on.
@@ -133,7 +130,7 @@ Milestones group phases into concurrent work streams. Each milestone has its own
 YAML for anything agents parse programmatically (project, requirements, roadmap, state). Markdown for human-facing content (constitution, context, verification reports). Never free-form prose for machine state.
 
 ### Milestone Completion: Status vs. Percentage
-**`current.status` is the authoritative workflow position.** A milestone is only complete when `current.status == complete`. The `progress.overall_percent` field measures task completion — not workflow completion. A milestone at 100% task completion still needs verifying, auditing, and refactoring before it is done. On resume, always check and display `current.status` to determine next steps.
+**`current.status` is the authoritative workflow position.** A milestone is only complete when `current.status == complete`. The `progress.overall_percent` field measures task completion — not workflow completion. A milestone at 100% task completion still needs verifying and reviewing before it is done. On resume, always check and display `current.status` to determine next steps.
 
 ## Deviation Rules (Executor Decision Tree)
 
@@ -146,6 +143,27 @@ When the executor encounters issues during building:
 
 Priority: Rule 4 first (stop if architectural). Then Rules 1-3 (auto-fix). Uncertain? → Rule 4 (ask).
 
+## Verification Gates
+
+After each task commit, the executor runs configured verification commands from `project.yml`:
+
+```yaml
+verification:
+  commands:
+    - cmd: "npm run lint"
+    - cmd: "npm test"
+    - cmd: "npx tsc --noEmit"
+      advisory: true           # pre-existing failures — warn only
+  auto_fix: true               # agent fixes and retries on failure
+  max_retries: 2               # max auto-fix attempts per command
+```
+
+- **Auto-detected during init** from `package.json` scripts (test, lint, typecheck)
+- **Advisory mode**: commands that were already failing before Forge started run but don't block
+- **Auto-fix loop**: on failure, agent reads output, fixes code, amends commit, re-runs (up to max_retries)
+- **3-strike integration**: verification retries count toward the task's 3-strike limit
+- Empty `commands` list = no verification gate (opt-out)
+
 ## Beads Integration (Optional)
 
 When Beads is installed, Forge gains persistent cross-session memory: