@jamie-tam/forge 6.1.0 → 6.2.0

package/hooks/scripts/pre-compact.sh

@@ -1,30 +1,47 @@
 #!/bin/bash
 # Pre-compact hook: Save critical state before context window compression.
-# This ensures the agent can recover its working context after compaction.
 #
-# Writes to .forge/state/notepad.md which survives context compression
-# because it's re-read by the agent when it detects context loss.
+# Writes a "## Checkpoints" entry to aiwiki/sessions/{date}-{session_id_short}.md
+# which is the canonical per-session handoff file. The session file is created
+# lazily on the first event (this hook, /wrap, /dream, or harden's session write).
 #
-# Scans `.forge/work/*/` (typed subdirs) for the single in-progress work item.
-# Skips `escalated`/`completed` manifests (terminal states). Uses `{type}/{name}`
-# as the canonical work identifier because names can collide across types.
+# Reads session_id from Claude Code's PreCompact hook payload (stdin JSON).
+# Falls back to "0000000" short id if stdin payload is missing or malformed —
+# the file is still created, just without traceable session linkage.
+#
+# Recovery path: post-compact agent (and the next SessionStart) reads the
+# latest aiwiki/sessions/*.md, looks at ## Checkpoints, and acts on any
+# `Status: unconsumed` directive.
+#
+# Notepad (.forge/state/notepad.md) — REMOVED in v6.2. The single source of
+# truth for session recovery state is now aiwiki/sessions/{date}-{id}.md.
+# See templates/aiwiki/schemas/session.md (schema v2) for the file shape.
+#
+# Also logs the compaction event to .forge/state/telemetry.jsonl (unchanged).
 
 set -euo pipefail
 
-# Find project root (look for .forge/ or .git/)
+# Read stdin JSON payload (Claude Code's hook contract). The payload includes
+# session_id, transcript_path, cwd, hook_event_name, trigger. We need session_id.
+PAYLOAD="$(cat 2>/dev/null || true)"
+
+# Extract session_id via sed (no jq dependency). UUID format expected.
+SESSION_ID=""
+if [ -n "$PAYLOAD" ]; then
+    SESSION_ID="$(echo "$PAYLOAD" | sed -n 's/.*"session_id"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)"
+fi
+SESSION_ID_SHORT="${SESSION_ID:0:7}"
+if [ -z "$SESSION_ID_SHORT" ]; then
+    SESSION_ID_SHORT="0000000"
+fi
+
+# Find project root
 PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
 STATE_DIR="$PROJECT_ROOT/.forge/state"
-
-# Create state directory if needed
 mkdir -p "$STATE_DIR"
 
-# Note: .forge/state/ gitignore management lives in `forge init` (src/init.ts
-# ensureGitignoreEntries). This hook used to append from here, but mutating a
-# tracked user file from a runtime hook is surprising — moved to install time.
-
-# Find active work item (status: in-progress), scanning typed subdirs
-NOTEPAD="$STATE_DIR/notepad.md"
-ACTIVE_WORK=""      # Canonical identifier: {type}/{name}
+# Find active work item (status: in-progress)
+ACTIVE_WORK=""
 MANIFEST_PATH=""
 
 if [ -d "$PROJECT_ROOT/.forge/work" ]; then
@@ -39,49 +56,100 @@ if [ -d "$PROJECT_ROOT/.forge/work" ]; then
     done
 fi
 
