forge-orkes 0.3.8 → 0.3.10

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

@@ -1,86 +1,69 @@
 ---
 name: verifying
-description: "Use when work is complete and you need to prove it actually works. Trigger after execution: does the code meet original requirements? Not 'did we complete tasks' but 'does it work?' This skill enforces goal-backward verification with 3 levels: Observable Truths, Artifacts, and Key Links."
+description: "Prove completed work delivers what was promised. Goal-backward verification with 3 levels: Observable Truths, Artifacts, and Key Links. Task completion ≠ goal achievement."
 ---
 
 # Verifying
 
-Prove completed work actually delivers what was promised. Task completion ≠ goal achievement.
+Prove completed work delivers what was promised. Task completion ≠ goal achievement.
 
 ## Core Question
 
-Don't ask: "Did we complete all the tasks?"
-Ask: "Does the user get what they were promised?"
+Not "Did we complete all tasks?" but "Does the user get what they were promised?"
 
 ## Load Context
 
-When entering with a fresh context (after `/clear`):
+After `/clear`, load with fresh eyes — don't carry the executor's assumptions:
 
 ```
 Read: .forge/state/milestone-{id}.yml → current phase, plans completed
 Read: .forge/project.yml → tech stack (for running tests)
 Read: .forge/phases/m{M}-{N}-{name}/plan-{NN}.md → must_haves (truths, artifacts, key_links)
-Read: .forge/context.md → locked decisions (to understand intent)
+Read: .forge/context.md → locked decisions
 Read: .forge/requirements.yml → requirement IDs for coverage check
 ```
 
-This is critical — the verifier should assess the code with fresh eyes, not carry the executor's assumptions. Load must_haves from the plan files and verify against the actual codebase.
-
 ## 3-Level Goal-Backward Verification
 
 ### Level 1: Observable Truths
 
 Read the plan's `must_haves.truths`. For each truth:
 
-1. Design a test (automated or manual) that proves/disproves it
+1. Design a test that proves/disproves it
 2. Run the test
-3. Record result: **VERIFIED** | **FAILED** | **UNCERTAIN**
+3. Record: **VERIFIED** | **FAILED** | **UNCERTAIN**
 
 ```markdown
 | Truth | Test | Result |
 |-------|------|--------|
-| User can see their profile | Navigate to /profile, check render | VERIFIED |
-| User can edit their bio | Click edit, type, save, verify persistence | VERIFIED |
-| Profile photo uploads correctly | Upload image, check display | FAILED — 413 error on large files |
+| User can edit their bio | Click edit, type, save, check persistence | VERIFIED |
+| Profile photo uploads correctly | Upload image, check display | FAILED — 413 on large files |
 ```
 
 ### Level 2: Artifacts (Exists → Substantive → Wired)
 
-Read the plan's `must_haves.artifacts`. For each artifact:
+Read the plan's `must_haves.artifacts`. For each:
 
 | Check | Question | Pass Criteria |
 |-------|----------|---------------|
-| **Exists** | Does the file exist? | File present at specified path |
-| **Substantive** | Is it real code, not a stub? | Exceeds min_lines, no placeholder text, real logic |
-| **Wired** | Is it imported and used by other code? | Has importers, called in production paths |
+| **Exists** | Does the file exist? | Present at specified path |
+| **Substantive** | Real code, not a stub? | Exceeds min_lines, no placeholders, real logic |
+| **Wired** | Imported and used? | Has importers, called in production paths |
 
 ```markdown
 | Artifact | Exists | Substantive | Wired | Status |
 |----------|--------|-------------|-------|--------|
 | src/components/Profile.tsx | ✓ | ✓ (87 lines) | ✓ (imported in routes) | VERIFIED |
-| src/api/users/[id].ts | ✓ | ✓ (43 lines) | ✓ (called by Profile) | VERIFIED |
 | src/hooks/useProfile.ts | ✓ | ✗ (returns {}) | - | STUB |
 ```
 
 ### Stub Detection Red Flags
 
-Watch for these patterns that indicate stubs, not real implementations:
-
-**React components:**
-- `<div>Component</div>` or `<div>Placeholder</div>`
-- `onClick={() => {}}` (empty handler)
-- `onChange={() => console.log()}` (logging-only handler)
-- Hardcoded data instead of API calls
+**React components:** `<div>Placeholder</div>`, `onClick={() => {}}`, `onChange={() => console.log()}`, hardcoded data instead of API calls
 
