forge-orkes 0.3.13 → 0.3.19

package/package.json

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

package/template/.claude/agents/researcher.md

@@ -6,29 +6,22 @@ Read-only investigation. Gather facts, never change code.
 Investigate codebases, requirements, tech, feasibility. Structured findings for Planner/Architect. Observe/report — never modify.
 
 ## Tools
-**Allowed:** Read, Glob, Grep, Bash read-only (`ls`, `find`, `cat`, `tree`, `npm list`, `git log`, `git diff`, `wc`), WebFetch, WebSearch, Task (parallel sub-researchers)
-**Forbidden:** Write, Edit, Bash mutators (`git commit`, `git push`, `rm`, `mv`, `cp`, `npm install`)
+
+| Allowed | Forbidden |
+|---------|-----------|
+| Read, Glob, Grep | Write, Edit |
+| Bash read-only (`ls`, `find`, `cat`, `tree`, `npm list`, `git log`, `git diff`, `wc`) | Bash mutators (`git commit`, `git push`, `rm`, `mv`, `cp`, `npm install`) |
+| WebFetch, WebSearch | |
+| Task (parallel sub-researchers) | |
 
 ## Input
 - Task from user or Forging skill; scope (codebase/requirements/tech/feasibility); constraints (time, focus, known context)
 
-## Output Template
-
-```markdown
-# Research: {Topic}
-## Summary
-{2-3 sentence overview}
-## Findings
-### {Finding 1}
-- **Detail**: {what was found}
-- **Source**: {file path / URL / documentation}
-- **Confidence**: HIGH | MEDIUM | LOW
-- **Implication**: {project impact}
-## Unknowns
-- {What couldn't be determined and why}
-## Recommendations
-- {Actionable next steps}
-```
+## Output
+
+Use the canonical **Finding Format** in `.claude/skills/researching/SKILL.md § Finding Format`. That schema is authoritative for both in-conversation summaries and the persisted artifact. Do not invent alternate structures.
+
+Every finding needs: source, confidence (HIGH/MEDIUM/LOW), and rationale for the confidence call.
 
 ## Process
 
@@ -57,7 +50,7 @@ Priority: MCP servers -> Codebase (Glob->Grep->Read) -> Docs (WebFetch) -> WebSe
 | UNVERIFIED | Training knowledge | State "unverified" |
 
 ### 5. Deliver
-Use template. Every finding needs: source, confidence, implication.
+Emit using the Finding Format from `researching/SKILL.md § Finding Format`. Every finding needs source, confidence, and rationale for the confidence call.
 
 ## Success Criteria
 - [ ] All questions answered or unknowns listed
@@ -71,3 +64,4 @@ Use template. Every finding needs: source, confidence, implication.
 - **Trusting training data**: Unverified as HIGH
 - **Analysis paralysis**: Over-investigating when MEDIUM suffices
 - **Scope creep**: Tangential topics outside scope
+- **Schema drift**: Inventing fields, renaming sections, duplicating the Finding Format — reference the skill, don't copy

package/template/.claude/agents/reviewer.md

@@ -1,140 +1,128 @@
 # Agent: Reviewer
 
-Security + code quality audit. Read-only. No fixes.
+Read-only auditor spawned by `reviewing` skill. Emits YAML per mode. No fixes, no source modification.
 
 ## Role
-Security + quality review. Identify risks — Executor addresses.
 
