@jamie-tam/forge 6.0.0

package/skills/support-debug/SKILL.md

@@ -0,0 +1,464 @@
+---
+name: support-debug
+description: "Use when encountering any bug, test failure, error, crash, or unexpected behavior — enforces systematic root cause investigation."
+---
+
+# Support: Debug
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues. This skill enforces a rigorous four-phase debugging process that finds root causes before attempting fixes.
+
+**Core Principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Laws
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
+FACT-CHECK THE PROBLEM BEFORE ASSUMING THE SYSTEM IS WRONG.
+IF 3 FIXES FAIL, STOP AND DISCUSS ARCHITECTURE.
+AFTER EVERY FIX, RECORD THE LESSON IN SUPPORT-GOTCHA.
+```
+
+If you have not completed Phase 1, you cannot propose fixes. Period.
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+- "It was working yesterday"
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You have already tried multiple fixes
+- Previous fix did not work
+- You do not fully understand the issue
+
+**Do NOT skip when:**
+- Issue seems simple (simple bugs have root causes too)
+- You are in a hurry (systematic debugging is faster than thrashing)
+- User wants it fixed NOW (systematic is faster than guess-and-check)
+- You think you already know the answer (verify first)
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Bug description, error output, or unexpected behavior report |
+| **Produces** | Root cause analysis + implemented fix + test demonstrating the fix |
+| **Feeds into** | `support-gotcha` (record lesson learned) |
+| **Updates** | `.forge/work/{type}/{name}/manifest.yaml` if bug is part of a feature |
+
+### Output Format
+
+When debugging is complete, produce:
+
+```markdown
+## Debug Report: {brief description}
+
+### Root Cause
+{What actually caused the problem and why}
+
+### Investigation Path
+{Key steps taken to find root cause, including dead ends}
+
+### Fix Applied
+{What was changed and why this addresses the root cause}
+
+### Test Added
+{Test that demonstrates the fix and prevents regression}
+
+### Lesson Learned
+{What to watch for in the future -- feeds into support-gotcha}
+```
+
+## Phase 0: Fact-Check First
+
+**BEFORE starting the four-phase process, verify the reported problem is real.**
+
+This phase applies the `rules/common/verification.md` rule specifically to bug reports. The verification rule is the authority on when and how to verify; this phase is how support-debug implements that rule for debugging contexts.
+
+1. **Verify the Reported Behavior**
+   - Can you reproduce exactly what the user describes?
+   - Is the error message exactly what they reported?
+   - Is the behavior actually wrong, or is it correct behavior they did not expect?
+
+2. **Verify Assumptions About Libraries/APIs**
+   - User says "library X should do Y" -- verify via documentation
+   - Use context7 or web search to confirm library behavior
+   - Check the actual version of the library in use (behavior may differ between versions)
+   - Read the library's changelog if behavior recently changed
+
+3. **Verify Environment Assumptions**
+   - "It works on my machine" -- check environment differences
+   - "It was working yesterday" -- check what changed (git log, dependency updates, env changes)
+   - "The API returns X" -- actually call the API and verify
+
+4. **If the Problem Is Not What Was Reported**
+   - State clearly: "I investigated and the actual issue is different from what was reported."
+   - Explain what is actually happening
+   - Then proceed with Phases 1-4 for the real issue
+
+**Example of fact-checking catching a misreport:**
+```
+User: "The fetch API is broken -- it's not sending the Content-Type header."
+Fact-check: Fetch API does send Content-Type for POST requests with body.
+             The actual issue: fetch was sending a GET request (missing method: 'POST').
+Real root cause: Missing method parameter, not a broken API.
+```
+
+## Adaptive Triage: Linear vs. Trace
+
+After Phase 0 (fact-checking), assess bug complexity to choose the investigation method:
+
+### Quick Triage (main agent, 2 minutes)
+
+**Prerequisite:** This triage assumes you completed Phase 0 (fact-check). If you did not reproduce the bug and verify assumptions, go back to Phase 0 first. Do not triage based on the user's description alone.
+
+Can you identify the likely cause from the stack trace, error message, or a single code path?
+
+**YES → Linear debugging (Phases 1-4 below).** Fast, cheap, sufficient for most bugs.
+
+**NO → Trace methodology.** Use when:
+- No clear stack trace or error message
+- Intermittent or non-deterministic behavior
+- Bug spans multiple systems or services
+- Previous fix attempts failed
+- User says "we've been trying to fix this"
+
+### Trace Methodology (for complex bugs)
+
+Dispatch the **tracer** subagent which investigates with 3 competing hypotheses in parallel:
+
+1. **Lane 1 (code-path):** Implementation bug, wrong logic, missing check
+2. **Lane 2 (config/env):** Wrong env var, version mismatch, deploy issue
+3. **Lane 3 (assumption):** Test is wrong, expectation is wrong, data changed
+
+Each lane gathers evidence FOR and AGAINST its hypothesis, ranked by strength:
+> controlled reproduction > primary artifacts > multiple sources > inference > speculation
+
+After investigation, a rebuttal round between top hypotheses determines the most likely root cause with a confidence rating (HIGH/MEDIUM/LOW).
+
+When the tracer returns its verdict, proceed to Phase 4 (Implementation) with the identified root cause. If confidence is LOW, the tracer will recommend a discriminating probe — run it before attempting a fix.
+
+## The Four Phases (Linear Debugging)
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 0: Codex Mode Check
+
+The user has already described the bug in their message. Run the Codex consent flow from `protocols/codex.md`. The selected mode applies for the rest of this skill's invocation.
+
+- **Takeover:** Dispatch Codex with the bug description, error messages/stack trace from the user's message, and skill methodology. Codex performs the 4-phase investigation. Claude reviews hypotheses and tests the fix.
+- **Verify** or **Skip / Codex unavailable:** Proceed with Phases 1-4 below. Phase 2.5 will dispatch Codex to propose alternative hypotheses (Verify only).
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Do not skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+   - Search for the exact error message in the codebase
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - Does it happen every time?
+   - If not reproducible, gather more data -- do NOT guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - `git diff`, recent commits, `git log --oneline -20`
+   - New dependencies, config changes
+   - Environmental differences (Node version, OS, Docker image)
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   When the system has multiple components (CI -> build -> signing, API -> service -> database):
+
+   **BEFORE proposing fixes, add diagnostic instrumentation:**
+
+   ```
+   For EACH component boundary:
+     - Log what data enters the component
+     - Log what data exits the component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once to gather evidence showing WHERE it breaks.
+   THEN analyze evidence to identify the failing component.
+   THEN investigate that specific component.
+   ```
+
+   **Example (multi-layer system):**
+   ```bash
+   # Layer 1: API Gateway
+   echo "=== Request received: ==="
+   echo "Method: $METHOD, Path: $PATH, Headers: $HEADERS"
+
+   # Layer 2: Service
+   echo "=== Service input: ==="
+   echo "Parsed body: $BODY"
+
+   # Layer 3: Database
+   echo "=== Query executed: ==="
+   echo "SQL: $QUERY, Params: $PARAMS"
+
+   # Layer 4: Response
+   echo "=== Response: ==="
+   echo "Status: $STATUS, Body: $RESPONSE_BODY"
+   ```
+
+   This reveals which layer fails (API -> Service OK, Service -> Database FAIL).
+
+5. **Trace Data Flow (Backward Tracing)**
+
+   When the error is deep in the call stack:
+
+   - Start at the error location
+   - Where does the bad value come from?
+   - What called this function with the bad value?
+   - Keep tracing backward until you find the SOURCE
+   - Fix at the source, not at the symptom
+
+   ```
+   Error: Cannot read property 'name' of undefined
+     at renderUser (user.tsx:42)         <- symptom
+     at UserList (list.tsx:18)           <- passed undefined user
+     at loadUsers (api.ts:55)            <- returned null instead of []
+     at fetchData (fetch.ts:12)          <- ROOT CAUSE: missing error handling
+   ```
+
+   Fix at `fetch.ts:12`, not at `user.tsx:42`.
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in the same codebase
+   - What works that is similar to what is broken?
+   - If a similar feature works, diff the two implementations
+
+2. **Compare Against References**
+   - If implementing a known pattern, read the reference implementation COMPLETELY
+   - Do not skim -- read every line
+   - Understand the pattern fully before applying
+   - Use context7 to fetch current documentation for the library/framework
+
+3. **Identify Differences**
+   - What is different between working and broken?
+   - List every difference, however small
+   - Do not assume "that can't matter" -- small differences often matter
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+   - Check versions of all involved dependencies
+
+#### Phase 2.5: Codex Alternative Hypotheses 
+After pattern analysis, check the mode recorded at Phase 0. If **Verify** was selected, dispatch Codex to propose alternative root causes and different hypotheses. Merge Claude's analysis + Codex alternatives into Phase 3 hypothesis testing. If **Takeover** was selected, skip this step (Codex already ran the investigation). If **Skip**, do nothing. Do NOT re-run the consent flow. See **Codex Integration** section below for full details.
+
+#### Graphify Context (Query-only)
+
+**Protocol:** `protocols/graphify.md` | **Mode:** Query-only — no guard, no build prompts.
+
+If `graphify-out/graph.json` exists and the `graphify` CLI is available, check the `graphify.query` preference in `.forge/local.yaml`:
+- `always` → run CLI queries below
+- `never` → skip CLI queries, trace manually
+- `ask` or absent → prompt once before the first query ("Graphify CLI detected. Use graph queries for dependency tracing? (a) Yes (b) Always (c) No (d) Never")
+
+If graph.json is missing OR CLI is unavailable, trace manually. Do not prompt for install or build — debugging should stay fast.
+
+**CLI queries:**
+- `graphify path "[error source]" "[suspected cause]" --graph graphify-out/graph.json` — trace dependency chain from symptom to potential root cause
+- `graphify explain "[unfamiliar component]" --graph graphify-out/graph.json` — understand components encountered during investigation
+- `graphify query "what calls [failing function]" --budget 1000 --graph graphify-out/graph.json` — find all callers of the failing code
+
+**Codex bridge:** Pass graph-traced dependency paths to the Codex verify step below for alternative hypothesis generation.
+
+#### Codex Integration
+**Modes:** Verify or Takeover | **Protocol:** `protocols/codex.md`
+
+- **Verify:** Claude investigates, Codex proposes alternative hypotheses.
+- **Takeover:** Codex investigates root cause, Claude reviews and tests hypotheses.
+
+**When:** After Phase 2 pattern analysis, before forming hypotheses in Phase 3.
+
+**Context to pass:**
+- Path to the file(s) containing the bug
+- Claude's pattern analysis findings (inline summary)
+- Error output / stack trace (inline)
+
+**What Codex reviews:**
+- Alternative hypotheses Claude hasn't considered
+- Different root causes based on different assumptions
+- Similar patterns in other parts of the codebase that might have the same bug
+
+**Prompt focus:** "Given this bug and this pattern analysis, propose alternative root causes. What assumptions might be wrong? What other code paths could produce this symptom? Don't confirm existing analysis — generate new angles."
+
+**Presentation:** Claude's analysis + Codex's alternative hypotheses. Both feed into Phase 3 hypothesis testing.
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down explicitly
+   - Be specific, not vague
+   - The hypothesis must explain ALL observed symptoms
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test the hypothesis
+   - One variable at a time
+   - Do NOT fix multiple things at once
+   - Predict what should happen if your hypothesis is correct
+
+3. **Verify Before Continuing**
+   - Did the test confirm your hypothesis? Yes -> Phase 4
+   - Did it not? Form a NEW hypothesis based on what you learned
+   - Do NOT add more fixes on top of an unconfirmed hypothesis
+
+4. **When You Do Not Know**
+   - Say "I don't understand X" explicitly
+   - Do not pretend to know
+   - Research more: read source code, check documentation, search for the error
+   - Ask the user for additional context if needed
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Write the simplest possible test that demonstrates the bug
+   - It must FAIL before the fix (this proves it tests the right thing)
+   - Automated test if possible, one-off test script if no framework
+   - This test MUST exist before you write the fix
+   - Use `build-tdd` discipline for writing proper failing tests
+
+2. **Implement Single Fix**
+   - Address the ROOT CAUSE identified in Phase 1-3
+   - ONE change at a time
+   - No "while I'm here" improvements
+   - No bundled refactoring
+   - No "let me also fix this other thing"
+
+3. **Verify Fix**
+   - The new test passes
+   - All existing tests still pass
+   - The original reported issue is resolved
+   - No new warnings or errors introduced
+
+4. **If Fix Does Not Work**
+   - STOP
+   - Count: How many fixes have you tried?
+   - If fewer than 3: Return to Phase 1, re-analyze with new information from the failed fix
+   - **If 3 or more: STOP and question the architecture (see step 5)**
+   - Do NOT attempt Fix #4 without architectural discussion
+
+5. **If 3+ Fixes Have Failed: Escalate**
+
+   Before concluding this is an architectural problem, if you have not yet used trace methodology, dispatch the **tracer** subagent now. Multiple failed fixes often indicate a wrong assumption (Lane 3) rather than a wrong architecture.
+
+   **Patterns indicating an architectural problem:**
+   - Each fix reveals new shared state, coupling, or a problem in a different place
+   - Fixes require "massive refactoring" to implement
+   - Each fix creates new symptoms elsewhere
+   - The code path is so tangled that isolating the issue is nearly impossible
+
+   **STOP and question fundamentals:**
+   - Is this pattern fundamentally sound?
+   - Are we sticking with it through sheer inertia?
+   - Should we refactor the architecture instead of continuing to fix symptoms?
+   - Is there a simpler design that would eliminate this class of bugs?
+
+   **Discuss with the user before attempting more fixes.**
+
+   This is NOT a failed hypothesis -- this is a wrong architecture.
+
+6. **After Fix: Record the Lesson**
+   - Invoke `support-gotcha` to record what went wrong
+   - Include: what happened, why, how to prevent it in the future
+   - Tag which skills should incorporate this lesson
+   - This is how the system learns and improves
+
+## STOP Signals
+
+If you catch yourself thinking any of these, or the user says anything similar — **STOP and return to Phase 1:**
+
+| Trigger | What It Means | Action |
+|---|---|---|
+| "Quick fix" / "Just try X" | Guessing, not debugging | Return to Phase 1 |
+| "Add multiple changes at once" | Can't isolate what worked | One change at a time |
+| "Skip the test" | Untested fixes don't stick | Write test first |
+| "One more fix" (after 2+ failures) | 3-fix threshold hit | Question architecture |
+| "The library must be broken" | Almost certainly your code | Verify via docs/context7 |
+| "I see the problem, let me fix it" | Symptoms ≠ root cause | Verify before fixing |
+| "I don't fully understand but this might work" | Incomplete understanding | Research more before proceeding |
+| "Pattern says X but I'll adapt it" | Partial pattern reading | Read the FULL reference first |
+| "The user said it's X so let me fix X" | Unchecked user report | Fact-check first (Phase 0) |
+| User: "Stop guessing" / "Did you check?" | You assumed without evidence | Return to Phase 1 |
+| User: "Think harder" / frustrated tone | Your approach isn't working | Change strategy |
+
+## Integration with the forge Harness
+
+### How Debug Fits in Commands
+
+- `/bugfix` command: invokes `support-debug` as the primary skill
+- `/hotfix` command: invokes `support-debug` with expedited gates (but same four phases)
+- `/feature` command: invokes `support-debug` if build phase encounters issues
+
+### Post-Fix Workflow
+
+After a successful fix:
+
+1. **Invoke support-gotcha** -- Record the lesson
+2. **Update manifest** -- If debugging was part of a feature, update the manifest status
+3. **Check for pattern** -- If this is the 3rd time a similar bug occurred, gotcha system will flag it for promotion to a rule
+
+### Tools for Fact-Checking
+
+When verifying library behavior or API specifications:
+
+- **context7**: Fetch current documentation for any library
+  - `mcp__plugin_context7_context7__resolve-library-id` to find the library
+  - `mcp__plugin_context7_context7__query-docs` to read the docs
+- **Web search**: For recent changes, CVEs, or migration guides
+- **Project dependencies**: Check `package.json`, `pyproject.toml`, etc. for exact versions
+- **Changelogs**: Check if behavior changed between versions
+
+## When Process Reveals No Clear Root Cause
+
+If systematic investigation reveals the issue is truly environmental, timing-dependent, or external:
+
+1. You have completed the process (this is valid)
+2. Document what you investigated and ruled out
+3. Implement appropriate handling (retry logic, timeout, descriptive error message)
+4. Add monitoring/logging for future investigation
+5. Record in `support-gotcha` for awareness
+
+**But:** 95% of "no root cause" cases are incomplete investigation. Be honest about whether you truly exhausted all avenues.
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|---|---|---|
+| **0. Fact-Check** | Verify reported problem, check library docs, confirm environment | Problem confirmed as described (or real issue identified) |
+| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence, trace data flow | Understand WHAT is wrong and WHERE it originates |
+| **2. Pattern** | Find working examples, compare, identify differences | Differences between working and broken are cataloged |
+| **3. Hypothesis** | Form theory, test with minimal change, verify | Confirmed hypothesis or new hypothesis formed |
+| **4. Implementation** | Create failing test, implement single fix, verify all tests pass | Bug fixed, test added, no regressions |
+| **Post-Fix** | Record lesson in support-gotcha, update manifest | Lesson recorded for future prevention |

package/skills/support-dream/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: support-dream
+description: "Use when the user asks to 'consolidate the wiki', 'clean up aiwiki', 'merge duplicate notes', 'prune stale gotchas', or when /evolve runs maintenance. Also auto-fires on phase-close or when context approaches compaction (~85%). Merges aiwiki duplicates, resolves contradictions, refreshes the session index. Output goes to aiwiki/proposed/ for user review — input is never modified."
+---
+
+# Support: Dream (Wiki Consolidation)
+
+## Overview
+
+The `aiwiki/` accumulates noise: raw notes that need to be classified, gotcha files that overlap, conventions that drift, session files that need to be summarized before context is lost. Dream consolidates all of it.
+
+**Core principle:** input store is never modified. Dream produces a NEW reviewable state in `aiwiki/proposed/{dream_id}/`; the user accepts (atomic swap) or rejects (discard).
+
+**Announce at start:** "I'm using the support-dream skill to consolidate `aiwiki/` for [trigger]."
+
+This skill orchestrates wiki consolidation. It dispatches the `dreamer` subagent to do the actual LLM consolidation work. Different providers (forge-local default, anthropic-managed optional) supply different consolidation backends behind the same skill interface.
+
+## When to Use
+
+Three triggers, distinct intents:
+
+| Trigger | Intent | Scope |
+|---|---|---|
+| **Phase close** (Phase 4 (iterate) lock, Phase 5 (codify) lock, Phase 6 (production-build) per-slice close, Phase 7 (deliver) retrospective) | Promote phase outputs into curated wiki state | Subfolders touched by the phase |
+| **PreCompact hook fire** (~85% context utilization) | Consolidate session signal into durable form before lossy compaction | `aiwiki/sessions/{current}` + `aiwiki/raw/` + recently-touched typed pages |
+| **Manual `/dream`** | User-driven cleanup (after major refactor, branch merge, accumulated noise) | User-specified |
+
+**Do NOT skip when:**
+- Phase close — the next phase's work depends on consolidated state
+- PreCompact — fires once before compaction; missing it means session signal is lost on compact
+
+**Do NOT run when:**
+- The wiki has no recent changes (no raw entries, no recent typed-page writes, no session events) — there's nothing to consolidate; the cycle would no-op
+
+## What Dream Does NOT Do
+
+- Does NOT modify `aiwiki/` directly (writes only to `aiwiki/proposed/{dream_id}/`)
+- Does NOT modify `.forge/work/` (manifest is operational state, not knowledge)
+- Does NOT delete or archive accepted typed pages (only the user does, via `forge wiki accept` / `reject`)
+- Does NOT enforce schemas (LINT does that — runs on the proposed output before marking the dream complete)
+- Does NOT promote raw entries on its own judgment if they fail their target schema (flags them in the manifest; user reviews)
+
+## Trigger Flow
+
+### Phase-close trigger
+
+Fired by phase-close hooks (after user emits the phase-lock signal):
+
+1. Skill detects phase-close event (e.g. Phase 4 lock)
+2. Determines scope based on which phase closed (e.g. Phase 4 → `aiwiki/raw/` written during Phase 4 + Phase 4 gotchas/conventions)
+3. Dispatches `dreamer` subagent with scope + provider config
+4. Dreamer produces `aiwiki/proposed/{dream_id}/` + `.dream-manifest.json`
+5. LINT runs on proposed output; results recorded in manifest
+6. Phase-close gate **blocks the next phase** until the user reviews this dream — the next phase reads consolidated wiki state, so it cannot proceed against pending unreviewed proposals
+
+### PreCompact trigger
+
+Fired by forge's existing pre-compact hook (~85% context):
+
+1. Hook calls skill with scope `[aiwiki/sessions/{current}, aiwiki/raw/, recently-touched-typed-pages]`
+2. **Sync prerequisite** — session checkpoint hook has already updated `aiwiki/sessions/{current}.md` with all events. Dream IMPROVES this file; does not produce its existence.
+3. Dispatches `dreamer` subagent
+4. Output to `aiwiki/proposed/{dream_id}/`
+5. LINT runs on proposed output
+6. Native compaction proceeds (does not wait for user review — the consolidated session file is already on disk)
+
+### Manual /dream trigger
+
+User invokes `/dream [scope]`:
+
+1. Skill parses scope (default: full `aiwiki/`; alternatives: `aiwiki/raw/`, `aiwiki/gotchas/`, etc.)
+2. Dispatches `dreamer` subagent
+3. Output to `aiwiki/proposed/{dream_id}/`
+4. LINT runs on proposed output
+5. User reviews via `forge wiki review {dream_id}`
+
+## Inputs (per trigger)
+
+| Source | Always | Phase-close | PreCompact | Manual |
+|---|---|---|---|---|
+| Current `aiwiki/` (typed pages) | ✓ | ✓ | ✓ | ✓ |
+| Page schemas (`aiwiki/schemas/`) | ✓ | ✓ | ✓ | ✓ |
+| `aiwiki/raw/` | ✓ | ✓ | ✓ | ✓ |
+| `aiwiki/sessions/{current}.md` | — | — | ✓ | optional |
+| Recent commits (since last dream) | — | ✓ (since phase start) | ✓ (since session start) | optional |
+| Phase 4 prototype iteration logs | — | ✓ (Phase 4 close only) | — | — |
+| Anthropic Managed Agents session IDs | — | — | — | — (only with `anthropic-managed` provider) |
+
+The dispatch prompt carries the scope; the dreamer subagent reads from disk.
+
+## Outputs
+
+Dream produces a directory `aiwiki/proposed/{dream_id}/` mirroring `aiwiki/` structure, plus a manifest:
+
+`aiwiki/proposed/{dream_id}/.dream-manifest.json`:
+
+```json
+{
+  "dream_id": "2026-05-10-1042-phase4-close",
+  "trigger": "phase-close",
+  "trigger_detail": "Phase 4 lock (feature/auth-refactor)",
+  "scope": ["aiwiki/raw/", "aiwiki/gotchas/2026-05/", "aiwiki/conventions/"],
+  "base_aiwiki_hash": "sha256:a3f2bc1...",
+  "created_at": "2026-05-10T10:42:00Z",
+  "provider": "forge-local",
+  "changed_pages": 3,
+  "new_pages": 1,
+  "deleted_pages": 0,
+  "lint_status": "passed",
+  "lint_warnings": [],
+  "review_status": "pending",
+  "reviewed_at": null,
+  "operations": [
+    {"op": "merge", "files": ["aiwiki/gotchas/2026-05-08-x.md", "aiwiki/gotchas/2026-05-09-x-recur.md"], "into": "aiwiki/gotchas/2026-05-10-x-merged.md", "reason": "duplicate root cause"},
+    {"op": "promote", "from": "aiwiki/raw/2026-05-09-handler-naming.md", "into": "aiwiki/conventions/handler-naming.md", "reason": "matches convention schema"},
+    {"op": "prune", "file": "aiwiki/raw/2026-05-01-investigate-cache.md", "reason": "investigation completed; ADR 0042 captures outcome"}
+  ]
+}
+```
+
+The `operations` log lets the user understand the diff at a glance without reading every file.
+
+## Consolidation pipeline
+
+The actual consolidation work — read aiwiki, identify merges/promotions/prunes, write proposed output, build the manifest — runs in the `dreamer` subagent. The pipeline is canonical in `agents/dreamer.md`; do not duplicate it here. This skill's job is dispatch (decide provider, scope, trigger detail) and post-dispatch handling (run LINT on the proposed output, update the manifest, surface to the user).
+
+## Provider model
+
+The skill dispatches different consolidation backends based on configuration:
+
+### `forge-local` (default)
+
+- Dispatches `dreamer` subagent locally (Claude Code subagent dispatch)
+- Reads from local filesystem (`aiwiki/`, schemas, session events)
+- Writes proposed output locally
+- No cloud dependency; free with subscription
+
+### `anthropic-managed` (optional)
+
+Enabled by `forge config set wiki.dream.provider anthropic-managed` or `FORGE_DREAM_PROVIDER=anthropic-managed`.
+
+- Adapts accepted `aiwiki/` pages into Anthropic memory-store format
+- Calls Anthropic Dreams API with optional Managed Agents session IDs
+- Maps the output store back into typed markdown in `aiwiki/proposed/{dream_id}/`
+- Runs forge LINT on the result (Anthropic output may not match forge schemas; LINT catches drift)
+
+The skill detects the provider from config and dispatches accordingly. The `dreamer` subagent's instructions are provider-aware (see `agents/dreamer.md`).
+
+## CLI Surface
+
+This skill operates the dream side; the user-facing CLI is separate but documented here for completeness:
+
+| Command | Purpose |
+|---|---|
+| `forge wiki status` | List pending dreams (sorted by `created_at`, oldest first) |
+| `forge wiki review [dream_id]` | Open per-page review flow (`$EDITOR` opens diff for each changed file) |
+| `forge wiki accept [dream_id]` | Atomic swap: `aiwiki/proposed/{dream_id}/` contents replace `aiwiki/` per-file. Old contents archived to `.forge/wiki-history/{timestamp}/`. |
+| `forge wiki reject [dream_id] --reason "..."` | Discard. Logged in `.forge/dream-history.jsonl` with reason. |
+
+## Invariants
+
+**Never:**
+- Write to `aiwiki/` directly (only `aiwiki/proposed/{dream_id}/`)
+- Write to `.forge/work/` (operational state, not knowledge)
+- Skip LINT on proposed output
+- Promote a raw entry that fails its target schema without flagging it in the manifest's `lint_warnings`
+- Run a new dream while the current one's `aiwiki/proposed/{dream_id}/` is still pending review (queue them; do not overwrite)
+
+**Always:**
+- Record the `base_aiwiki_hash` so the user can detect if `aiwiki/` changed mid-dream (rare, but possible if a session writes during dream)
+- Include the `operations` log in the manifest so review is one-glance, not file-by-file fishing
+- Keep the proposed output's structure mirroring `aiwiki/` exactly (so atomic swap is per-file safe)
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Modifying `aiwiki/` directly during consolidation | All writes go to `aiwiki/proposed/{dream_id}/`; the swap is the user's action |
+| Writing to `aiwiki/sessions/{current}.md` to "create" the file | Session checkpoint hook creates the file; dream only refines an existing file |
+| Running dream when there's no signal to consolidate | Skip the dream entirely; record nothing |
+| Skipping LINT on proposed output | LINT MUST run; lint warnings go into the manifest, surface during review |
+| Promoting raw entries without reading the target schema | Read `aiwiki/schemas/{type}.md` first; the raw entry must satisfy required sections + frontmatter |
+| Overwriting a previous proposed dream | New dreams create new `{dream_id}` directories; queue accumulates; the user reviews in order |
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | `aiwiki/` (or empty), `aiwiki/schemas/` (the typed-page schemas), provider config (`forge-local` default) |
+| **Produces** | `aiwiki/proposed/{dream_id}/` (mirror structure), `aiwiki/proposed/{dream_id}/.dream-manifest.json` |
+| **Triggers** | Phase-close hooks, pre-compact hook, manual `/dream` |
+| **Updates manifest** | `.forge/dream-history.jsonl` (one append per dream cycle, regardless of accept/reject) |
+
+## Integration
+
+**Called by:**
+- Phase-close hooks (Phase 4 (iterate) lock, Phase 5 (codify) lock, Phase 6 (production-build) per-slice close, Phase 7 (deliver) retrospective)
+- Pre-compact hook (forge's existing context-monitor at ~85%)
+- `/dream` slash command
+
+**Dispatches:**
+- `dreamer` subagent (forge-local provider) — see `agents/dreamer.md`
+- Anthropic Dreams API (anthropic-managed provider) — via the `support-dream` skill's provider adapter
+
+**Pairs with:**
+- `support-wiki-lint` — LINT runs on dream's proposed output
+- `support-context-monitor` — fires the pre-compact trigger
+- `support-gotcha` — provides the gotcha files dream may merge
+- Phase-close hooks for Phase 4 (`iterate-prototype`), Phase 5 (`harden`), Phase 6 (per-slice gates), Phase 7 (deliver) (`support-gotcha` retrospective)
+
+**Forbidden integrations:**
+- Cannot be called from inside another dream (no nested dreams)
+- Cannot be called as a write target by other skills (other skills write to `aiwiki/raw/` or typed pages directly; dream consolidates separately)