-# Build notepad content
-{
-    echo "# Forge Context Recovery"
-    echo ""
-    echo "**This file was auto-generated before context compaction.**"
-    echo "**Re-read the manifest and continue from where you left off.**"
-    echo ""
-    echo "## Active Work Item"
-
-    if [ -n "$ACTIVE_WORK" ]; then
-        echo "- Work: $ACTIVE_WORK"
-        echo "- Manifest: $MANIFEST_PATH"
+# Detect recent aiwiki/ activity (24h window) for dream-directive decision
+RECENT_AIWIKI_CHANGES=0
+if [ -d "$PROJECT_ROOT/aiwiki" ]; then
+    if [ -d "$PROJECT_ROOT/aiwiki/raw" ] && [ -n "$(find "$PROJECT_ROOT/aiwiki/raw" -type f -name '*.md' -mtime -1 2>/dev/null | head -1)" ]; then
+        RECENT_AIWIKI_CHANGES=1
+    fi
+    if [ "$RECENT_AIWIKI_CHANGES" -eq 0 ]; then
+        for typed in gotchas decisions conventions architecture oracles; do
+            if [ -d "$PROJECT_ROOT/aiwiki/$typed" ] && [ -n "$(find "$PROJECT_ROOT/aiwiki/$typed" -type f -name '*.md' -mtime -1 2>/dev/null | head -1)" ]; then
+                RECENT_AIWIKI_CHANGES=1
+                break
+            fi
+        done
+    fi
+fi
+
+# Session file path
+TODAY="$(date -u '+%Y-%m-%d')"
+TIMESTAMP="$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
+SESSIONS_DIR="$PROJECT_ROOT/aiwiki/sessions"
+SESSION_FILE="$SESSIONS_DIR/${TODAY}-${SESSION_ID_SHORT}.md"
+
+# If aiwiki/ doesn't exist (forge installed but never bootstrapped), skip
+# session-file write entirely — there's nowhere to put it. Telemetry still logs.
+if [ -d "$PROJECT_ROOT/aiwiki" ]; then
+    mkdir -p "$SESSIONS_DIR"
+
+    # Lazy-create session file with bare frontmatter if missing
+    if [ ! -f "$SESSION_FILE" ]; then
+        FOCUS_INIT="${ACTIVE_WORK:-unset}"
+        {
+            echo "---"
+            echo "schema_id: session"
+            echo "schema_version: 2"
+            echo "status: active"
+            echo "date_start: $TODAY"
+            echo "session_id: ${SESSION_ID:-unknown}"
+            echo "focus: $FOCUS_INIT"
+            echo "last_commit: ~"
+            echo "---"
+            echo ""
+            echo "## Checkpoints"
+            echo ""
+        } > "$SESSION_FILE"
+    fi
+
+    # Append PreCompact checkpoint entry
+    {
+        echo "### PreCompact at $TIMESTAMP"
         echo ""
+        if [ -n "$ACTIVE_WORK" ]; then
+            echo "Active work: $ACTIVE_WORK"
+            echo "Manifest: $MANIFEST_PATH"
+            echo ""
+            if [ -f "$MANIFEST_PATH" ]; then
+                echo "Phase status (from manifest):"
+                echo '```yaml'
+                grep -A 1 'status:\|gate-passed:\|locked_at:' "$MANIFEST_PATH" 2>/dev/null | head -30
+                echo '```'
+                echo ""
+            fi
+        else
+            echo "Active work: none (no in-progress manifest found)"
+            echo ""
+        fi
 
-        # Extract current phase info from manifest
-        if command -v grep &>/dev/null && [ -f "$MANIFEST_PATH" ]; then
-            echo "### Phase Status (from manifest)"
-            echo '```yaml'
-            grep -A 1 'status:\|gate-passed:' "$MANIFEST_PATH" 2>/dev/null | head -30
-            echo '```'
+        if [ "$RECENT_AIWIKI_CHANGES" -eq 1 ]; then
+            echo "**Dream directive (unconsumed):**"
+            echo ""
+            echo "- Scope: \`aiwiki/raw/\` + typed pages touched in the last 24h (gotchas/, conventions/, etc.)"
+            echo "- Trigger: \`pre-compact\`, context ~85%"
+            echo "- Action: invoke \`support-dream\` skill before resuming other work"
+            echo "- Session-file refinement: if this file's other sections (Files touched, Decisions, etc.) exist, dream may also refine them"
+            echo ""
+            echo "Mark consumed: after invoking dream, change this entry's header from \`**Dream directive (unconsumed):**\` to \`**Dream directive (consumed at {ISO-timestamp}):**\`. Header-flip is what session-start.sh counts; appending a 'Status: consumed' line leaves the original header in place and the next session-start still surfaces it as unconsumed."
+            echo ""
         fi
-    else
-        echo "- No active work item found"
-    fi
 
-    echo ""
-    echo "## Recovery Instructions"
-    echo "1. Read the manifest file listed above"
-    echo "2. Find the first phase with \`status: pending\` or \`gate-passed: false\`"
-    echo "3. Continue from that phase"
-    echo "4. If build phase: check which tasks are complete vs pending"
-    echo ""
-    echo "---"
-    echo "*Generated at: $(date -u '+%Y-%m-%dT%H:%M:%SZ')*"
-} > "$NOTEPAD"
-
-# Log compaction event to telemetry
+        echo "---"
+        echo ""
+    } >> "$SESSION_FILE"
+
+    echo "Pre-compact: appended checkpoint to $SESSION_FILE" >&2
+else
+    echo "Pre-compact: aiwiki/ not present — skipped session checkpoint. Telemetry logged." >&2
+fi
+
+# Log compaction event to telemetry (unchanged)
 TELEMETRY_FILE="$STATE_DIR/telemetry.jsonl"
