forge-orkes 0.3.8 → 0.3.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

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

@@ -29,7 +29,7 @@ Check for state files in this order:
 4. **If one milestone:** Auto-select it. Inform user: *"Resuming milestone: [{name}] — status: {current.status}, tasks: {overall_percent}%"*
 5. **If no active milestones:** Proceed to init or ask user to create one.
 6. Load the selected milestone's state file (`.forge/state/milestone-{id}.yml`)
-7. **Route based on `current.status`, NOT on `overall_percent`.** The `current.status` field is the authoritative workflow position. A milestone is only complete when `current.status` equals `complete`. Even if `overall_percent` is 100%, the milestone still needs to go through any remaining workflow steps (verifying, auditing, refactoring) before it is truly done.
+7. **Route based on `current.status`, NOT on `overall_percent`.** The `current.status` field is the authoritative workflow position. A milestone is only complete when `current.status` equals `complete`. Even if `overall_percent` is 100%, the milestone still needs to go through remaining workflow steps (verifying, reviewing) before it is truly done.
 8. Report position briefly, then **immediately route to the next skill** (see Step 3: Mandatory Auto-Routing):
    - **Workflow status** (`current.status`) — this is the primary indicator of where you are
    - Phase progress using precise terminology: "Executed" (code done, not verified), "Verified", "Pending", "In progress" — **never say "Complete" for a phase that hasn't been verified**
@@ -85,7 +85,7 @@ Match ANY:
 - Integration with external service
 - Estimated 1-8 hours of work
 
-→ Route through: `researching` → `discussing` → `planning` → `executing` → `verifying` → `auditing` → `refactoring`
+→ Route through: `researching` → `discussing` → `planning` → `executing` → `verifying` → `reviewing`
 
 ### Full Tier
 Match ANY:
@@ -96,7 +96,7 @@ Match ANY:
 - Estimated days of work
 - User says "full", "complex", "project", "milestone"
 
-→ Route through: `researching` → `discussing` → `architecting` → `planning` → `executing` → `verifying` → `auditing` → `refactoring`
+→ Route through: `researching` → `discussing` → `architecting` → `planning` → `executing` → `verifying` → `reviewing`
 → Add `designing` if UI work involved
 → Add `securing` if auth/data/API touched
 
@@ -140,12 +140,11 @@ This is a **briefing, not a prompt** — the user sees where they are and what's
 | `discussing` | Invoke `Skill(discussing)`, then → `planning` (or `architecting` for Full) |
 | `planning` | Invoke `Skill(planning)`, then → `executing` |
 | `executing` | Invoke `Skill(executing)`, then → `verifying` |
-| `verifying` | Invoke `Skill(verifying)`, then → `auditing` |
-| `auditing` | Invoke `Skill(auditing)`, then → `refactoring` |
-| `refactoring` | Invoke `Skill(refactoring)`, then → `complete` |
+| `verifying` | Invoke `Skill(verifying)`, then → `reviewing` |
+| `reviewing` | Invoke `Skill(reviewing)`, then → `complete` |
 | `complete` | Milestone is done. Ask user what's next. |
 
-- **Never treat a milestone as complete just because `overall_percent` is 100%.** Task completion and workflow completion are different. All planned tasks being done (100%) means execution is finished — verification, auditing, and refactoring still need to run.
+- **Never treat a milestone as complete just because `overall_percent` is 100%.** Task completion and workflow completion are different. All planned tasks being done (100%) means execution is finished — verification and reviewing still need to run.
 - Skip completed phases (phases before `current.status`)
 - Resume from current phase
 
@@ -154,7 +153,7 @@ This is a **briefing, not a prompt** — the user sees where they are and what's
 Sometimes a session ends before the executing skill advances `current.status`. On resume, detect and fix this:
 
 - **If `current.status == executing`**: Check if all phases in the roadmap have been executed (all plans completed, commits made). If YES → advance `current.status` to `verifying` in the state file, then route to verifying. If NO → route to executing for the next unexecuted phase.
-- **If `current.status == verifying`**: Check if verification report exists. If YES and it passed → advance to `auditing`. If NO → route to verifying.
+- **If `current.status == verifying`**: Check if verification report exists. If YES and it passed → advance to `reviewing`. If NO → route to verifying.
 - **General rule**: If the work for the current status is done but the status wasn't advanced (session ended mid-handoff), advance it now and route to the next skill.
 
 ### Phase Status Wording
@@ -168,7 +167,7 @@ When reporting phase progress on resume, use precise terminology to avoid confus
 | Not yet started | **"Pending"** | No work done yet |
 | Currently in progress | **"In progress"** | Partially executed |
 
-**Never say a phase is "Complete" unless it has passed through the full workflow** (executed + verified + audited). Use "Executed" for phases where code is done but verification hasn't run. This prevents users from thinking a phase is fully done when it still needs verification.
+**Never say a phase is "Complete" unless it has passed through the full workflow** (executed + verified + reviewed). Use "Executed" for phases where code is done but verification hasn't run. This prevents users from thinking a phase is fully done when it still needs verification.
 
 ### On-Demand Discussion
 