-## Tools
-**Allowed:** Read, Glob, Grep, Bash read-only (`npm audit`, `git log`, `git diff`, static analysis), Task (sub-reviewers)
-**Forbidden:** Write, Edit, Bash mutators (`git commit`, `git push`, `npm install`, `rm`), fixing (report only)
-
-## Input
-Verification report (if any), source code, `.forge/context.md`, `constitution.md`.
-
-## Output
-
-```markdown
-# Review: {Feature/Phase Name}
-**Date**: {YYYY-MM-DD}
-**Reviewer**: Claude (Forge reviewer agent)
-**Scope**: {files/modules}
-
-## Security Findings
-### Critical (Must fix before ship)
-- **[S-001]** {Finding}
-  - File: {path}:{line}
-  - Risk: {impact}
-  - Fix: {recommendation}
-### Warning
-- **[S-002]** {Finding}
-### Info
-- **[S-003]** {Finding}
-
-## Code Quality
-### Architecture Compliance
-- Article I (Library-First): PASS/FAIL — {evidence}
-- Article III (Simplicity): PASS/FAIL — {evidence}
-- Article IV (Consistency): PASS/FAIL — {evidence}
-### Patterns
-- **[Q-001]** File: {path}:{line} — {issue} — {suggestion}
-### Dependency Health
-- `npm audit`: {summary}
-- Outdated: {list}
-- Licenses: {concerns}
-
-## Context Compliance
-- Locked decisions: YES/NO — {details}
-- Deferred absent: YES/NO — {details}
-- Design system: YES/NO — {details}
-
-## Summary
-Critical: {n} | Warnings: {n} | Info: {n}
-Recommendation: SHIP | FIX THEN SHIP | REWORK
-```
+Spawned by `.claude/skills/reviewing/SKILL.md` Step 3 in one of three modes: `security`, `architecture`, or `refactoring`. Scan in-scope files, emit the YAML schema that matches the invoked mode. The reviewing skill aggregates outputs into the milestone health report.
 
-## Process
+One agent definition, three modes. Mode is set by the invoking skill at spawn.
 
-### 1. Scope
-Changed files (git diff/summary), auth/data/API/secrets, verification-flagged.
-
-### 2. Security Checklist
+## Tools
 
-**Auth**
-```bash
-grep -rn "password\|secret\|api_key\|token\|Bearer" src/ --include="*.ts" --include="*.tsx" --include="*.js"
-grep -rn "eval(\|new Function(\|dangerouslySetInnerHTML" src/
-grep -rn "SELECT.*\${\|INSERT.*\${\|UPDATE.*\${" src/
+| Allowed | Forbidden |
+|---------|-----------|
+| Read, Glob, Grep | Write, Edit, NotebookEdit |
+| Bash read-only (`git log`, `git diff`, `npm audit`, `npm outdated`, static analysis) | Task |
+| | Bash mutators (`git commit`, `git push`, `npm install`, `rm`, any writes) |
+| | Auto-fixing findings |
+
+## Upstream Input
+
+Supplied by the reviewing skill at spawn:
+- Mode flag: `security | architecture | refactoring`
+- File list in scope (paths, not globs)
+- Tech stack summary (from `.forge/project.yml`)
+- Milestone id + name
+
+Additional context to read on start:
+- `.forge/project.yml` — stack, framework, database, dependencies
+- `.forge/state/milestone-{id}.yml` — milestone id + name
+- `.forge/constitution.md` — active gates (if present)
+- `.forge/deferred-issues.md` — pre-existing failures (architecture mode only)
+
+## Downstream Output
+
+Emit exactly one fenced YAML block, matching the mode. Shapes come from `.claude/skills/reviewing/SKILL.md` Step 3. Do not add, rename, or reorder fields. No prose outside the block.
+
+### Mode: security
+
+```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"
 ```
 
-**Input Validation**
-```bash
-grep -rn "req\.body\|req\.params\|req\.query" src/ --include="*.ts"
-grep -rn "innerHTML\|outerHTML\|document\.write" src/
+Categories 1-10 per reviewing/SKILL.md Step 3 Part 1.
+
+### Mode: architecture
+
+```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: []
 ```
 
-**Secrets**
-```bash
-grep -n "\.env" .gitignore
-grep -rn "sk-\|pk_\|Bearer \|apiKey:" src/
-```
+Dimensions + checks per reviewing/SKILL.md Step 3 Part 2.
 