-TIMESTAMP="$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
 WORK_JSON="${ACTIVE_WORK:-null}"
 if [ -n "$ACTIVE_WORK" ]; then WORK_JSON="\"$ACTIVE_WORK\""; fi
+SESSION_JSON="${SESSION_ID:-null}"
+if [ -n "$SESSION_ID" ]; then SESSION_JSON="\"$SESSION_ID\""; fi
 
-echo "{\"event\":\"compact\",\"timestamp\":\"$TIMESTAMP\",\"work\":$WORK_JSON}" >> "$TELEMETRY_FILE"
+echo "{\"event\":\"compact\",\"timestamp\":\"$TIMESTAMP\",\"work\":$WORK_JSON,\"session_id\":$SESSION_JSON,\"aiwiki_active\":$RECENT_AIWIKI_CHANGES}" >> "$TELEMETRY_FILE"
 
-echo "Pre-compact: Saved context recovery state to $NOTEPAD" >&2
 exit 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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jamie-tam/forge",
-  "version": "6.1.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/rules/common/forge-system.md

@@ -44,7 +44,7 @@ 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.
 ```
 
 The `.forge/` directory retains operational state only (manifests, telemetry, dream history). Project knowledge lives in `aiwiki/` (next section).
@@ -61,8 +61,8 @@ Work items are identified by `{type}/{name}` — names may collide across types.
 | `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 work notes (index-of-links) | manual or `harden` at codify; session-checkpoint hooks deferred |
-| `oracle/` | Trusted external references (RFCs, vendor docs) | 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`.
@@ -70,7 +70,7 @@ Work items are identified by `{type}/{name}` — names may collide across types.
 **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. (Session-file refinement deferred until session-checkpoint hooks ship — see `aiwiki/sessions/` row above.)
+- **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.
 
@@ -78,19 +78,39 @@ Dream outputs to `aiwiki/proposed/{dream_id}/` — input store is never modified
 
 ### When the AI should write to aiwiki
 
-The default is **don't**. The user-customizable `aiwiki/CLAUDE.md` (auto-loaded when `aiwiki/` is scaffolded by `/setup`) carries the per-page-type writing rules; respect them. Three reminders that override any temptation to over-capture:
+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.
 
-1. **Never write speculation, conversation history, or "we might want to revisit this" notes.** This is the strongest rule in `aiwiki/CLAUDE.md`. Wiki pages answer recurring questions; conversational asides do not.
-2. **Typed pages need durable, reusable knowledge.** Decisions go to `aiwiki/decisions/` only after the decision is finalized (architectural, public-surface, security, schema, or other hard-to-reverse choice). Gotchas to `aiwiki/gotchas/` only when the failure mode is reproducible with a concrete fix. Conventions to `aiwiki/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. **Ad-hoc research, half-formed thoughts, deferred decisions, comparison notes — these go to `aiwiki/raw/` ONLY when the user explicitly invokes `/note <text>`.** The AI does not autonomously decide to write conversational content to raw. The user is the gate.
+Per-folder discipline:
 
-If a typed-page-worthy insight emerges mid-conversation (e.g., "this is a real gotcha"), you MAY write it to the correct typed page — but only if it meets that page's durability test. When in doubt, ask the user.
+| 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 has no automated session-end capture mechanism. If a session produced durable knowledge that warrants persisting, the AI should OFFER to write the appropriate typed pages before ending the session — never silently. The user accepts or declines.
+**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/deliver-deploy/SKILL.md

@@ -300,6 +300,15 @@ VERDICT: Ready to deploy
    - If any issues were encountered during deploy, invoke `support-gotcha`
    - 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
 
 ### When to Roll Back

package/skills/harden/SKILL.md

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

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.

