@jamie-tam/forge 6.0.0 → 6.1.0

package/dist/__tests__/work-manifest.test.js

@@ -198,10 +198,11 @@ test("v5 manifest parsed under v6 reader leaves phase_plan undefined", () => {
         throw new Error(`expected v5 manifest to have phase_plan=undefined, got ${JSON.stringify(m.phase_plan)}`);
     }
 });
-test("v6 typo'd phase_plan key triggers W_UNKNOWN_PHASE_PLAN_KEY warning", () => {
+test("v6 typo'd phase_plan key triggers E_UNKNOWN_PHASE_PLAN_KEY error", () => {
     // Same as v6-good.yaml but with one key intentionally misspelled. Parse
-    // should still succeed (warning, not error) and the warning should name the
-    // bad key so command authors can act on it.
+    // should FAIL (was a warning pre-2026-05-17; promoted to error after dogfood
+    // showed silent typos breaking downstream routing). The error should name
+    // the bad key so authors can act on it.
     const yaml = `schema_version: "6"
 name: typo-feature
 type: feature
@@ -230,24 +231,57 @@ slice_graph:
     a: { type: feature-slice, depends_on: [], status: pending, gates: { build-tdd: { status: pending, gate-passed: false } } }
 `;
     const r = parseManifest(yaml);
-    if (!r.ok) {
-        throw new Error(`expected parse to succeed (warning, not error); got errors: ${r.errors.map((e) => e.code).join(", ")}`);
+    if (r.ok) {
+        throw new Error("expected parse to fail on phase_plan typo, but it succeeded");
     }
-    const matching = r.warnings.filter((w) => w.code === "W_UNKNOWN_PHASE_PLAN_KEY");
+    const matching = r.errors.filter((e) => e.code === "E_UNKNOWN_PHASE_PLAN_KEY");
     if (matching.length !== 1) {
-        throw new Error(`expected exactly 1 W_UNKNOWN_PHASE_PLAN_KEY warning, got ${matching.length}: ${JSON.stringify(r.warnings)}`);
+        throw new Error(`expected exactly 1 E_UNKNOWN_PHASE_PLAN_KEY error, got ${matching.length}: ${JSON.stringify(r.errors)}`);
     }
     if (!matching[0].path.includes("prototpe")) {
-        throw new Error(`expected warning path to mention the typo'd key, got ${matching[0].path}`);
+        throw new Error(`expected error path to mention the typo'd key, got ${matching[0].path}`);
     }
 });
-test("v6 happy-path manifest emits no W_UNKNOWN_PHASE_PLAN_KEY warnings", () => {
+test("v6 typo'd phase_plan key error suggests the nearest allowed key", () => {
+    // The "did you mean?" hint should fire for a single-edit typo on a known key.
+    const yaml = `schema_version: "6"
+name: typo-feature
+type: feature
+description: "phase_plan with a misspelled key"
+status: in-progress
+created: "2026-05-12"
+command: feature
+phase_plan:
+  prototpe: active
+phases:
+  discover: { codebase-analysis: { status: pending, gate-passed: false } }
+  plan: { brainstorm: { status: pending, gate-passed: false } }
+  quality: { code-review-final: { status: pending, gate-passed: false } }
+  deliver: { pr-created: false }
+  support: { gotchas-recorded: false }
+slice_graph:
+  current_slice: a
+  slices:
+    a: { type: feature-slice, depends_on: [], status: pending, gates: { build-tdd: { status: pending, gate-passed: false } } }
+`;
+    const r = parseManifest(yaml);
+    if (r.ok)
+        throw new Error("expected parse to fail");
+    const err = r.errors.find((e) => e.code === "E_UNKNOWN_PHASE_PLAN_KEY");
+    if (!err)
+        throw new Error("expected E_UNKNOWN_PHASE_PLAN_KEY error");
+    if (!err.message.includes(`did you mean "prototype"`)) {
+        throw new Error(`expected 'did you mean "prototype"' suggestion in message, got: ${err.message}`);
+    }
+});
+test("v6 happy-path manifest emits no E_UNKNOWN_PHASE_PLAN_KEY errors", () => {
     const r = parseManifest(loadFixture("v6-good.yaml"));
-    if (!r.ok)
-        throw new Error("expected v6-good to parse");
-    const unknown = r.warnings.filter((w) => w.code === "W_UNKNOWN_PHASE_PLAN_KEY");
-    if (unknown.length !== 0) {
-        throw new Error(`expected zero W_UNKNOWN_PHASE_PLAN_KEY warnings on v6-good, got: ${JSON.stringify(unknown)}`);
+    if (!r.ok) {
+        const unknown = r.errors.filter((e) => e.code === "E_UNKNOWN_PHASE_PLAN_KEY");
+        if (unknown.length > 0) {
+            throw new Error(`v6-good fixture should have no unknown phase_plan keys; got: ${JSON.stringify(unknown)}`);
+        }
+        throw new Error(`v6-good failed with other errors: ${r.errors.map((e) => e.code).join(", ")}`);
     }
 });
 test("variant: empty-string on non-skeleton is forbidden", () => {

package/dist/hooks.js

@@ -1,6 +1,14 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { SOURCE } from "./paths.js";
+function isForgeOwned(entry, forgeEntries, forgeStrings) {
+    if (entry.forge_owned === true)
+        return true;
+    // Identity fallback: entries installed before the marker shipped lack the
+    // field; they match the current forge entry set verbatim. Once replaced
+    // with the new (marked) entry, future runs use the marker path.
+    return forgeStrings.has(JSON.stringify(entry));
+}
 /**
  * Install forge hooks into the project's .claude/settings.local.json.
  * Copies hook scripts to .claude/hooks/ and merges hook definitions
@@ -43,18 +51,92 @@ export function installHooks(projectRoot, opts) {
 }
 /**
  * Merge forge hooks into existing hooks by event type.
- * For each event forge defines, remove any existing entry that exactly
- * matches a forge entry (old or new), then append the new forge entries.
- * User-defined entries that don't match any forge entry are preserved.
+ * For each event forge defines, remove any existing entry identified as
+ * forge-owned (via the `forge_owned: true` marker, or via exact JSON match
+ * against the current forge entry set for backward compat), then append the
+ * new forge entries. User-defined entries are preserved.
+ *
+ * The marker-based detection is what makes the merge tolerant of changing
+ * forge entries between releases: a v6 entry with command "X.sh" and a v7
+ * entry with command "X.sh --strict" both carry `forge_owned: true`, so v7's
+ * install correctly replaces v6's entry rather than letting it survive as
+ * "user-defined" forever.
  */
 function mergeHooks(existing, forge) {
     const merged = { ...existing };
     for (const [event, forgeEntries] of Object.entries(forge)) {
         const existingEntries = merged[event] ?? [];
         const forgeStrings = new Set(forgeEntries.map((e) => JSON.stringify(e)));
-        // Keep only entries that are NOT identical to a forge entry
-        const userEntries = existingEntries.filter((entry) => !forgeStrings.has(JSON.stringify(entry)));
+        // Keep only entries that are NOT forge-owned (by marker or by identity fallback)
+        const userEntries = existingEntries.filter((entry) => !isForgeOwned(entry, forgeEntries, forgeStrings));
         merged[event] = [...userEntries, ...forgeEntries];
     }
     return merged;
 }
+/**
+ * Mirror of mergeHooks. Remove every entry identified as forge-owned for each
+ * event. User-defined entries are preserved in their original order. Events
+ * whose entries were entirely forge-owned have their key dropped from the
+ * result. Events forge doesn't define are passed through untouched.
+ *
+ * Detection uses the same dual rule as mergeHooks: `forge_owned: true` marker,
+ * with exact-JSON-match fallback for installations made before the marker
+ * shipped.
+ */
+export function unmergeHooks(existing, forge) {
+    const result = {};
+    for (const [event, existingEntries] of Object.entries(existing)) {
+        const forgeEntries = forge[event];
+        if (!forgeEntries) {
+            // Forge doesn't manage this event; leave it alone
+            result[event] = existingEntries;
+            continue;
+        }
+        const forgeStrings = new Set(forgeEntries.map((e) => JSON.stringify(e)));
+        const userEntries = existingEntries.filter((entry) => !isForgeOwned(entry, forgeEntries, forgeStrings));
+        if (userEntries.length > 0) {
+            result[event] = userEntries;
+        }
+        // else drop the event key entirely — nothing user-owned left
+    }
+    return result;
+}
+/**
+ * Reverse of installHooks. Strip forge-installed hook entries from
+ * .claude/settings.local.json while preserving user-added hooks, permissions,
+ * env vars, and any other keys. Deletes the file only when nothing remains.
+ *
+ * Returns the action taken so callers can log it consistently.
+ */
+export function uninstallHooks(projectRoot, opts) {
+    const claudeDir = resolve(projectRoot, ".claude");
+    const settingsPath = join(claudeDir, "settings.local.json");
+    if (!existsSync(settingsPath)) {
+        return { settingsPath, action: "absent" };
+    }
+    const srcHooksJson = join(SOURCE.hooks, "hooks.json");
+    if (!existsSync(srcHooksJson)) {
+        // No source — can't precisely identify forge entries; leave file untouched
+        return { settingsPath, action: "absent" };
+    }
+    const forgeHooks = JSON.parse(readFileSync(srcHooksJson, "utf-8")).hooks;
+    const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    const existingHooks = (settings.hooks ?? {});
+    const remainingHooks = unmergeHooks(existingHooks, forgeHooks);
+    if (Object.keys(remainingHooks).length > 0) {
+        settings.hooks = remainingHooks;
+    }
+    else {
+        delete settings.hooks;
+    }
+    // Only delete the file if nothing user-meaningful remains.
+    if (Object.keys(settings).length === 0) {
+        if (!opts.dryRun)
+            rmSync(settingsPath);
+        return { settingsPath, action: "deleted" };
+    }
+    if (!opts.dryRun) {
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    }
+    return { settingsPath, action: "updated" };
+}

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 (notepad, telemetry, dream history)
+ *   .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/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/pre-compact.sh

@@ -18,12 +18,9 @@ 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
+# 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"

package/hooks/scripts/session-start.sh

@@ -52,7 +52,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/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.1.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