-**Dependencies**
-```bash
-npm audit 2>&1
-npm outdated 2>&1
-```
+### Mode: refactoring
 
-### 3. Code Quality
-**Constitution:** Per article, check gates, PASS/FAIL + evidence.
-**Patterns:** Structure, naming, errors, imports consistent.
-
-| Threshold | Action |
-|-----------|--------|
-| Functions > 50 lines | Flag refactor |
-| Files > 300 lines | Flag split |
-| Nesting 4+ deep | Flag simplify |
-| Duplicated blocks | Flag extract |
-
-### 4. Design System
-```bash
-grep -rn "<button\|<input\|<select\|<table" src/ --include="*.tsx" --include="*.jsx"
-grep -rn "color:\|background:\|font-size:" src/ --include="*.css" --include="*.scss"
-grep -rn "from 'primereact" src/ --include="*.tsx"
+```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"
 ```
 
-### 5. Context
-Check `.forge/context.md`: no locked-out tech, no deferred features, discretion ok.
+Categories 1-6 per reviewing/SKILL.md Step 3 Part 3. `effort: quick | standard`. Milestone-changed files only.
 
-### 6. Report
+## Process
 
-| Level | Criteria |
-|-------|----------|
-| **Critical** | Security vuln, data leak, auth breach |
-| **Warning** | Code smell, minor security, pattern issue |
-| **Info** | Style, refactor opp, doc gap |
+1. **Read context** — load project.yml, milestone-{id}.yml, constitution.md. Architecture mode also reads deferred-issues.md.
+2. **Scan in-scope files per mode's rules** — see reviewing/SKILL.md Step 3 for the authoritative category/dimension tables and scanning rules. Do not duplicate those tables here.
+3. **Classify findings** — severity per the taxonomy in the YAML schema: `critical` = exploitable vuln / prod-blocking issue, `warning` = defense gap or quality issue, `info` = observation. Inapplicable category (e.g. XSS on backend-only stack) → `status: na`.
+4. **Emit YAML** — one fenced block, matching the mode's schema exactly. No cross-mode output.
 
-| Verdict | When |
-|---------|------|
-| **SHIP** | No critical, warnings acceptable |
-| **FIX THEN SHIP** | Critical but small scope |
-| **REWORK** | Fundamental issues |
+Scanning is exhaustive per mode scope — every file in the supplied list, no sampling. Security and architecture modes take the full source set; refactoring mode takes only milestone-changed files.
 
 ## Success Criteria
-- [ ] Security checklist done
-- [ ] Articles checked
-- [ ] Design system verified
-- [ ] Deps assessed
-- [ ] Context confirmed
-- [ ] No code modified
-- [ ] Clear recommendation
+
+- [ ] Correct YAML schema emitted for the invoked mode
+- [ ] Every file in supplied scope scanned (no sampling)
+- [ ] Per-finding fields populated: file, line, severity, issue, remediation (or effort + suggested_approach for refactoring)
+- [ ] Category/dimension `status` set per observed findings
+- [ ] No source files modified
+- [ ] No output outside the fenced YAML block
 
 ## Anti-Patterns
 
-| Anti-Pattern | Description |
-|-------------|-------------|
-| Rubber stamping | PASS without checking |
-| Fix-while-reviewing | Modifying code (read-only) |
-| Severity inflation | Style as Critical |
-| Missing context | No context.md read |
-| Ignoring constitution | Skipping because "works" |
+| Anti-Pattern | Why it's wrong |
+|-------------|----------------|
+| Rubber-stamping | Marking `passed` without scanning — defeats the audit |
+| Fix-while-reviewing | Agent is read-only; fixes go to executor via backlog |
+| Severity inflation | Style nits marked `critical` degrade signal |
+| Missing context | Skipping project.yml / constitution.md → false positives on intentional patterns |
+| Schema drift | Inventing fields, renaming keys, or mixing modes — breaks the reviewing skill's aggregation |
+| Duplicating skill tables | The category/dimension tables live in reviewing/SKILL.md; reference them, don't copy |

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

@@ -91,21 +91,15 @@ Open-ended via prose: *"Tried before?" / "Must-haves or must-nots?"* 1-2 at a ti
 
 ### Step 4: Functionality Distillation
 
-Per feature, force behavioral clarity. Surface assumptions + edge cases. **Five layers:**
-
-| Layer | Focus | When to use |
-|-------|-------|-------------|
-| 1. Happy Path | What success looks like step by step | Always |
-| 2. Boundaries & Rules | Permissions, limits, triggers, preconditions | Anything with rules |
-| 3. Failure Modes | Invalid input, service down, cancellation, concurrency | Critical paths (payments, data mutations, auth, integrations) |
-| 4. Interactions & Side Effects | Cascading updates, notifications, undo, related features | Features with shared state or dependencies |
-| 5. Evolution | v1 vs. final shape, scope cuts, likely future changes | Uncertain scope |
-
-**L1:** *"See first?" / "Sequence?" / "Confirms success?"*
-**L2:** *"Who can?" / "Limits?" / "Trigger type?"*
-**L3:** *"Invalid/down/cancel?" / "Retry/fail/alert?" / "Concurrent?"*
-**L4:** *"Else updates?" / "Notify?" / "Undo?"*
-**L5:** *"v1 or final?" / "Essential vs nice-to-have?"*
+Per feature, force behavioral clarity. Surface assumptions + edge cases.
+
+**L1 (Happy Path):** *"See first?" / "Sequence?" / "Confirms success?"*
+**L2 (Rules):** *"Who can?" / "Limits?" / "Trigger type?"*
+**L3 (Failures):** *"Invalid/down/cancel?" / "Retry/fail/alert?" / "Concurrent?"*
+**L4 (Side Effects):** *"Else updates?" / "Notify?" / "Undo?"*
+**L5 (Evolution):** *"v1 or final?" / "Essential vs nice-to-have?"*
+
+**Listen for:** Contradictions ("Simple" + "12 states"), Vague ("Just work" → push for example), Assumed knowledge ("Like Stripe" → confirm specifics), Energy shifts (excitement/boredom = signal).
 
 Not all 5 mechanically. 2-3 questions, deeper on uncertainty. `AskUserQuestion` for discrete; prose to explain.
 
@@ -122,12 +116,6 @@ options:
     description: "Process remaining items, revisit failures in next sweep."
 ```
 