-**API endpoints:**
-- `return Response.json({ message: "Not implemented" })`
-- Empty arrays without database queries
-- TODO comments in response path
+**API endpoints:** `return Response.json({ message: "Not implemented" })`, empty arrays without DB queries, TODO in response path
 
-**Wiring:**
-- `fetch()` without await/then
-- Query without returning result
-- Form with only `preventDefault`
+**Wiring:** `fetch()` without await/then, query without returning result, form with only `preventDefault`
 
 ### Level 3: Key Links
 
@@ -88,8 +71,8 @@ Read the plan's `must_haves.key_links`. Verify each connection:
 
 | Pattern | How to Verify |
 |---------|---------------|
-| Component → API | Find fetch/axios call in component pointing to API route |
-| API → Database | Find ORM/query call in API handler returning data |
+| Component → API | Find fetch/axios call pointing to API route |
+| API → Database | Find ORM/query call returning data |
 | Form → Handler | Find onSubmit with API call and response handling |
 | State → Render | Find state variable used in JSX (not just declared) |
 
@@ -97,12 +80,11 @@ Read the plan's `must_haves.key_links`. Verify each connection:
 | From | To | Via | Pattern | Status |
 |------|----|-----|---------|--------|
 | Profile.tsx | /api/users/[id] | fetch in useEffect | fetch.*api/users | VERIFIED |
-| ProfileForm.tsx | /api/users/[id] | PUT on submit | method.*PUT | VERIFIED |
 ```
 
 ## Anti-Pattern Scan
 
-After 3-level verification, scan for common issues:
+After 3-level verification:
 
 - [ ] No `TODO` or `FIXME` in production code paths
 - [ ] No `console.log` as error handling
@@ -112,27 +94,24 @@ After 3-level verification, scan for common issues:
 
 ## Requirements Coverage
 
-Cross-reference verified work against `.forge/requirements.yml`:
+Cross-reference against `.forge/requirements.yml`:
 
 ```markdown
 | Requirement | Status | Evidence |
 |-------------|--------|----------|
 | FR-001 | Verified | Profile renders, tests pass |
-| FR-002 | Verified | Edit flow works end-to-end |
 | FR-003 | Partial | Upload works for small files, fails > 5MB |
 ```
 
 ## Verdict
 
-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.
 
 ### GAPS FOUND
 Some truths failed or artifacts are stubs.
-→ Document gaps in YAML format:
+→ Document gaps:
 
 ```yaml
 gaps:
@@ -150,8 +129,8 @@ gaps:
 → Return to `planning` skill in gap-closure mode.
 
 ### HUMAN VERIFICATION NEEDED
