@jamie-tam/forge 6.0.0 → 6.2.0

package/dist/init.js

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { cwd } from "node:process";
 import { SOURCE, targets } from "./paths.js";
 import { copyFlatDir, copyRules, copyTreeDir } from "./copy.js";
@@ -7,6 +7,38 @@ import { installHooks } from "./hooks.js";
 import { verify } from "./verify.js";
 import { collectHashes, writeManifest } from "./manifest.js";
 import { hasForgeMarkers, mergeForgeBlock } from "./merge.js";
+/**
+ * Ensure runtime-only forge paths are gitignored. Idempotent: appends only
+ * entries the user does not already have. Creates .gitignore if absent.
+ *
+ * Entries:
+ *   .forge/state/      — operational state (telemetry, dream history; session handoff lives in aiwiki/sessions/)
+ *   .forge/local.yaml  — per-user preferences (Codex/Graphify consent, etc.)
+ *
+ * Why at install time: pre-compact.sh used to add `.forge/state/` from the
+ * runtime hook, which surprised users (writes to a tracked file from a hook).
+ * Moving this to init means a single intentional touch at user-invoked
+ * install time instead of an unexpected mutation mid-session.
+ *
+ * Returns the list of entries that were added (empty if all already present).
+ */
+export function ensureGitignoreEntries(projectRoot) {
+    const entries = [".forge/state/", ".forge/local.yaml"];
+    const path = join(projectRoot, ".gitignore");
+    const existing = existsSync(path) ? readFileSync(path, "utf-8") : "";
+    const lines = new Set(existing.split("\n").map((l) => l.trim()));
+    // Anything matching `.forge/` (full-dir ignore) covers both entries already.
+    if (lines.has(".forge/") || lines.has(".forge"))
+        return [];
+    const toAdd = entries.filter((e) => !lines.has(e));
+    if (toAdd.length === 0)
+        return [];
+    // Preserve trailing newline discipline of the existing file.
+    const needsLeadingNewline = existing.length > 0 && !existing.endsWith("\n");
+    const block = (needsLeadingNewline ? "\n" : "") + toAdd.join("\n") + "\n";
+    writeFileSync(path, existing + block);
+    return toAdd;
+}
 function summarize(label, r) {
     const parts = [];
     if (r.added.length)
@@ -52,6 +84,12 @@ export async function init(opts) {
         }
     }
     mkdirSync(t.claude, { recursive: true });
+    // Ensure forge runtime paths are gitignored. Done here (not from a runtime
+    // hook) so the mutation of a tracked file is intentional and user-visible.
+    const added = ensureGitignoreEntries(projectRoot);
+    if (added.length > 0) {
+        console.log(`  gitignore:   added ${added.join(", ")}`);
+    }
     // Copy assets
     const agents = copyFlatDir(SOURCE.agents, t.agents, opts);
     summarize("agents:", agents);

package/dist/uninstall.js

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { cwd } from "node:process";
 import { SOURCE, targets } from "./paths.js";
 import { readManifest } from "./manifest.js";