-**Listen for:**
-- **Contradictions** -- "Simple" + "12 states." Surface.
-- **Vague** -- "Just work." Push for example.
-- **Assumed knowledge** -- "Like Stripe." Confirm specifics.
-- **Energy shifts** -- Excitement/boredom = signal.
-
 ### Step 5: Converge
 
 Summarize decided items, then confirm:

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

@@ -13,19 +13,9 @@ description: "Build to plan with atomic commits, deviation rules, and context en
 
 ## Deviation Rules
 
-### Rule 4 Check First (Architectural)
-New DB table, service layer, schema change, library swap, or infra change?
-- **YES** → **STOP.** Checkpoint: what, proposed change, why, impact, alternatives. Wait for user.
-- **NO** → Continue to Rules 1-3.
+**Full definitions:** `.claude/agents/executor.md`. Decision order: **Rule 4 first** (architectural → STOP, ask user), then Rule 1 (bugs), Rule 2 (critical gaps), Rule 3 (infra blockers). Uncertain → Rule 4.
 
-### Rule 1: Auto-Fix Bugs
-Bug blocking current task → Fix inline. Add test if applicable. Document: "Rule 1: Fixed [bug] because [reason]."
-
-### Rule 2: Auto-Add Critical Functionality
-Missing error handling, validation, null checks, auth, CSRF, rate limiting, logging → Add it. Document: "Rule 2: Added [what] because [reason]."
-
-### Rule 3: Auto-Fix Blocking Infrastructure
-Missing dep, wrong types, broken imports, env var, build config → Fix it. Document: "Rule 3: Fixed [issue] because [reason]."
+Execution-phase operational guidance below supplements the rules — it does not redefine them.
 
 ### 3-Strike Limit
 3 auto-fix attempts on a single task → STOP. Document remaining issues. Move to next task.
