@jamie-tam/forge 6.0.0 → 6.2.0

package/hooks/scripts/session-start.sh

@@ -1,12 +1,19 @@
 #!/usr/bin/env bash
 # Session start check: surface promotion-pending gotchas, unresolved hotfix
-# workarounds, and paused work items. Runs as a SessionStart hook — warns
-# loudly via stderr but does not block (Claude Code treats SessionStart exit
-# codes advisorily).
+# workarounds, paused work items, and the latest session handoff. Runs as a
+# SessionStart hook — warns loudly via stderr but does not block (Claude Code
+# treats SessionStart exit codes advisorily).
 #
 # Resolves .forge at the repo root via `git rev-parse --show-toplevel` to match
 # pre-compact.sh and telemetry.sh. Scans `.forge/work/*/` (typed subdirs) and
 # skips `escalated`/`completed` manifests (terminal states).
+#
+# Session handoff: reads the LATEST aiwiki/sessions/*.md (by mtime, within
+# 7 days) and surfaces:
+#   - one-line summary (focus + status)
+#   - any "Status: unconsumed" Checkpoints directives the next agent should act on
+# The session file is created lazily by pre-compact.sh / /wrap / /dream / harden —
+# NOT by this hook (avoids empty-file noise from trivial 30-second sessions).
 
 set -u
 
@@ -15,6 +22,38 @@ FORGE_DIR="$PROJECT_ROOT/.forge"
 GLOBAL_GOTCHAS="$HOME/.claude/gotchas"
 WARNINGS=""
 
+# Latest session handoff: find the most recently modified session file within
+# the last 7 days and surface its focus + any unconsumed checkpoints.
+if [ -d "$PROJECT_ROOT/aiwiki/sessions" ]; then
+  LATEST_SESSION="$(find "$PROJECT_ROOT/aiwiki/sessions" -maxdepth 1 -type f -name '*.md' \
+    ! -name 'INDEX.md' ! -name 'CLAUDE.md' \
+    -mtime -7 -print0 2>/dev/null \
+    | xargs -0 stat -f '%m %N' 2>/dev/null \
+    | sort -rn | head -1 | cut -d' ' -f2-)"
+
+  if [ -n "$LATEST_SESSION" ] && [ -f "$LATEST_SESSION" ]; then
+    SESSION_NAME="$(basename "$LATEST_SESSION" .md)"
+    FOCUS="$(grep -m1 '^focus:' "$LATEST_SESSION" 2>/dev/null | sed 's/^focus:[[:space:]]*//')"
+    STATUS="$(grep -m1 '^status:' "$LATEST_SESSION" 2>/dev/null | sed 's/^status:[[:space:]]*//')"
+    # Count active directives by the exact bold-header pattern. Loose patterns
+    # like 'Status: unconsumed' false-positive on prose mentions of the
+    # mark-consumed protocol (surfaced during dogfood, 2026-05-18).
+    # `grep -c` already prints "0" when no matches; the `|| true` swallows the
+    # exit-1 without appending a second "0" (which would break the -gt check
+    # below — also dogfood-found).
+    UNCONSUMED_COUNT="$(grep -c '^\*\*Dream directive (unconsumed):\*\*$' "$LATEST_SESSION" 2>/dev/null || true)"
+    UNCONSUMED_COUNT="${UNCONSUMED_COUNT:-0}"
+
+    WARNINGS="${WARNINGS}SESSION HANDOFF: previous session ${SESSION_NAME} (status: ${STATUS:-unknown}, focus: ${FOCUS:-unset}).\n"
+    WARNINGS="${WARNINGS}  File: ${LATEST_SESSION}\n"
+    if [ "$UNCONSUMED_COUNT" -gt 0 ]; then
+      WARNINGS="${WARNINGS}  HARD-INTERRUPT: ${UNCONSUMED_COUNT} unconsumed checkpoint directive(s) — read ## Checkpoints in this file, act on the directive (typically: invoke support-dream), then mark the entry consumed before doing other work.\n"
+    elif [ "${STATUS:-}" = "active" ]; then
+      WARNINGS="${WARNINGS}  Previous session left active (no /wrap fired). Read ## Files touched / ## Next steps for context, then continue or run /wrap to finalize.\n"
+    fi
+  fi
+fi
+
 # Hard-interrupt: promotion-pending gotchas.
 # When `support-gotcha` auto-drafts a proposed rule at the 3rd occurrence,
 # the gotcha's INDEX status column flips to `promotion-pending` and a
@@ -52,7 +91,7 @@ if [ -d "$PROJECT_ROOT/aiwiki/gotchas" ]; then
 
   if [ -n "$HOTFIX_FILES" ]; then
     COUNT=$(echo "$HOTFIX_FILES" | wc -l | tr -d ' ')
-    WARNINGS="${WARNINGS}WARNING: ${COUNT} unresolved hotfix workaround(s) in aiwiki/gotchas/. Run /evolve or address these before starting new work.\n"
+    WARNINGS="${WARNINGS}WARNING: ${COUNT} unresolved hotfix workaround(s) in aiwiki/gotchas/. Run /forge-evolve or address these before starting new work.\n"
   fi
 fi
 

package/hooks/scripts/telemetry.sh

@@ -5,6 +5,12 @@
 #
 # Output: .forge/state/telemetry.jsonl (one JSON object per line)
 #
+# Each record now includes work_id when there's an in-progress manifest.
+# gate-enforcer.sh filters by work_id so a stale invocation from another work
+# item no longer satisfies a fresh gate — closes the cross-work-item bypass
+# vector flagged in v6.1-beta audit P0-5. Records with no in-progress work
+# omit the work_id field (null on the consuming side).
+#
 # Note: the subagent-dispatch tool was renamed `Agent` → `Task` (canonical name
 # in current Claude Code releases). Both names are accepted here for backward
 # compatibility with existing telemetry written before the rename; `Task` is