package/skills/support-dream/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: support-dream
-description: "Use when the user asks to 'consolidate the wiki', 'clean up aiwiki', 'merge duplicate notes', 'prune stale gotchas', or when /forge-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."
+description: "Use when the user asks to 'consolidate the wiki', 'clean up aiwiki', 'merge duplicate notes', 'prune stale gotchas', or when /forge-evolve runs maintenance. Auto-fires via /dream slash command (manual), hooks/scripts/pre-compact.sh (PreCompact, ~85% context — writes a 'Status: unconsumed' Checkpoints entry to aiwiki/sessions/{date}-{session_id}.md that the post-compact agent acts on), and phase-close skills (iterate-prototype Step 9, harden Step 4, feature.md Step 8.5 per-slice, deliver-deploy Phase 5.4 retrospective) which dispatch this skill after writing their respective artifacts.{phase}.locked_at. Merges aiwiki duplicates, resolves contradictions, refines the active session file. Output goes to aiwiki/proposed/ for user review — input is never modified."
 ---
 
 # Support: Dream (Wiki Consolidation)
@@ -22,7 +22,7 @@ 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 signal into durable form before lossy compaction | `aiwiki/raw/` + recently-touched typed pages. If `aiwiki/sessions/{current}.md` exists, refine it too; if not, skip (session-checkpoint hooks deferred — see `templates/aiwiki/schemas/session.md`). |
+| **PreCompact hook fire** (~85% context utilization) | Consolidate signal into durable form before lossy compaction | `aiwiki/raw/` + recently-touched typed pages. Also refines the active session file (`aiwiki/sessions/{date}-{session_id_short}.md`) — pre-compact creates it lazily on first fire; dream consolidates its `## Checkpoints` event log if it grows beyond ~10 entries. |
 | **Manual `/dream`** | User-driven cleanup (after major refactor, branch merge, accumulated noise) | User-specified |
 
 **Do NOT skip when:**
@@ -55,14 +55,15 @@ Fired by phase-close hooks (after user emits the phase-lock signal):
 
 ### PreCompact trigger
 
-Fired by forge's existing pre-compact hook (~85% context):
+Fired indirectly via the pre-compact hook (`hooks/scripts/pre-compact.sh`). The hook itself cannot dispatch a subagent — instead it writes a `**Dream directive (unconsumed)**` block to the active session file's `## Checkpoints` section. The post-compact agent reads the session file, finds the unconsumed directive, and invokes this skill.
 
-1. Hook calls skill with scope `[aiwiki/raw/, recently-touched-typed-pages]`. If `aiwiki/sessions/{current}.md` exists, ALSO include it in scope.
-2. **Conditional session prerequisite** — if `aiwiki/sessions/{current}.md` exists (session-checkpoint hooks shipped and active), dream IMPROVES it; does not produce its existence. If it does NOT exist (current state — session-checkpoint hooks deferred), dream SKIPS session-file refinement and consolidates raw/typed pages only. No `SESSION_FILE_MISSING` failure.
+1. Skill is invoked by the post-compact agent acting on the directive. Scope from directive: `aiwiki/raw/` + recently-touched typed pages, plus the active session file itself (`aiwiki/sessions/{date}-{session_id_short}.md`).
+2. **Session file is always present at PreCompact time** — pre-compact.sh creates it lazily on first fire and appends the checkpoint. Dream refines the session file's `## Checkpoints` section if it has grown unwieldy (>10 entries) and may pre-populate the index sections (`## Files touched`, etc.) from git diff and aiwiki writes, leaving `/wrap` to finalize.
 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 raw/typed pages are already on disk)
+6. Native compaction does not wait for user review — the consolidated raw/typed pages and session-file proposal are already on disk
+7. **Mark the directive consumed** — after dispatch returns, the agent changes the originating entry's header from `**Dream directive (unconsumed):**` to `**Dream directive (consumed at {ISO-timestamp}):**`. Header-flip is what `session-start.sh` counts. Appending a separate "Status: consumed" line leaves the original unconsumed-marked header in place and the next session-start will still surface it as a HARD-INTERRUPT (dogfood-validated 2026-05-18).
 
 ### Manual /dream trigger
 
@@ -176,7 +177,7 @@ This skill operates the dream side; the user-facing CLI is separate but document
 | 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 |
+| Writing a new file in `aiwiki/sessions/` instead of refining the active session file | The active session file is `aiwiki/sessions/{date}-{session_id_short}.md` — created by pre-compact, /wrap, /dream, or harden. Dream refines that file in place (via the proposed-output path); it does not produce a separate sessions 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 |