@@ -128,25 +118,42 @@ Attempt 1:
   1. Read error output
   2. Caused by current task?
      - YES → fix code, stage fixes, amend commit
-     - NO → mark advisory for this session, log warning, continue
+     - NO → mark advisory for this session; append to .forge/deferred-issues.md; continue
   3. Re-run command
   4. Pass → next command
   5. Fail → next attempt (up to max_retries)
 
 After max_retries exhausted:
+  → Append to .forge/deferred-issues.md
   → Log failure in execution summary
   → Continue to next task
-  → Verifying skill catches persistent failures later
 ```
 
 ### 3-Strike Integration
 Verification retries count toward the task's 3-strike limit. 2 strikes used = 1 verification retry max.
 
 ### Do NOT Fix
-- **Pre-existing failures** not from current task → mark advisory
+- **Pre-existing failures** not from current task → mark advisory; append to `.forge/deferred-issues.md`
 - **Flaky tests** passing on re-run without changes → note in summary, no strike
 - **Unrelated warnings** (deprecation, non-blocking lint) → ignore
 
+### Deferred Issues Format
+
+Append one entry per failure to `.forge/deferred-issues.md` (create if missing):
+
+```yaml
+issues:
+  - id: DI-001
+    type: test_failure | lint_failure | build_failure
+    command: "npm test"
+    summary: "HealthEndpointTest — Redis unavailable in test env"
+    first_seen: "2026-04-14"
+    milestone: "m3"
+    status: pending
+```
+
+ID = `DI-{N}` where N = next integer after existing max (or 001 if new file).
+
 ### Quick Tier
 Run all non-advisory verification commands once after commit. 1 retry max.
 

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

@@ -79,9 +79,9 @@ Tier + state → invoke via `Skill` tool.
 
 **CRITICAL: NEVER `EnterPlanMode`.** "Planning" = `Skill(planning)`. Native plan mode writes wrong format, bypasses gates + state.
 
-### Mandatory Auto-Routing on Resume
+### Auto-Routing (Always Deterministic)
 
-**No menus.** Deterministic. Brief → route. Choices only at `complete` or corrupted.
+**No menus.** Applies on first run and resume. Deterministic. Brief → route. Choices only at `complete` or corrupted.
 
 1. Read `milestone-{id}.yml` → 2. Check advancement → 3. `current.status` → skill → 4. Brief + route:
 
@@ -121,7 +121,6 @@ Subagents via `Task` → same precedence.
 | `reviewing` | `Skill(reviewing)` → complete |
 | `complete` | Done. Ask what's next. |
 
-- 100% tasks != complete -- verification + reviewing must run.
 - Skip before `current.status`; resume current.
 
 ### Status Advancement Check
@@ -148,27 +147,12 @@ Sessions end before advancement. On resume detect + fix:
 
 ## Deviation Rules (All Tiers)
 
-| Situation | Action | Rule |
-|-----------|--------|------|
-| Bug blocking task | Auto-fix, document | 1 |
-| Missing validation/error handling/null checks | Auto-add, document | 2 |
-| Broken import/dep/config | Auto-fix, document | 3 |
-| New DB table, service layer, library swap | **STOP. Ask user.** | 4 |
-| After verifying passes | Health + refactoring audit | `reviewing` |
-| Model routing mismatch | Flag expensive models for mechanical tasks | `reviewing` |
-
-Uncertain → 4. Never silently make arch decisions.
+See CLAUDE.md § Deviation Rules (always loaded) or `.claude/agents/executor.md` for full definitions. Uncertain → Rule 4.
 
 ## Context Handoff Protocol
 
 Phase transitions = clear boundaries. **Recommend `/clear`** after writing state. Next phase reads disk artifacts, not working memory.
 
-Standard/Full:
-
-```
-researching → [clear] → discussing → [clear] → architecting → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → reviewing
-```
-
 **Skip:** Quick, short phase + context <40%, user opted out.
 
 ### Handoff Pattern
@@ -182,7 +166,7 @@ researching → [clear] → discussing → [clear] → architecting → [clear]
 
 | Phase | Writes | Read By |
 |-------|--------|---------|
-| researching | Research summary | discussing |
+| researching | `.forge/research/milestone-{id}.md` | discussing |
 | discussing | Decisions → context.md | planning |
 | architecting | ADRs, data models, API contracts | planning |
 | planning | `.forge/phases/m{M}-{N}-{name}/`, requirements.yml, roadmap.yml | executing |
@@ -196,10 +180,11 @@ After clear, skills load from disk via "Read Context"/"Pre-Execution Checklist".
 ## State Transitions
 
 ```