@@ -24,17 +30,41 @@ INPUT=$(cat)
 TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
 TIMESTAMP=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
 
+# Locate the in-progress work item (if any). Same scan pattern used by
+# pre-compact.sh and session-start.sh. Cost is sub-millisecond — a small
+# loop over a handful of manifest files — well within PostToolUse overhead.
+ACTIVE_WORK=""
+if [ -d "$PROJECT_ROOT/.forge/work" ]; then
+    for manifest in "$PROJECT_ROOT/.forge/work"/*/*/manifest.yaml; do
+        if [ -f "$manifest" ] && grep -q 'status: in-progress' "$manifest" 2>/dev/null; then
+            WORK_NAME="$(basename "$(dirname "$manifest")")"
+            WORK_TYPE="$(basename "$(dirname "$(dirname "$manifest")")")"
+            ACTIVE_WORK="$WORK_TYPE/$WORK_NAME"
+            break
+        fi
+    done
+fi
+
+# work_id field — emitted only when we resolved an in-progress manifest.
+# Records without work_id naturally fail the enforcer's per-work-id filter,
+# which is the desired behavior (an invocation that happened with no
+# work-in-progress context cannot satisfy a gate on a specific work item).
+WORK_FIELD=""
+if [ -n "$ACTIVE_WORK" ]; then
+    WORK_FIELD=",\"work_id\":\"$ACTIVE_WORK\""
+fi
+
 # Extract relevant fields based on tool type.
 # Task and Agent share input shape (subagent_type + description); accept either.
 case "$TOOL_NAME" in
   Skill)
     SKILL_NAME=$(echo "$INPUT" | jq -r '.tool_input.skill // "unknown"')
-    echo "{\"timestamp\":\"$TIMESTAMP\",\"type\":\"skill\",\"name\":\"$SKILL_NAME\"}" >> "$TELEMETRY_FILE"
+    echo "{\"timestamp\":\"$TIMESTAMP\",\"type\":\"skill\",\"name\":\"$SKILL_NAME\"$WORK_FIELD}" >> "$TELEMETRY_FILE"
     ;;
   Task|Agent)
     AGENT_TYPE=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // "unknown"')
     DESCRIPTION=$(echo "$INPUT" | jq -r '.tool_input.description // ""')
-    echo "{\"timestamp\":\"$TIMESTAMP\",\"type\":\"agent\",\"name\":\"$AGENT_TYPE\",\"description\":\"$DESCRIPTION\"}" >> "$TELEMETRY_FILE"
+    echo "{\"timestamp\":\"$TIMESTAMP\",\"type\":\"agent\",\"name\":\"$AGENT_TYPE\",\"description\":\"$DESCRIPTION\"$WORK_FIELD}" >> "$TELEMETRY_FILE"
     ;;
 esac
 

package/hooks/templates/CLAUDE.md.template

@@ -19,12 +19,13 @@ project:
 
 New to this project? Describe your goal in plain English — forge auto-routes via skills, OR invoke a command directly:
 
-- `/forge` — one-screen orientation: what's installed, what's in flight, what to run next
+- `/discover` — one-screen orientation: what's installed, what's in flight, what to run next
 - `/setup` — detect your stack and install matching language rules (run this first)
 - `/feature <name>` — develop a feature end-to-end with quality gates
 - `/bugfix <name>` — systematic debugging with root-cause analysis
 - `/refactor <name>` — restructure code without new functionality
-- `/task-force <list>` — parallel agents for a punch list of ad-hoc tasks
+- `/note <text>` — capture an ad-hoc research note or brainstorm to `aiwiki/raw/`
+- `/parallel <list>` — parallel agents for a punch list of ad-hoc tasks
 - `/validate` — check skill/rule/command consistency
 
 Operational state lives in `.forge/state/`; project knowledge in `aiwiki/`.
@@ -36,7 +37,9 @@ Claude Code's auto-memory (v2.1.59+) lives in `~/.claude/projects/<project>/memo
 
 This project uses **forge** as its development workflow. Every session should follow it: route via skills, use the `/feature`, `/bugfix`, `/refactor` etc. commands, and keep work artifacts in `.forge/`.
 