+import { uninstallHooks } from "./hooks.js";
 /**
  * Remove only forge-managed files from a project.
  * Uses the installed manifest (forge.json) when available for precision.
@@ -160,11 +161,16 @@ export async function uninstall(opts) {
             rmSync(hooksDir, { recursive: true });
         console.log(`  ${prefix}: hooks/`);
     }
-    const settingsLocal = join(t.claude, "settings.local.json");
-    if (existsSync(settingsLocal)) {
-        if (!opts.dryRun)
-            rmSync(settingsLocal);
-        console.log(`  ${prefix}: settings.local.json`);
+    // settings.local.json: strip forge-installed hook entries via reverse-merge,
+    // preserve user-added hooks/permissions/env. Delete the file only if nothing
+    // user-owned remains.
+    const settingsResult = uninstallHooks(projectRoot, { dryRun: opts.dryRun });
+    if (settingsResult.action === "deleted") {
+        console.log(`  ${prefix}: settings.local.json (no user content remained)`);
+    }
+    else if (settingsResult.action === "updated") {
+        const updatePrefix = opts.dryRun ? "Would update" : "Updated";
+        console.log(`  ${updatePrefix}: settings.local.json (forge hooks removed; user content preserved)`);
     }
     // CLAUDE.md and AGENTS.md — only with --force
     if (opts.force) {

package/dist/work-manifest.js

@@ -49,7 +49,6 @@ const VALID_SLICE_STATUSES = [
     "in-progress",
     "gated",
     "complete",
-    "abandoned",
 ];
 const VALID_GATE_STATUSES = [
     "pending",
@@ -70,14 +69,13 @@ const VALID_MANIFEST_STATUSES = [
     "paused",
     "completed",
     "escalated",
-    "abandoned",
 ];
-// Per-work-type recommended phase_plan keys, sourced from v6 SCHEMA.md §3.2's
-// recommended-keys table. Keys NOT in this set produce W_UNKNOWN_PHASE_PLAN_KEY
-// warnings (advisory only — typos are silent failures by spec, so a warning
-// gives commands a chance to catch them at preflight without breaking workflows
-// that legitimately extend their plan with custom keys).
-const RECOMMENDED_PHASE_PLAN_KEYS = new Map([
+// Per-work-type allowed phase_plan keys, sourced from v6 SCHEMA.md §3.2's
+// recommended-keys table. Keys NOT in this set produce E_UNKNOWN_PHASE_PLAN_KEY
+// errors — strict validation per the v6 follow-up decision (2026-05-17) after
+// dogfood signal showed silent typos breaking downstream routing. To add a
+// workflow-specific key, extend the set here AND update SCHEMA.md §3.2.
+const ALLOWED_PHASE_PLAN_KEYS = new Map([
     [
         "feature",
         new Set([
@@ -221,7 +219,7 @@ export function parseManifest(yaml) {
     validatePhaseGatePremature(manifest, errors);
     if (detectedSchema === "v6") {
         validateAndNormalizePhasePlan(manifest, errors);
-        validatePhasePlanKeysForType(manifest, warnings);
+        validatePhasePlanKeysForType(manifest, errors);
     }
     if (errors.length > 0) {
         return { ok: false, errors, warnings };
@@ -621,33 +619,74 @@ function validateAndNormalizePhasePlan(manifest, errors) {
     manifest.phase_plan = normalized;
 }
 /**
- * Advisory check: warn on phase_plan keys not in the recommended-keys table for
- * this manifest's work type (v6 SCHEMA.md §3.2). Typos in keys are silent
- * failures by spec (the parser does not validate against a canonical
- * vocabulary), so this warning gives commands a chance to catch them at
- * preflight without breaking workflows that legitimately extend the plan with
- * custom keys.
+ * Strict check: phase_plan keys MUST be in the allowed-keys table for this
+ * manifest's work type (v6 SCHEMA.md §3.2). Was a warning until the 2026-05-17
+ * follow-up decision — promoted to error because dogfood evidence showed
+ * silent typos breaking downstream routing (e.g. `phase_plan.prototpe` parses
+ * fine but `rules/common/skill-selection.md` reads `phase_plan.prototype`).
  *
- * Implemented as a warning, not an error: SCHEMA.md §3.2 reserves promotion to
- * a hard enum if real usage shows typos causing failures. Until then, command
- * authors can read `result.warnings` and surface them however they want.
+ * To extend a workflow with a new phase_plan key, add it to
+ * ALLOWED_PHASE_PLAN_KEYS for the relevant work type AND update SCHEMA.md §3.2.
  */