-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)
+Standard: not_started → [init?] → researching → discussing → planning → executing → verifying → reviewing → complete
+Full:     not_started → [init?] → researching → discussing → architecting → planning → executing → verifying → reviewing → complete
+
+Branches (any tier, on-demand): debugging (stuck) · designing (UI) · securing (auth/data/API)
+Phase boundaries: `[clear]` recommended between phases to reset context.
 ```
 
 Update `milestone-{id}.yml` + `index.yml` `last_updated` at each transition.

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

@@ -94,6 +94,8 @@ Check: Any structured agent/workflow system
 | `extensions/` | Specialized skills | `.claude/skills/` (if relevant) |
 | Project specs (if filled in) | Locked decisions | `.forge/context.md` |
 
+**BMAD:** No dedicated absorption table. Use Generic path.
+
 **Generic:** `researching` reads all markdown/config, maps to Forge equivalents, confirms with user.
 
 **Process:** Read sources → synthesize per target → prose to YAML where expected, keep markdown where expected → unmapped to `.forge/context.md` "Carried Forward" → originals to `.forge/archive/{name}/` → show summary. Then continue brownfield steps.

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

@@ -83,7 +83,9 @@ For independent topics, research simultaneously:
 
 Never research sequentially when topics are independent.
 
-## Output Template
+## Finding Format
+
+Canonical schema for research output. Used both for in-conversation summaries and the persisted artifact (see Research Artifact below).
 
 ```markdown
 # Research: [Topic]
@@ -95,6 +97,9 @@ Never research sequentially when topics are independent.
 1. [Finding] — Confidence: HIGH/MEDIUM/LOW — Source: [source]
 2. [Finding] — Confidence: HIGH/MEDIUM/LOW — Source: [source]
 
+## Ruled Out
+- [approach]: [reason rejected]
+
 ## Recommendations
 - [Recommended approach with rationale]
 
@@ -110,9 +115,15 @@ Never research sequentially when topics are independent.
 
 Research output under 500 lines. If larger, split into focused documents: `research-codebase.md`, `research-tech.md`, `research-requirements.md`.
 
+## Research Artifact
+
+Always write `.forge/research/milestone-{id}.md` at phase end. Create directory if needed. Immutable after writing — dated snapshot, never updated. Re-research if stale.
+
+Artifact uses the Finding Format above, with two adjustments: prepend `Date: {YYYY-MM-DD}` below the title, and omit the Sources section (URLs are ephemeral).
+
 ## Phase Handoff
 
-1. **Persist findings** — Write research summary to `.forge/phases/m{M}-{N}-{name}/` or present inline. Standard tier: inline is fine. Full tier with multiple topics: write to files.
+1. **Write artifact** (see Research Artifact section above).
 2. **Update state** — Set `current.status` to `discussing` in `.forge/state/milestone-{id}.yml`
 3. **Recommend context clear:**
 

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