-System structure — skills (prefix-grouped), commands, `.forge/` layout, context recovery — lives in **`.claude/rules/common/forge-system.md`** (always-on rule, auto-loaded every session).
+Knowledge accumulates in **`aiwiki/`** — typed pages (`decisions/`, `gotchas/`, `conventions/`, `architecture/`, `sessions/`) read by subagents during their work, plus `raw/` for free-form research and brainstorm capture (use `/note <text>`). The `wiki-lint` hook validates every `aiwiki/**` write against its schema, and `support-dream` consolidates raw → typed at phase-close and PreCompact (~85% context). Operational state (manifests, telemetry) stays separate in **`.forge/`**.
+
+System structure — skills (prefix-grouped), commands, `.forge/` layout, `aiwiki/` integration, context recovery — lives in **`.claude/rules/common/forge-system.md`** (always-on rule, auto-loaded every session).
 
 <!-- FORGE:END -->
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jamie-tam/forge",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "description": "AI Development Life Cycle — structured AI-assisted development with quality gates, feature manifests, and agent coordination",
   "type": "module",
   "bin": {

package/references/common/phases.md

@@ -24,15 +24,17 @@ Phases are **defaults, not requirements**. The work-item manifest at `.forge/wor
 
 Commands (`/feature`, `/bugfix`, `/greenfield`, `/refactor`) ask the AI to propose phase skips at preflight; the user confirms. Forcing all seven on every work item is wrong shape with current model capability.
 
-## Phase-conditional rules
+## Which rules apply when
 
-The following rules apply from Phase 5 (codify) onward, per their own phase headers:
+All eight common rules auto-load every session except `testing.md`, which is paths-conditional (loads only on test files and `src/` code).
 
-- `rules/common/testing.md` — TDD becomes mandatory
-- `references/common/quality-gates.md` — full gate set (the rule-tier stub at `rules/common/quality-gates.md` fans out to this reference)
-- `rules/common/git-workflow.md` — conventional commits + branch hygiene
+The content of the following rules is **scoped to Phase 5+ work** even though they auto-load — agents reading them should treat their guidance as applying from codify onward:
 
-Phases 1–4 operate under the safety-floor rules only (`rules/common/security.md`, `guardrails.md`, `verification.md`, `skill-selection.md`).
+- `rules/common/testing.md` — TDD becomes mandatory at Phase 5; Phases 1–4 (prototype work) are exempt because mock-heavy tests under-catch wiring bugs (see `skills/build-tdd` and `skills/iterate-prototype`)
+- `references/common/quality-gates.md` — full gate set (the rule stub at `rules/common/quality-gates.md` fans out to this reference)
+- `rules/common/git-workflow.md` — conventional commits + branch hygiene; relevant once Phase 5 codify produces code-shaped artifacts
+
+The other five rules (`security`, `guardrails`, `verification`, `skill-selection`, `forge-system`) apply across all phases.
 
 ## How to reference this in agent/skill files
 

package/references/common/skill-authoring.md

@@ -1,6 +1,6 @@
 # Skill Authoring Guidelines
 
-Principles for creating and modifying skills. Reference this when using the skill-creator or `/evolve`.
+Principles for creating and modifying skills. Reference this when using the skill-creator or `/forge-evolve`.
 
 ## Atomic Single-Responsibility
 

package/rules/common/forge-system.md

@@ -1,5 +1,5 @@
 ---
-description: Forge system structure — skills (prefix-grouped), commands (orchestrate skills), .forge/ directory layout, context recovery. Auto-loaded every session so agents know the system they're operating in.
+description: Forge system structure — skills (prefix-grouped), commands (orchestrate skills), .forge/ directory layout, aiwiki/ knowledge layer, context recovery. Auto-loaded every session so agents know the system they're operating in.
 ---
 
 # Forge System
@@ -23,14 +23,15 @@ v6 also adds phase skills: concept-slides, build-wireframe, build-prototype, ite
 
 | Command | When to use |
 |---------|------------|
-| `/forge` | One-screen discovery — installed capabilities, active work, suggested next |
+| `/discover` | One-screen discovery — installed capabilities, active work, suggested next |
 | `/setup` | Detect stack, install matching language rules, and fill the project profile |
 | `/feature` | Full feature development |
 | `/greenfield` | New project from zero |
 | `/bugfix` | Fix a bug |
 | `/refactor` | Improve existing code |
 | `/hotfix` | Emergency production fix |
-| `/evolve` | Improve the forge system itself |
+| `/note <text>` | Capture an ad-hoc research note or brainstorm to `aiwiki/raw/{date}.md` |
+| `/forge-evolve` | Improve the forge system itself |
 | `/validate` | Check skill consistency |
 
 ## .forge/ Directory
@@ -43,16 +44,73 @@ v6 also adds phase skills: concept-slides, build-wireframe, build-prototype, ite
     refactor/{name}/           # manifest, codebase analysis, tasks, test results
     hotfix/{name}/             # manifest, minimal debug, smoke tests
     greenfield/{name}/         # manifest + full project scaffold artifacts
-  state/                       # Runtime state (notepad.md, telemetry, dream history)
+  state/                       # Runtime state (telemetry, dream history). Per-session handoff lives in aiwiki/sessions/ — see below.
 ```
 
-Project knowledge (ADRs, gotchas) lives under `aiwiki/` — see `aiwiki/decisions/` and `aiwiki/gotchas/`. The `.forge/` directory retains operational state only (manifests, telemetry, dream history).
+The `.forge/` directory retains operational state only (manifests, telemetry, dream history). Project knowledge lives in `aiwiki/` (next section).
 
 Work items are identified by `{type}/{name}` — names may collide across types.
 
+## aiwiki/ (knowledge layer)
+
+`aiwiki/` accumulates lasting project knowledge — separate from `.forge/` which is operational state. Subagents read these pages to inform their work, so the typed pages have schemas enforced by `wiki-lint`.
+
+| Page type | Purpose | Written by |
+|---|---|---|
+| `decisions/` | ADRs — architecture decisions + rationale | `plan-brainstorm`, `harden`, manual |
+| `gotchas/` | Recurring failure modes with reproducible fixes | `iterate-prototype`, `quality-code-review`, manual |
+| `conventions/` | Established patterns in this codebase | `iterate-prototype`, `harden`, manual |
+| `architecture/` | Component maps, sequence diagrams | `harden`, manual |
+| `sessions/` | Per-session handoff: `## Checkpoints` event log (pre-compact, /dream) + index sections (Files touched, Decisions, Gotchas, Open questions, Next steps) filled by `/wrap`. Filename `{date}-{session_id_short}.md`. Lazy-created by first writer in the session. | `hooks/scripts/pre-compact.sh`, `/wrap`, `/dream`, `harden` |
+| `oracles/` | Prototype behavior snapshots that Phase 6 production code must reproduce (setup → trigger → assertions) | `harden` (Step 2.5) |
+| `raw/` | Append-only research/brainstorm capture (no schema) | `/note <text>`, manual |
+
+**Auto-capture during phases.** `iterate-prototype` (Phase 4) writes gotchas and conventions surfaced during prototype iteration. Phases 1 (concept) and 2 (wireframe) have **no auto-capture** — use `/note <text>` to land research/brainstorm in `aiwiki/raw/{date}.md`.
+
+**Lint** (`wiki-lint` PostToolUse hook). Fires on every `aiwiki/**.md` write (Edit/Write/MultiEdit). Validates frontmatter, required H2 sections, line caps, citation hash drift, and possible-secret patterns in cited content against the page's schema. Skips `aiwiki/raw/` (no schema) and `aiwiki/proposed/` (lint runs there separately at dream-complete). Findings surface on stderr — non-blocking, but the next edit should address them.
+
+**Dream** (`support-dream` skill). Async consolidation:
+- **PreCompact** (~85% context): consolidates `aiwiki/raw/` + recently-touched typed pages before lossy compaction. Also refines the active session file's `## Checkpoints` event log (if it exceeds ~10 entries) and pre-populates index sections from git diff. The pre-compact hook itself writes an unconsumed dream directive to the session file's checkpoints; the post-compact agent reads it and dispatches this skill.
+- **Phase-close** (Phase 4/5/6/7 lock): promotes phase outputs into curated wiki state. The next phase **blocks** until the user reviews the proposed dream.
+- **Manual `/dream`**: user-driven cleanup.
+
+Dream outputs to `aiwiki/proposed/{dream_id}/` — input store is never modified. User atomically accepts (swap) or rejects (discard) via `forge wiki accept` / `reject`.
+
+### When the AI should write to aiwiki
+
+The discipline is **selectivity, not abstention.** AI writes happen routinely — `support-gotcha`, `iterate-prototype` (via `prototype-builder`), and `harden` all write to typed pages directly during their normal operation, and the pre-compact hook + `/wrap` write to `aiwiki/sessions/`. Wiki-lint validates schema on every write; the user can edit or delete any page after the fact. The rule is what content qualifies — not whether AI can write.
+
+Per-folder discipline:
+
+| Folder | Who writes | Gate |
+|---|---|---|
+| `raw/` | **User only**, via `/note <text>` | The user is the gate. AI does NOT decide to write conversational asides to raw on its own. |
+| `decisions/` `gotchas/` `conventions/` `architecture/` `oracles/` | AI writes directly via `support-gotcha`, `iterate-prototype`, `harden`, code-review subagents | Schema (enforced by wiki-lint) + durability test (below). User can edit/delete after-the-fact. |
+| `sessions/` | `pre-compact.sh` (Checkpoints) + `/wrap` (index sections) + `harden` (codify-time session entry) | Schema. `/wrap` confirms with user before setting `status: done`. |
+| `proposed/` | `dreamer` subagent only (via `support-dream`) | User reviews each proposal via `forge wiki ui` / `forge wiki review` and atomically accepts or rejects. |
+
+Three durability rules that override any temptation to over-capture:
+
+1. **Never write speculation, conversation history, or "we might want to revisit this" notes.** This is the strongest rule. Wiki pages answer recurring questions; conversational asides do not. Speculation goes to raw via `/note` (user-gated), not to typed pages.
+2. **Typed pages need durable, reusable knowledge.** ADRs go to `decisions/` only when the choice is finalized AND hard-to-reverse (architectural, public-surface, security, schema). Gotchas to `gotchas/` only when the failure mode is reproducible with a concrete fix. Conventions to `conventions/` only when the pattern is established across multiple sites. If the knowledge isn't yet durable, it doesn't belong in a typed page.
+3. **Raw is `/note`-only.** Ad-hoc research, half-formed thoughts, deferred decisions, comparison notes all go to `aiwiki/raw/` — and ONLY when the user explicitly invokes `/note <text>`. The AI does not autonomously decide what becomes raw content.
+
+When a typed-page-worthy insight emerges mid-conversation (e.g., "this is a real gotcha"), write it to the correct typed page if it meets that page's durability test. When the durability is uncertain, ask the user instead of speculating.
+
+**Session-end handoff.** Forge provides `/wrap` for explicit session-end capture. Run it at a natural session boundary: it fills the active session file's index sections (Files touched / Decisions made / Gotchas surfaced / Open questions / Next steps) and sets `status: done`. The next `SessionStart` hook surfaces the latest session's focus and any unconsumed `## Checkpoints` directives. If `/wrap` isn't invoked, the session file (if pre-compact created one) stays `status: active` — `SessionStart` will surface it as unfinalized so the next session can pick up. The AI should OFFER to run `/wrap` before a long break or context shift; never silently fabricate a session summary.
+
 ## Context Recovery
 
-If `.forge/state/notepad.md` exists, read it FIRST before doing anything else.
+On session start or after compaction, recovery state lives in **two places**, in priority order:
+
+1. **`aiwiki/sessions/{date}-{session_id_short}.md`** — the per-session handoff file. Read this FIRST.
+   - The `## Checkpoints` section is an append-only event log. Any entry with header `**Dream directive (unconsumed):**` is an action item for the current agent (typically: invoke `support-dream`). After acting, change the header from `(unconsumed)` to `(consumed at {ISO-timestamp})`. The `session-start.sh` hook counts active directives by matching the bold header literally — flipping the header is what makes the count accurate (dogfood-validated 2026-05-18).
+   - The index sections (`## Files touched` / `## Decisions made` / `## Gotchas surfaced` / `## Open questions` / `## Next steps`) describe the prior session's work. If `status: done`, the file was `/wrap`'d. If `status: active`, the prior session didn't run `/wrap` — surface the file as in-progress context.
+2. **The active manifest** (`.forge/work/*/*/manifest.yaml` with `status: in-progress`). Read after the session file to anchor on the work item's current phase and gate state.
+
+`SessionStart` hook (`hooks/scripts/session-start.sh`) automatically surfaces the latest session file's focus + any unconsumed checkpoints on stderr. The agent should still re-read the file's full content when acting on a directive.
+
+**Notepad deprecated.** Earlier versions wrote recovery state to `.forge/state/notepad.md`. v6.2 consolidated session recovery into `aiwiki/sessions/{date}-{session_id_short}.md`. If a legacy `.forge/state/notepad.md` exists from an older install, it's safe to delete — nothing reads or writes it anymore.
 
 ## Rules
 

package/rules/common/quality-gates.md

@@ -6,6 +6,8 @@ description: Gate-state names and pass criteria summary — auto-loaded every se
 
 Gates block phase transitions until criteria are met. See [references/common/quality-gates.md](../../references/common/quality-gates.md) for the full gate-set tables, pass criteria, and fail actions.
 
+**Enforcement.** `gate-enforcer.sh` (PreToolUse hook) blocks manifest writes that set `gate-passed: true` unless the gate's required skill/agent (per `hooks/config/gate-requirements.json`) was invoked **for this work item**. The check is `work_id`-scoped: the enforcer extracts `work_id` from the edited manifest's path (`.forge/work/{type}/{name}/manifest.yaml`) and filters `.forge/state/telemetry.jsonl` to records matching that work_id. Stale invocations from another work item — or from before the work_id field was added (legacy records) — do not satisfy fresh gates. After upgrade from a pre-work_id version, re-invoke any required skill once to write a tagged telemetry record.
+
 Gate names (per `hooks/config/gate-requirements.json`):
 - code-review-final
 - code-review (per-slice)

package/skills/build-prototype/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build-prototype
-description: "Use to scaffold a working POC from a locked wireframe. Produces a runnable Vite + React + TS app at pocs/{name}-prototype/ with seed data, in-memory state, and screens that mirror the wireframe states. The prototype is the verification surface for concept + UX before any production code is written."
+description: "Use to scaffold a working POC from a locked wireframe — triggered by phrases like 'build the prototype', 'scaffold the POC', 'wireframe is locked, start the prototype', 'turn the wireframe into something I can run', 'make it interactive', or by the wireframe-lock event in /feature and /greenfield (Phase 2 → Phase 3 transition). Produces a runnable Vite + React + TS + Tailwind + Zustand app at pocs/{name}-prototype/ with seed data, in-memory state, and screens mirroring the wireframe's locked states. The prototype is the verification surface for concept + UX before any production code is written. Skip if the wireframe is not locked (run build-wireframe first), if a prototype already exists at the target path (use iterate-prototype for changes), or if the work is production code under TDD (use build-tdd at Phase 6)."
 ---
 
 # Build Prototype
@@ -15,7 +15,7 @@ Once a wireframe is locked, the prototype turns it into something the user can r
 
 ## When to Use
 
-- Phase 4 of a prototype-driven flow (after wireframe is locked, before Phase 5 codification)
+- Phase 3 of a prototype-driven flow (after wireframe is locked, before Phase 4 iteration and Phase 5 codification)
 - For `/feature` on existing apps: scaffold a `pocs/{feature-name}-prototype/` mini-prototype branch of the existing app's tech stack — same skill, smaller scope
 - Ad-hoc when a wireframe is mature enough to validate via running code
 
@@ -176,7 +176,7 @@ Capture findings in `pocs/{name}-prototype/.forge/feedback.md` if there's any dr
 
 ### Step 5: side-effect capture during iteration
 
-Phase 4 is also when real gotchas + conventions emerge. During iteration:
+Phase 3 (prototype build) and Phase 4 (iteration) are when real gotchas + conventions emerge. During the build and iteration cycles:
 
 - **Gotchas**: every time prototype-builder hits a state-management surprise, library quirk, framework mounting issue, or type-system pothole, write to `aiwiki/gotchas/{date}-{slug}.md` per the gotcha schema. The wiki-lint hook validates on save.
 - **Conventions**: when patterns settle (file naming, import order, state-shape conventions, design-token usage), write to `aiwiki/conventions/{slug}.md`. The `prototype-reviewer` flags new conventions emerging across iteration cycles.
@@ -249,7 +249,7 @@ Document the choice in `pocs/{name}-prototype/README.md` so Phase 5 codification
 
 | Caller | When |
 |---|---|
-| Wireframe-lock event in `/feature` and `/greenfield` | Phase 3 → Phase 4 transition |
+| Wireframe-lock event in `/feature` and `/greenfield` | Phase 2 → Phase 3 transition |
 | Manual invocation | When a wireframe is mature enough to verify via running code |
 
 | Dispatches | For |

package/skills/build-tdd/SKILL.md

@@ -67,6 +67,20 @@ Do not ask the user. The decision was persisted at task decompose handoff.
 
 When architecture artifacts exist (from `plan-architecture` or `harden`), use them to set unit-test expectations for shapes, constraints, and error behavior. Treat those contracts as the source of truth for assertions at the unit boundary. Integration tests at boundaries identified by `harden`'s slice graph are required per the Wiring Coverage subsection above — they are not optional even when the task description omits them.
 
+## Oracle Satisfaction
+
+When `harden` (Phase 5) ran, it captured prototype behavior as integration-test oracles at `aiwiki/oracles/{slug}.md` — one per slice or subsystem. These are the load-bearing contract: production code must reproduce the oracle's `Setup → Trigger → Assertions`. They close the wiring gap that mock-heavy unit tests miss (the Flux/REACH dogfood signal that drove v6).
+
+**Before writing the first RED test for a slice:**
+
+1. Read every oracle whose `slug` or `prototype_path` matches the slice being built (the slice graph entry produced by harden references its oracles).
+2. For each oracle, design at least one test that exercises its `Setup → Trigger → Assertions`. That test counts as the boundary integration test for Wiring Coverage above — so the oracle test and the wiring test are usually the same test.
+3. If the slice crosses a wiring boundary (CLI ↔ filesystem, process exec, manifest I/O, external services) and **no oracle exists for that boundary**, halt and surface to the user. Do NOT invent oracles inline; do NOT proceed against an empty oracle directory. Missing oracles mean harden has not closed — re-run harden to capture them, or surface to the user that the slice is being built without a verified prototype contract.
+
+When this skill dispatches the **builder** subagent (manifest's `execution.mode: subagent`), the agent enforces the same discipline (see [agents/builder.md](../../agents/builder.md) "Oracles Are Load-Bearing"). When running inline, the orchestrator (this skill) is responsible — load the oracles before the first RED.
+
+If `phase_plan.codify: skipped` for this work item (typical for trivial bugfixes that bypass harden), no oracles are expected — note the skip in the work-item notes and proceed.
+
 ## Codex Integration
 
 **Mode:** Delegate | **Protocol:** `protocols/codex.md`

package/skills/concept-slides/SKILL.md

@@ -15,7 +15,7 @@ A concept deck is the cheapest artifact in the pipeline. It exists to verify the
 
 ## When to Use
 
-- Phase 2 of a prototype-driven flow (after discovery, before wireframing)
+- Phase 1 of a prototype-driven flow (after discovery, before wireframing)
 - For `/feature` on existing apps: a 1-3 slide mini-deck — what the feature is, where it sits, the visual sketch. Often a single slide.
 - Ad-hoc when a user wants to put a concept on paper before building anything
 
@@ -46,8 +46,8 @@ The deck is rendered with `marp` and previewed in HTML so the user can click thr
 
 ## What concept-slides does NOT produce
 
-- A wireframe (Phase 3 deliverable; uses `build-wireframe` skill)
-- A prototype (Phase 4 deliverable; uses `build-prototype` skill)
+- A wireframe (Phase 2 deliverable; uses `build-wireframe` skill)
+- A prototype (Phase 3 deliverable; uses `build-prototype` skill)
 - An architecture doc (Phase 5 deliverable; uses `harden`)
 - A finalized pitch deck (use `marp-slides` directly for finalized presentations)
 
@@ -58,7 +58,7 @@ If the user asks for "a real deck for the leadership pitch," use `marp-slides` w
 | Source | Required | Purpose |
 |---|---|---|
 | Rough concept brief from the user | yes | One-sentence to one-paragraph description of what's being built |
-| Discovery output (if existing repo) | if Phase 1 ran | Codebase conventions, existing UX patterns to align with |
+| Discovery output (if existing repo) | if discovery ran | Codebase conventions, existing UX patterns to align with |
 | Reference decks the user likes | optional | Style/composition reference (links or paths) |
 
 ## Process
@@ -119,13 +119,13 @@ Re-dispatch the subagent with the feedback as part of the prompt; rewrite the de
 
 ### Step 5: lock
 
-When the user emits "concept locked" (or equivalent), the phase closes. The locked deck is the input to Phase 3 (`build-wireframe`).
+When the user emits "concept locked" (or equivalent), the phase closes. The locked deck is the input to Phase 2 (`build-wireframe`).
 
 Update the manifest at `.forge/work/{type}/{name}/manifest.yaml`:
 - `artifacts.concept.deck_path: decks/{name}/slides.md`
 - `artifacts.concept.locked_at: <ISO-8601 timestamp>`
 
-Presence of `artifacts.concept.locked_at` is the lock signal that Phase 3 (`build-wireframe`) reads to confirm the concept is locked before proceeding.
+Presence of `artifacts.concept.locked_at` is the lock signal that Phase 2 (`build-wireframe`) reads to confirm the concept is locked before proceeding.
 
 ## Visual sketch guidance
 
@@ -146,7 +146,7 @@ Avoid:
 | Mistake | Fix |
 |---|---|
 | Treating the deck as a finalized pitch | It's a draft; lower the polish bar to "sketch-grade" |
-| Embedding real UI mockups | Move that to Phase 3 wireframe; sketches in the deck are boxes-and-arrows |
+| Embedding real UI mockups | Move that to Phase 2 wireframe; sketches in the deck are boxes-and-arrows |
 | Producing a 30-slide deck | Cap at 15 for full products, 3 for features. Cut or split. |
 | Skipping the "out of scope" slide | The deferral list IS the spec — what NOT to build is as important as what to build |
 | Iterating with the user before the first render | Render first, get feedback against something concrete; don't iterate against imagined slides |
@@ -158,7 +158,7 @@ Avoid:
 - Build a polished marketing deck under this skill (different intent — use `marp-slides` directly)
 - Skip the "out of scope" slide — defining what's NOT built is half the value
 - Iterate without rendering — text-only edits invite imaginary feedback
-- Carry a draft to Phase 3 without an explicit user lock
+- Carry a draft to Phase 2 without an explicit user lock
 
 **Always:**
 - Render to HTML and let the user click through — that's the iteration surface
@@ -172,13 +172,13 @@ Avoid:
 | **Requires** | User brief, target output path, optional discovery output |
 | **Produces** | `decks/{name}/slides.md` (marp source) + `decks/{name}/slides.html` (rendered preview) |
 | **Updates manifest** | `artifacts.concept.{deck_path, locked_at}` |
-| **Feeds into** | `build-wireframe` (Phase 3 — wireframe extends the visual sketches into clickable HTML) |
+| **Feeds into** | `build-wireframe` (Phase 2 — wireframe extends the visual sketches into clickable HTML) |
 
 ## Integration
 
 | Caller | When |
 |---|---|
-| Phase 2 of `/feature` and `/greenfield` | Default flow entry point for prototype-driven work |
+| Phase 1 of `/feature` and `/greenfield` | Default flow entry point for prototype-driven work |
 | Manual invocation | When a concept needs sketching outside a workflow |
 
 | Dispatches | For |
@@ -188,5 +188,5 @@ Avoid:
 | Pairs with | For |
 |---|---|
 | `marp-slides` (user-level skill) | Underlying rendering engine — concept-slides specializes the format |
-| `build-wireframe` | Phase 3 successor — wireframer reads the locked deck as input |
+| `build-wireframe` | Phase 2 successor — wireframer reads the locked deck as input |
 | `discover-codebase-analysis` | If existing repo, supplies UX/convention context |

package/skills/deliver-deploy/SKILL.md

@@ -298,7 +298,16 @@ VERDICT: Ready to deploy
 3. **Trigger Post-Deploy Skills**
    - If documentation needs updating, flag for `deliver-onboarding`
    - If any issues were encountered during deploy, invoke `support-gotcha`
-   - If deployment revealed process improvements, note for `/evolve`
+   - If deployment revealed process improvements, note for `/forge-evolve`
+
+4. **Retrospective dream (Phase 7 auto-fire on lock).** After writing `artifacts.deliver.locked_at`, invoke the **support-dream** skill to consolidate the full feature's wiki accumulation. This is the last consolidation pass for the feature — gotchas, conventions, and any deploy-time learnings get merged into the durable wiki state before the manifest closes.
+   - **scope:** `aiwiki/raw/`, `aiwiki/gotchas/`, `aiwiki/conventions/`, `aiwiki/sessions/` (any subfolder touched during this feature's lifetime)
+   - **trigger:** `phase-close`
+   - **trigger_detail:** `"Phase 7 (deliver) retrospective — {feature/name}"`
+
+   Surface the dream id + review path to the user. The feature manifest's `status: completed` transition should wait until the retrospective dream is reviewed — this is the consolidation pass the next feature's `discover-codebase-analysis` will read from.
+
+   **Skip when:** no `aiwiki/` writes occurred during this feature (rare — most non-trivial features produce at least one gotcha or convention).
 
 ## Rollback Procedures
 

package/skills/harden/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: harden
-description: "Use after a working prototype is locked and the user says 'codify', 'harden', 'ready to productionize', 'extract decisions', 'time to build for real', or runs /feature past the prototype phase. Extracts architecture, ADRs, design system, slice graph, and convention/gotcha promotions FROM the working prototype — does not invent them. Skip if prototype is still iterating or has been abandoned — re-iterate or restart instead."
+description: "Use after a working prototype is locked and the user says 'codify', 'harden', 'ready to productionize', 'extract decisions', 'time to build for real', or runs /feature past the prototype phase. Extracts architecture, ADRs, design system, slice graph, and convention/gotcha promotions FROM the working prototype — does not invent them. Skip if prototype is still iterating — re-iterate or restart instead."
 ---
 
 # Harden
@@ -48,7 +48,7 @@ The expected total is short: ~200-400 lines across all architecture files combin
 - Does NOT run gates (LINT runs on the wiki output; reachability runs on production code later)
 - Does NOT modify the prototype (it's the source of truth — leave it alone)
 - Does NOT pre-promote raw entries from `aiwiki/raw/` to typed pages (dream's job at phase close)
-- Does NOT skip the adversarial-review step on ADRs — every production ADR is reviewed inline at Step 2 (the dedicated `/second-opinion` slash command + `support-second-opinion` skill are *planned, not yet implemented*; until they ship, harden inlines the review pass and records reviewer, objections, resolutions, verdict in the ADR `review:` block before promoting to `accepted`)
+- Does NOT skip the adversarial-review step on ADRs — every production ADR is reviewed inline at Step 2: harden runs the review pass and records reviewer, objections, resolutions, and verdict in the ADR `review:` block before promoting to `accepted`. If Codex is configured (`protocols/codex.md`), the review pass may dispatch Codex in verify mode; otherwise Claude performs the pass directly.
 
 ## Inputs
 
@@ -102,7 +102,7 @@ The subagent does NOT write the files itself — it returns the proposals. The m
 
 Each proposed ADR represents a decision that's hard to reverse — by definition, ADR-worthy. The `prototype-codifier` agent only proposes ADRs that match the adversarial-review trigger list (the canonical list lives in `agents/prototype-codifier.md` Phase 4); every proposal therefore arrives flagged for review.
 
-For each proposed ADR, run an adversarial review pass and write a structured `review:` block (reviewers, objections, resolutions, verdict) into the draft. The dedicated `/second-opinion` slash command + `support-second-opinion` skill that would package this work are *planned, not yet implemented* — until they ship, perform the review inline within harden (interrogate the decision against the trigger list's failure modes, surface objections explicitly, and either record resolutions or escalate to the user).
+For each proposed ADR, run an adversarial review pass and write a structured `review:` block (reviewers, objections, resolutions, verdict) into the draft. The review is performed inline within harden: interrogate the decision against the trigger list's failure modes, surface objections explicitly, and either record resolutions or escalate to the user. If Codex is configured (`protocols/codex.md`), dispatch it in verify mode to perform the review pass and merge its findings; otherwise Claude runs the pass directly.
 
 Only ADRs with `verdict: approved` get written as `status: accepted`. ADRs with `verdict: escalate` are surfaced to the user for resolution before the phase closes. ADRs with `verdict: reject` are dropped from the proposal set.
 
@@ -135,9 +135,23 @@ Each write triggers wiki-lint synchronously; lint failures must be resolved befo
 
 ### Step 4: trigger a focused dream
 
-After the writes land, fire a phase-close dream over the touched subfolders. The dream is the consolidation pass that may merge new ADRs with existing ones, promote raw entries that became relevant during codification, and prune stale entries the new architecture supersedes.
+After the Step 3 writes land, fire a phase-close dream. Invoke the `support-dream` skill with:
 
-Dream output goes to `aiwiki/proposed/{dream_id}/` for user review. The phase does NOT close until the user accepts or rejects the dream output.
+- **scope:** the subfolders Step 3 touched — typically `aiwiki/architecture/`, `aiwiki/decisions/`, `aiwiki/conventions/`, `aiwiki/gotchas/`, `aiwiki/oracles/`, `aiwiki/sessions/`
+- **trigger:** `phase-close`
+- **trigger_detail:** `"Phase 5 (codify) — {feature/name}"`
+
+The dream is the consolidation pass: it may merge new ADRs with existing ones, promote raw entries that became relevant during codification, and prune stale entries the new architecture supersedes.
+
+Dream output goes to `aiwiki/proposed/{dream_id}/` for user review. Surface the dream id and review path:
+
+```
+Phase 5 writes complete. Dream queued: 2026-05-18-HHMM-codify-{name}
+Review: `forge wiki review {dream_id}` or open `forge wiki ui`
+The codify gate (Step 5) does not pass until this dream is reviewed.
+```
+
+The phase does NOT close until the user accepts or rejects the dream output.
 
 ### Step 5: gate
 
@@ -153,7 +167,7 @@ The user reviews ALL outputs as a unit, not piecemeal. The codified plan is shor
 
 ## Adversarial review integration
 
-Every production-only decision is an ADR-worthy decision; the prototype-codifier subagent flags them all. Adversarial review runs on each proposed ADR before it's written as `accepted`. This is non-optional — production code that ships against an ADR with no recorded review is silent debt. The dedicated `/second-opinion` skill that will eventually own this work is *planned, not yet implemented* (see docs/V6-PLAN.md §11); today the review pass runs inline within harden Step 2 and writes the verdict directly into the ADR.
+Every production-only decision is an ADR-worthy decision; the prototype-codifier subagent flags them all. Adversarial review runs on each proposed ADR before it's written as `accepted`. This is non-optional — production code that ships against an ADR with no recorded review is silent debt. The review pass runs inline within harden Step 2 and writes the verdict directly into the ADR. When Codex is configured (`protocols/codex.md`), the pass may be dispatched to Codex in verify mode; otherwise Claude performs it directly.
 
 Decisions that don't make the trigger list (variable naming, inline-vs-extract, choosing between known-good libraries with no real tradeoff) don't need ADRs at all and are NOT proposed by the subagent.
 
@@ -164,7 +178,7 @@ Decisions that don't make the trigger list (variable naming, inline-vs-extract,
 | Generating architecture from imagination instead of citing the prototype | Every claim about a component cites `prototype-dir/path/to/file.ts:line@<sha7>` — if you can't cite, the claim is premature |
 | One giant `aiwiki/architecture.md` file | Split by subsystem: `data-layer.md`, `auth-flow.md`, `event-bus.md`. Each <400 lines. |
 | Writing ADRs for non-trigger-list decisions | Variable naming and inline-vs-extract are NOT ADRs. Use the trigger list strictly. |
-| Skipping adversarial review because "the decision is obvious" | If the decision is obvious it doesn't need an ADR; if it needs an ADR it needs review (today inline; `/second-opinion` dedicated surface planned) |
+| Skipping adversarial review because "the decision is obvious" | If the decision is obvious it doesn't need an ADR; if it needs an ADR it needs review (performed inline at Step 2, optionally via Codex verify mode) |
 | Pre-promoting raw entries during codification | Raw entries are dream's territory; harden writes to typed pages directly, raw stays raw until dream consolidates |
 | Modifying the prototype during codification | The prototype is the source of truth — leave it alone. Annotation goes in the architecture file, not in prototype source |
 | Treating the gate as advisory | Phase 6 reads these outputs; if codification is incomplete, the production build is improvising. Block until the user accepts. |
@@ -203,7 +217,7 @@ Decisions that don't make the trigger list (variable naming, inline-vs-extract,
 | Dispatches | For |
 |---|---|
 | `prototype-codifier` subagent | Bulk codification work in own context window |
-| `support-second-opinion` (`/second-opinion`) *(planned, not yet implemented)* | Adversarial review on each proposed ADR — until shipped, harden inlines this pass at Step 2 |
+| Codex (verify mode, via `protocols/codex.md`) | Optional adversarial review on each proposed ADR — if Codex is not configured, harden runs the review pass inline at Step 2 |
 | `support-dream` | Focused dream over touched subfolders after writes |
 | `support-wiki-lint` | Synchronous validation on every wiki write |
 

package/skills/iterate-prototype/SKILL.md

@@ -181,6 +181,28 @@ Two convergence signals:
 
 In autopilot mode, the loop hook reads the LOCKED signal from the manifest and exits cleanly.
 
+### Step 9: phase-close dream (auto-fire on lock)
+
+**Trigger:** Step 8 just wrote `artifacts.prototype.locked_at`. The prototype phase is closing, and Phase 4's accumulated `aiwiki/` writes (gotchas, conventions, raw notes from `/note`) should be consolidated before the next phase (codify) reads from it.
+
+**Action:** invoke the `support-dream` skill with:
+
+- **scope:** `aiwiki/raw/`, `aiwiki/gotchas/`, `aiwiki/conventions/` (the subfolders Phase 4 wrote to)
+- **trigger:** `phase-close`
+- **trigger_detail:** `"Phase 4 (iterate) lock — {feature/name}"`
+
+`support-dream` dispatches the `dreamer` subagent and writes a consolidation proposal to `aiwiki/proposed/{dream_id}/`. Surface the dream id and review path to the user:
+
+```
+Phase 4 closed. Dream queued: 2026-05-18-HHMM-iterate-{name}
+Review: `forge wiki review {dream_id}` or open `forge wiki ui`
+The codify (Phase 5) gate blocks until this dream is reviewed.
+```
+
+**Gate coupling:** the codify gate (`harden` Step 0 readiness check) must verify any phase-4 dream is reviewed before proceeding. The next phase reads consolidated wiki state, so it cannot proceed against pending unreviewed proposals.
+
+**Skip when:** no aiwiki writes occurred during Phase 4 (gotchas/conventions/raw all unchanged since prototype scaffold). No-op dreams add noise.
+
 ## Anti-fatigue
 
 If pending feedback grows past 10 items without any being resolved, the loop is not iterating — it's accumulating. Surface this to the user explicitly: "Pending list has grown to N items without resolution; consider whether the wireframe needs an update before continuing prototype iteration." This is the prototype-equivalent of the wiki accept-fatigue safeguard.