@@ -184,8 +183,7 @@ While working at any tier, if you encounter:
 | Missing validation/error handling/null checks | Auto-add, document | Rule 2 |
 | Broken import/dep/config blocking progress | Auto-fix, document | Rule 3 |
 | Need new DB table, service layer, library swap | **STOP. Ask user.** | Rule 4 |
-| After verifying passes | Run health audit before completion | `auditing` |
-| After auditing passes | Review refactoring opportunities | `refactoring` |
+| After verifying passes | Run health audit + refactoring review | `reviewing` |
 
 When uncertain → Rule 4 (ask). Never silently make architectural decisions.
 
@@ -202,7 +200,7 @@ Each phase produces persistent artifacts (state files, plans, reports, backlogs)
 Recommend clearing context at every phase boundary in Standard and Full tiers:
 
 ```
-researching → [clear] → discussing → [clear] → architecting → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → auditing → [clear] → refactoring
+researching → [clear] → discussing → [clear] → architecting → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → reviewing
 ```
 
 **Skip the recommendation when:**
@@ -233,8 +231,7 @@ Each skill ends with a standard handoff message. The pattern is:
 | architecting | ADRs in `.forge/decisions/`, data models, API contracts | planning reads decisions |
 | planning | Plans in `.forge/phases/m{M}-{N}-{name}/`, requirements.yml, roadmap.yml, context.md | executing reads plans |
 | executing | Committed code, execution summary, milestone state updated | verifying reads must_haves from plans |
-| verifying | Verification report, desire paths updated | auditing reads project.yml + source files |
-| auditing | Health report in `.forge/audits/` | refactoring reads health report + git diff |
+| verifying | Verification report, desire paths updated | reviewing reads project.yml + source files + git diff |
 
 ### Context Loading on Resume
 
@@ -243,7 +240,7 @@ When a skill starts after a context clear, it must load its required state from
 ## State Transitions
 
 ```
-not_started → [init if new] → researching → [clear] → discussing → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → auditing → [clear] → refactoring → complete
+not_started → [init if new] → researching → [clear] → discussing → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → reviewing → complete
                                                                                                     ↗ debugging (if stuck)
                                                                                           ↗ designing (if UI)
                                                                                           ↗ securing (if auth/data)

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/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."*

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

@@ -1,168 +0,0 @@
----
-name: refactoring
-description: "Review code built during a milestone for refactoring opportunities. Runs after auditing passes. Produces a structured backlog of improvements the user can work through via quick-tasking. Soft gate — review items, add to backlog, complete milestone."
----
-
-# Refactoring: Post-Milestone Code Review for Improvement Opportunities
-
-You review the code built during a milestone and catalog opportunities for improvement. This is not about correctness (that's `verifying`) or health (that's `auditing`) — it's about identifying code that works but could be cleaner, simpler, or more consistent.
-
-## When to Trigger
-
-- **Automatically** after `auditing` completes (all three paths: HEALTHY, NEEDS ATTENTION after fix, ACCEPTABLE WITH CAVEATS after accept)
-- **On-demand** at any time via user request
-
-## Step 1: Read Context
-
-```
-Read: .forge/project.yml → tech stack, conventions
-Read: .forge/state/milestone-{id}.yml → milestone ID, name, phases completed
-Read: .forge/audits/milestone-{id}-health-report.md → health findings (avoid overlap)
-Read: .forge/refactor-backlog.yml → existing backlog items (if any)
-Read: .forge/constitution.md → active architectural gates (if exists)
-```
-
-Determine the milestone's starting point for the git diff:
-- 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: Scan Milestone Code
-
-Spawn a fresh agent with isolated context. Pass it:
-- The explicit list of files changed during the milestone (from `git diff --name-only {start}..HEAD`)
-- The tech stack from `project.yml`
-- The health report findings (so it doesn't duplicate auditing's work)
-- The constitution (so it respects intentional decisions)
-
-**The agent scans for 6 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 already in the health report from auditing.
-- 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
-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"
-  - category: complexity
-    file: "src/components/Dashboard.tsx"
-    lines: "120-245"
-    description: "Dashboard render function is 125 lines with 4 levels of nesting"
-    effort: standard
-    suggested_approach: "Extract stat cards, chart section, and filter bar into subcomponents"
-```
-
-## Step 3: Present Findings to User
-
-Group findings by category. Show each with:
-- File and line range
-- What the issue is
-- Estimated effort
-- Suggested approach
-
-Present top findings (max 10 initially). If there are more, mention the count.
-
-*"I found {N} refactoring opportunities in the code built during this milestone:"*
-
-Then 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. ...*"
-
-## Step 4: User Triage
-
-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 5: Write 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`.
-
-Present summary:
-*"Added {N} items to the refactor backlog. {M} dismissed. You can work these anytime — pending items with `effort: quick` will show up as available Quick tasks when you start a session."*
-
-## Step 6: Route
-
-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.
-
-## Gate Type: Soft Gate
-
-This is a soft gate — it presents opportunities but never blocks milestone completion. Rationale:
-- Refactoring is improvement, not correctness. The code already works (verified) and is healthy (audited).
-- Users should review opportunities but aren't forced to act on them immediately.
-- Backlog items persist across sessions and can be worked whenever it makes sense.
-- Some items may become irrelevant as the codebase evolves — that's fine.
-
-## 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