@@ -29,6 +29,7 @@ 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)
+Read: .forge/deferred-issues.md → pre-existing failures logged during execution (if exists)
 ```
 
 Skip by stack: no DB->SQL/NoSQL N/A, no frontend->XSS N/A, no CI/CD->Pipeline N/A.
@@ -94,7 +95,7 @@ security_audit:
 |-----------|--------|
 | **Scalability** | Synchronous blocking, missing pagination, unbounded queries, N+1, missing caching, SPOFs, hardcoded limits |
 | **Maintainability** | Files >300 lines, nesting >4, god components/classes, circular deps, dup logic |
-| **Code Health** | Dead code/unused exports, TODO/FIXME inventory, untested critical paths, stale deps |
+| **Code Health** | Dead code/unused exports, TODO/FIXME inventory, untested critical paths, stale deps, deferred issues in `.forge/deferred-issues.md` |
 | **Structural Quality** | Biz logic in UI, inconsistent patterns, missing error boundaries, API contract drift |
 
 **Rules:** Actual code, not theory. Specific files + evidence. `critical`=prod issues/blocking, `warning`=quality, `info`=improvement. Respect ADRs + constitution.
@@ -254,6 +255,13 @@ Refactoring triage (max 10): *"{N} opportunities:"*
 
 **Accept**->backlog | **Dismiss**->skip | **Accept all** | **Dismiss all**
 
+Deferred issues triage: If `.forge/deferred-issues.md` has `status: pending` items, surface them:
+*"**Test debt** ({N} pre-existing failures): 1. `{summary}` -- first seen {date}. [Accept/Dismiss/Fix-now]*"*
+
+- **Accept** → add to refactor-backlog.yml as `category: test-debt`, mark `status: triaged` in deferred-issues.md
+- **Fix-now** → route to `planning` fix mode before completing milestone
+- **Dismiss** → mark `status: dismissed` in deferred-issues.md with reason
+
 ## Step 7: Backlog + Route
 
 ### Backlog

package/template/CLAUDE.md

@@ -125,7 +125,8 @@ State lives in `.forge/`:
 - `state/index.yml` — Global: active milestones, desire_paths, metrics
 - `state/milestone-{id}.yml` — Per-milestone cursor: position, progress, decisions, blockers
 - `context.md` — Locked decisions + deferred ideas (discuss phase)
-- `plan.md` — Task plans with must_haves frontmatter
+- `research/milestone-{id}.md` — Research findings snapshot (dated, immutable)
+- `phases/m{M}-{N}-{name}/plan-{NN}.md` — Task plans with must_haves frontmatter
 - `refactor-backlog.yml` — Refactoring catalog, worked via quick-tasking
 
 **Milestones** group phases into concurrent streams. Own state file — no conflicts across sessions.
@@ -134,10 +135,14 @@ State lives in `.forge/`:
 
 ## Deviation Rules
 
-1. **Bug blocking task** → Auto-fix. Document "Rule 1."
-2. **Missing critical functionality** (error handling, validation, auth, null checks) → Auto-add. "Rule 2."
-3. **Blocking infrastructure** (missing dep, wrong types, broken imports) → Auto-fix. "Rule 3."
-4. **Architectural change** (new DB table, service layer, library switch) → **STOP. Ask user.** "Rule 4."
+**Full definitions:** `.claude/agents/executor.md`.
+
+| Situation | Action | Rule |
+|-----------|--------|------|
+| Bug blocking task | Auto-fix, document | 1 |
+| Missing validation/error handling/null checks | Auto-add, document | 2 |
+| Broken import/dep/config | Auto-fix, document | 3 |
+| New DB table, service layer, library swap | **STOP. Ask user.** | 4 |
 
 Priority: Rule 4 first. Then 1-3. Uncertain → Rule 4.