-Some items can't be verified automatically (visual appearance, real-time behavior, external service integration).
-→ List items for user to verify manually:
+Items that can't be verified automatically (visual appearance, real-time behavior, external services).
+→ List for manual check:
 
 ```markdown
 ## Human Verification Items
@@ -162,68 +141,61 @@ Some items can't be verified automatically (visual appearance, real-time behavio
 
 ## Re-Verification Mode
 
-When re-verifying after gap closure:
+After gap closure:
 1. Load previous verification results
 2. Full 3-level check on previously failed items
-3. Quick regression check on previously passed items (exists + basic sanity)
-4. Merge results and issue updated verdict
+3. Quick regression check on passed items (exists + basic sanity)
+4. Merge results, issue updated verdict
 
 ## Desire Paths Retrospective
 
-After completing verification (PASSED or GAPS FOUND), do a quick retrospective on framework usage patterns. This takes 1-2 minutes and feeds the framework's self-improvement loop.
+After verification completes (PASSED or GAPS FOUND), run a quick retrospective on framework usage patterns. Update `.forge/state/index.yml → desire_paths` (global, not per-milestone).
 
 ### Collect Signals
 
-Review the current session and update `.forge/state/index.yml → desire_paths` (desire paths are global, not per-milestone):
+**1. Deviation patterns**: Read `.forge/state/milestone-{id}.yml → deviations`. Repeating?
+- Same Rule 1 fix in multiple places → plan template should include this check
+- Same Rule 2 addition everywhere → constitution needs a new article
+- Same Rule 3 issue → project setup is missing something
 
-**1. Deviation patterns**: Read `.forge/state/milestone-{id}.yml → deviations` from this session. Are any repeating?
-- Same Rule 1 fix in multiple places → maybe the plan template should include this check
-- Same Rule 2 addition everywhere → maybe the constitution needs a new article
-- Same Rule 3 issue → maybe the project setup is missing something
+**2. Tier overrides**: User override tier detection? Log detected vs. chosen. Repeated overrides = wrong heuristics.
 
-**2. Tier overrides**: Did the user override tier detection this session? Log what was detected vs. chosen. Repeated overrides mean the detection heuristics are wrong.
+**3. Skipped steps**: User ask to skip workflow steps? Repeated skips = friction without value.
 
-**3. Skipped steps**: Did the user ask to skip any workflow steps? (e.g., "skip the constitution check", "don't need a full research phase"). Repeated skips mean the step adds friction without value for this project type.
+**4. Recurring friction**: Same problem from previous sessions? Check prior `desire_paths`. Increment counts.
 
-**4. Recurring friction**: Did the same problem come up that appeared in previous sessions? Check previous `desire_paths` entries. Increment occurrence counts.
+**5. Agent struggles**: Agent need multiple attempts or human intervention? Log task type and failure pattern.
 
-**5. Agent struggles**: Did any agent need multiple attempts or human intervention to complete a task? Log the task type and failure pattern.
-
-**6. User corrections**: Did the user correct the same thing multiple times? (e.g., "remember to use the Card component, not a div", "always add error boundaries"). These are implicit rules that should become explicit.
+**6. User corrections**: User correct the same thing multiple times? Implicit rules that should become explicit.
 
 ### Surface Recommendations
 
-When any pattern reaches **3+ occurrences**, surface it to the user:
-
-*"I've noticed a recurring pattern: [{description}] has come up {N} times now. This suggests we should evolve the framework. Options:"*
+When any pattern reaches **3+ occurrences**, surface it:
 
 | Pattern Type | Suggested Evolution |
 |-------------|-------------------|
-| Repeated deviations | Add pre-check to planning skill, or new constitutional article |
+| Repeated deviations | Add pre-check to planning, or new constitutional article |
 | Tier overrides | Adjust detection heuristics in forge skill |
-| Skipped steps | Make step optional for this project type, or merge into another step |
-| Recurring friction | Add specific guidance to relevant skill, or create a new template |
-| Agent struggles | Add examples or anti-patterns to the skill that handles this task |
-| User corrections | Add as a rule to constitution, context.md, or the relevant skill |
+| Skipped steps | Make step optional, or merge into another step |
+| Recurring friction | Add guidance to relevant skill, or create a template |
+| Agent struggles | Add examples or anti-patterns to the relevant skill |
+| User corrections | Add rule to constitution, context.md, or relevant skill |
 
-**Concrete actions the user can approve:**
-- *"Should I add 'always use Card component for content containers' to the design-system.md?"*
-- *"Should I add a null-check verification step to the planning template?"*
-- *"Should I make the research phase optional for Standard tier in this project?"*
-- *"Should I add a new constitutional article: 'Error Boundaries Required'?"*
+Propose concrete actions:
+- *"Add 'always use Card component for content containers' to design-system.md?"*
+- *"Add null-check verification step to planning template?"*
+- *"Make research phase optional for Standard tier in this project?"*
 
-Only suggest changes when there's clear evidence (3+ occurrences). One-off issues are noise, not signal.
+Only suggest at 3+ occurrences. One-off issues are noise.
 
 ## Phase Handoff
 
-After verification completes with a PASSED verdict:
+After 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`
+1. **Persist** — Confirm verification results documented, desire paths logged to `.forge/state/index.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.*
-
-*Ready to continue? Clear context and invoke `/forge` to resume."*
+*"Verification passed. State written. `/clear` then `/forge` to continue with reviewing."*
 
-Note: If verification found GAPS, route back to planning in gap-closure mode instead. The context clear recommendation applies after the re-verified PASSED verdict.
+If GAPS found, route back to planning in gap-closure mode. Context clear applies after re-verified PASSED verdict.

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

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

@@ -1,314 +0,0 @@
----
-name: auditing
-description: "Use after verifying passes to assess overall application health before milestone completion. Runs security audit (10 categories) and architecture audit (scaling, maintainability, code health). This is the pre-release gate — it answers 'is this codebase healthy enough to ship?'"
----
-
-# Auditing: Health Audit Before Milestone Completion
-
-You are the pre-release gate. After `verifying` confirms the work delivers what was promised, you assess whether the codebase is healthy enough to ship. Two parallel audits — security and architecture — produce a structured health 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 audit — glob all source files, summarize what will be scanned
-3. Spawn two parallel subagents: Security Audit + Architecture Audit
-4. Collect results, score per-category, determine overall status
-5. Write health report to `.forge/audits/milestone-{id}-health-report.md`
-6. Route based on results: healthy → complete, 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)
-```
-
-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
-
-## Step 2: Scope the Audit
-
-```
-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*
-```
-
-Present scope summary to user:
-*"Health audit scope: {N} source files, {N} config files. Scanning for security vulnerabilities (10 categories) and architectural health (4 dimensions). 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 Audits
-
-Spawn both audits as fresh-context subagents. Each receives:
-- The explicit file list for their scope
-- The tech stack from `project.yml`
-- Their specific audit 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: []
-```
-
-## Step 4: Score Results
-
-After both subagents return, compute scores.
-
-**Per-category scoring:**
-
-| 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 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 |
-
-## 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}"
-audited: "{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
-total_files_scanned: N
----
-```
-
-**Body structure:**
-
-```markdown
-# Health Audit Report: {milestone name}
-
-## Executive Summary
-{1-3 sentences: overall health assessment, key findings, 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}
-
-## Public Endpoints
-{List of intentionally public endpoints documented during security audit}
-
-## Files Scanned
-{Count and list of all files scanned across both audits}
-```
-
-**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: Route Based on Results
-
-### HEALTHY (all passed)
-
-Update `.forge/state/milestone-{id}.yml`:
-- Set `current.status` to `refactoring`
-
-Present to user:
-*"Health audit passed. No security vulnerabilities or architectural concerns found. Moving to refactoring review."*
-
-→ Route to `refactoring` skill.
-
-### NEEDS ATTENTION (critical issues found)
-
-Do NOT mark milestone complete. Present to user:
-
-*"Health audit found critical issues that should be addressed before shipping:"*
-
-Inline the top 3 findings per critical category so the user sees them immediately (don't make them open the report).
-
-Then offer 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, proceed to refactoring review
-
-If user chooses A:
-- Create fix requirements from critical findings
-- Route to `planning` skill in fix mode
-- After fix execution, re-run `auditing` (not full `verifying` — just the audit)
-
-If user chooses B:
-- Append "Accepted Risks" section to the health report with user's acknowledgment
-- Update `.forge/state/milestone-{id}.yml`: set `current.status` to `refactoring`
-- → Route to `refactoring` skill.
-
-### ACCEPTABLE WITH CAVEATS (warnings only)
-
-Present to user:
-
-*"Health audit passed with warnings — no critical issues, but {N} items worth noting. See the full report at `.forge/audits/milestone-{id}-health-report.md`."*
-
-Then offer choices:
-- **A. Continue to refactoring review** — accept warnings as known items
-- **B. Fix warnings** — address before continuing
-
-If user chooses A:
-- Document accepted warnings in report
-- Update `.forge/state/milestone-{id}.yml`: set `current.status` to `refactoring`
-- → Route to `refactoring` skill.
-
-If user chooses B:
-- Create fix requirements from warning findings
-- Route to `planning` in fix mode
-- After fix execution, re-run `auditing`
-
-## Gate Type: Soft Gate
-
-This is a soft gate — critical issues strongly recommend fixing before completion, but the user can accept risk and proceed. Rationale:
-- Some issues may be acceptable known risks for the deployment context
-- Some findings may be false positives despite the conservative flagging approach
-- Non-production or internal tools may have different risk tolerances
-- The user always has final authority over ship decisions
-
-The report documents the decision either way, creating an audit trail.
-
-## Phase Handoff
-
-After auditing routes to refactoring (all three paths: HEALTHY, accepted risk, accepted warnings):
-
-1. **Verify persistence** — Confirm health report is written to `.forge/audits/milestone-{id}-health-report.md`
-2. **Update state** — Set `current.status` to `refactoring` in `.forge/state/milestone-{id}.yml`
-3. **Recommend context clear:**
-
-*"Health audit complete. Report written to `.forge/audits/`. I recommend clearing context (`/clear`) before the refactoring review — the refactoring scanner spawns a fresh agent with the git diff and health report, so a clean context ensures accurate scanning.*
-
-*Ready to continue? Clear context and invoke `/forge` to resume."*