-function validatePhasePlanKeysForType(manifest, warnings) {
+function validatePhasePlanKeysForType(manifest, errors) {
     if (!manifest.phase_plan)
         return;
-    const allowed = RECOMMENDED_PHASE_PLAN_KEYS.get(manifest.type);
+    const allowed = ALLOWED_PHASE_PLAN_KEYS.get(manifest.type);
     if (!allowed)
         return; // unknown work type — E_BAD_ENUM_VALUE already caught that
     for (const key of Object.keys(manifest.phase_plan)) {
         if (!allowed.has(key)) {
-            warnings.push({
-                code: "W_UNKNOWN_PHASE_PLAN_KEY",
-                message: `phase_plan.${key} is not a recommended key for work type "${manifest.type}" (likely typo; SCHEMA.md §3.2 lists allowed keys)`,
+            const suggestion = nearestAllowedKey(key, allowed);
+            const suggestionHint = suggestion ? ` (did you mean "${suggestion}"?)` : "";
+            errors.push({
+                code: "E_UNKNOWN_PHASE_PLAN_KEY",
+                message: `phase_plan.${key} is not an allowed key for work type "${manifest.type}"${suggestionHint}. Allowed keys: ${[...allowed].sort().join(", ")}`,
                 path: `phase_plan.${key}`,
             });
         }
     }
 }
+/**
+ * Return the closest allowed key by Levenshtein distance, but only if it's
+ * within a small distance (likely typo, not a different word entirely). Helps
+ * the "did you mean?" hint in E_UNKNOWN_PHASE_PLAN_KEY messages.
+ */
+function nearestAllowedKey(typo, allowed) {
+    let best = null;
+    for (const k of allowed) {
+        const d = levenshtein(typo, k);
+        if (best === null || d < best.dist)
+            best = { key: k, dist: d };
+    }
+    // Only suggest if the edit distance is small relative to key length.
+    if (!best)
+        return null;
+    const threshold = Math.max(2, Math.floor(best.key.length / 3));
+    return best.dist <= threshold ? best.key : null;
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = new Array(b.length + 1);
+    let curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, // insertion
+            prev[j] + 1, // deletion
+            prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[b.length];
+}
 function validatePhaseGatePremature(manifest, errors) {
     // §3.6: code-review-final cannot be passed until all slices are terminal.
     // Only applies when a slice_graph exists — v6 allows manifests without one
@@ -660,7 +699,7 @@ function validatePhaseGatePremature(manifest, errors) {
     if (!manifest.slice_graph)
         return;
     const slices = manifest.slice_graph.slices;
-    const nonTerminal = Object.entries(slices).filter(([, s]) => s.status !== "complete" && s.status !== "abandoned");
+    const nonTerminal = Object.entries(slices).filter(([, s]) => s.status !== "complete");
     if (nonTerminal.length > 0) {
         errors.push({
             code: "E_PHASE_GATE_PREMATURE",

package/hooks/config/gate-requirements.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Maps manifest gate names to required skill and agent invocations. Used by gate-enforcer.sh to verify prerequisites before allowing gate-passed: true. Agents are dispatched by skills internally — listed here so the enforcer can verify they were invoked via telemetry.",
+  "_comment": "Maps manifest gate names to required skill and agent invocations. Used by gate-enforcer.sh to verify prerequisites before allowing gate-passed: true. Enforcement is work_id-scoped (v6.2+): the enforcer filters .forge/state/telemetry.jsonl to records whose work_id matches the manifest being edited (extracted from .forge/work/{type}/{name}/manifest.yaml). A stale invocation from another work item, or a legacy record written before work_id was added, does NOT satisfy a fresh gate. Agents are dispatched by skills internally — listed here so the enforcer can verify they were invoked via telemetry.",
   "requirements": {
     "skill": "discover-requirements",
     "agent": null

package/hooks/hooks.json

@@ -1,8 +1,9 @@
 {
-  "description": "Guardrails for safe git operations and context preservation",
+  "description": "Guardrails for safe git operations and context preservation. Every entry carries forge_owned: true so installHooks/uninstallHooks can identify forge-managed entries by provenance marker rather than exact string match — this lets future forge versions change command strings (paths, flags, timeouts) without leaving stale entries in user settings.local.json.",
   "hooks": {
     "PreToolUse": [
       {
+        "forge_owned": true,
         "matcher": "Bash",
         "hooks": [
           {
@@ -13,6 +14,7 @@
         ]
       },
       {
+        "forge_owned": true,
         "matcher": "Bash",
         "hooks": [
           {
@@ -23,6 +25,7 @@
         ]
       },
       {
+        "forge_owned": true,
         "matcher": "Edit",
         "hooks": [
           {
@@ -33,6 +36,7 @@
         ]
       },
       {
+        "forge_owned": true,
         "matcher": "Write",
         "hooks": [
           {
@@ -43,6 +47,7 @@
         ]
       },
       {
+        "forge_owned": true,
         "matcher": "MultiEdit",
         "hooks": [
           {
@@ -55,6 +60,7 @@
     ],
     "PostToolUse": [
       {
+        "forge_owned": true,
         "matcher": "Bash",
         "hooks": [
           {
@@ -65,6 +71,7 @@
         ]
       },
       {
+        "forge_owned": true,
         "matcher": "Skill",
         "hooks": [
           {
@@ -75,6 +82,7 @@
         ]
       },
       {
+        "forge_owned": true,
         "matcher": "Task",
         "hooks": [
           {
@@ -85,6 +93,7 @@
         ]
       },
       {
+        "forge_owned": true,
         "matcher": "Edit",
         "hooks": [
           {
@@ -95,6 +104,7 @@
         ]
       },
       {
+        "forge_owned": true,
         "matcher": "Write",
         "hooks": [
           {
@@ -105,6 +115,7 @@
         ]
       },
       {
+        "forge_owned": true,
         "matcher": "MultiEdit",
         "hooks": [
           {
@@ -117,6 +128,7 @@
     ],
     "SessionStart": [
       {
+        "forge_owned": true,
         "matcher": "*",
         "hooks": [
           {
@@ -129,6 +141,7 @@
     ],
     "PreCompact": [
       {
+        "forge_owned": true,
         "matcher": "*",
         "hooks": [
           {

package/hooks/scripts/gate-enforcer.sh

@@ -83,6 +83,14 @@ if [ ! -f "$CONFIG" ]; then
   exit 0
 fi
 
+# Extract work_id from the manifest path: .forge/work/{type}/{name}/manifest.yaml
+# Used to filter telemetry by work item so a stale invocation from another work
+# item cannot satisfy this gate (closes P0-5 from v6.1-beta audit).
+WORK_ID=""
+if [[ "$FILE_PATH" =~ \.forge/work/([^/]+)/([^/]+)/manifest\.yaml$ ]]; then
+  WORK_ID="${BASH_REMATCH[1]}/${BASH_REMATCH[2]}"
+fi
+
 # Check each gate being passed against requirements
 BLOCKED_REASONS=""
 
@@ -126,18 +134,55 @@ for GATE in $(jq -r 'keys[] | select(. != "_comment")' "$CONFIG"); do
     # Resolve required agents: agents array first, then single agent field
     REQUIRED_AGENTS=$(jq -r "if .\"$GATE\".agents then .\"$GATE\".agents[] else .\"$GATE\".agent // empty end" "$CONFIG" 2>/dev/null)
 
-    # Check skill invocation in telemetry
+    # Telemetry check is work_id-scoped (closes P0-5 cross-work-item bypass).
+    # Records without work_id (legacy or no-active-work) are NOT counted —
+    # an untagged invocation can't satisfy a gate on a specific work item.
+    # Records lacking jq-parsable shape are also ignored (jq returns null per line;
+    # `select(...)` filters them out).
+    check_invocation() {
+      local NAME="$1"
+      if [ ! -f "$TELEMETRY" ]; then
+        return 1
+      fi
+      if [ -z "$WORK_ID" ]; then
+        # No work_id resolved from path — should be rare; fall back to bare-name
+        # check so we don't accidentally hard-block manifest edits made outside
+        # the .forge/work/{type}/{name}/ tree (unlikely given the path filter
+        # at line ~43 already excluded non-manifest paths, but defensive).
+        grep -q "\"name\":\"$NAME\"" "$TELEMETRY" 2>/dev/null
+      else
+        # jq -s collects all JSONL lines into an array. select() narrows to the
+        # exact work_id + name pair. length > 0 means at least one invocation
+        # in this work item. The 2>/dev/null swallows parse errors on
+        # malformed records (treated as no match — correct behavior).
+        local COUNT
+        COUNT=$(jq -s --arg work_id "$WORK_ID" --arg name "$NAME" \
+          'map(select(.work_id == $work_id and .name == $name)) | length' \
+          "$TELEMETRY" 2>/dev/null || echo 0)
+        [ "$COUNT" != "0" ] && [ -n "$COUNT" ]
+      fi
+    }
+
+    # Check skill invocation in telemetry (work_id-scoped)
     if [ -n "$REQUIRED_SKILL" ]; then
-      if [ ! -f "$TELEMETRY" ] || ! grep -q "\"name\":\"$REQUIRED_SKILL\"" "$TELEMETRY"; then
-        BLOCKED_REASONS="${BLOCKED_REASONS}Gate '$GATE' requires skill '$REQUIRED_SKILL' (not found in telemetry). "
+      if ! check_invocation "$REQUIRED_SKILL"; then
+        if [ -n "$WORK_ID" ]; then
+          BLOCKED_REASONS="${BLOCKED_REASONS}Gate '$GATE' requires skill '$REQUIRED_SKILL' (not invoked for work_id '$WORK_ID'). "
+        else
+          BLOCKED_REASONS="${BLOCKED_REASONS}Gate '$GATE' requires skill '$REQUIRED_SKILL' (not found in telemetry). "
+        fi
       fi
     fi
 
-    # Check agent dispatch in telemetry
+    # Check agent dispatch in telemetry (work_id-scoped)
     for AGENT in $REQUIRED_AGENTS; do
       if [ -n "$AGENT" ] && [ "$AGENT" != "null" ]; then
-        if [ ! -f "$TELEMETRY" ] || ! grep -q "\"name\":\"$AGENT\"" "$TELEMETRY"; then
-          BLOCKED_REASONS="${BLOCKED_REASONS}Gate '$GATE' requires agent '$AGENT' (not found in telemetry). "
+        if ! check_invocation "$AGENT"; then
+          if [ -n "$WORK_ID" ]; then
+            BLOCKED_REASONS="${BLOCKED_REASONS}Gate '$GATE' requires agent '$AGENT' (not dispatched for work_id '$WORK_ID'). "
+          else
+            BLOCKED_REASONS="${BLOCKED_REASONS}Gate '$GATE' requires agent '$AGENT' (not found in telemetry). "
+          fi
         fi
       fi
     done

package/hooks/scripts/pre-compact.sh

@@ -1,33 +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"
 
-# Ensure .forge/state/ is gitignored
-if [ -f "$PROJECT_ROOT/.gitignore" ]; then
-    if ! grep -q '.forge/state' "$PROJECT_ROOT/.gitignore" 2>/dev/null; then
-        echo '.forge/state/' >> "$PROJECT_ROOT/.gitignore"
-    fi
-fi
-
-# 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
@@ -42,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