@ghl-ai/aw 0.1.39-beta.8 → 0.1.39

package/commands/push.mjs

@@ -29,7 +29,7 @@ import { hasRulesChanges, isRulesPushInput, pushRulesCommand } from './push-rule
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8')).version;
 
-const PUSHABLE_TYPES = ['agents', 'skills', 'commands', 'evals'];
+const PUSHABLE_TYPES = ['agents', 'skills', 'commands', 'evals', 'references'];
 
 // ── PR content generation ────────────────────────────────────────────
 
@@ -635,8 +635,8 @@ export async function pushCommand(args) {
     const registryAbsPath = join(registrySubDir, relFromRegistry);
     const allFiles = collectBatchFiles(registryAbsPath, registrySubDir);
     if (allFiles.length === 0) {
-      fmt.cancel(`Nothing to push in ${chalk.cyan(input)} — no agents, skills, commands, or evals found.`);
-      return;
+      // Folder/namespace input → batch push
+      fmt.cancel(`Nothing to push in ${chalk.cyan(input)} — no agents, skills, commands, evals, or references found.`);
     }
     // Only include files that actually have changes (new or modified)
     const folderChanges = detectChanges(awHome, REGISTRY_DIR);
@@ -688,7 +688,7 @@ export async function pushCommand(args) {
     fmt.cancel([
       `Invalid push path: ${chalk.red(resolved.registryPath)}`,
       '',
-      `  Content must live under an ${chalk.bold('agents/')}, ${chalk.bold('skills/')}, ${chalk.bold('commands/')}, or ${chalk.bold('evals/')} directory.`,
+      `  Content must live under an ${chalk.bold('agents/')}, ${chalk.bold('skills/')}, ${chalk.bold('commands/')}, ${chalk.bold('evals/')}, or ${chalk.bold('references/')} directory.`,
       '',
       `  ${chalk.dim('Valid examples:')}`,
       `    aw push .aw_registry/commerce/quality/agents/unit-tester.md`,

package/commands/search.mjs

@@ -98,7 +98,7 @@ function searchLocal(workspaceDir, query) {
     if (!nsEntry.isDirectory() || nsEntry.name.startsWith('.')) continue;
     const ns = nsEntry.name;
 
-    for (const type of ['agents', 'skills', 'commands', 'evals']) {
+    for (const type of ['agents', 'skills', 'commands', 'evals', 'references']) {
       const typeDir = join(workspaceDir, ns, type);
       if (!existsSync(typeDir)) continue;
 

package/commands/startup.mjs

@@ -0,0 +1,87 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import * as fmt from '../fmt.mjs';
+import { chalk } from '../fmt.mjs';
+import { removeWorkspaceHookDefaults } from '../codex.mjs';
+import {
+  applyStoredStartupPreferences,
+  getStartupStatus,
+  hasLegacyRepoStartupDefaults,
+  saveStartupPreferences,
+} from '../startup.mjs';
+
+const HOME = homedir();
+
+export function routingCommand(args) {
+  const action = String(args._positional?.[0] || 'status').toLowerCase();
+
+  if (!['status', 'enable', 'disable'].includes(action)) {
+    fmt.cancel(`Unknown routing action: ${action}. Use: aw routing status|enable|disable`);
+    return;
+  }
+
+  fmt.intro(`aw routing ${action}`);
+
+  if (action === 'status') {
+    return renderStatus();
+  }
+
+  const mode = action === 'disable' ? 'disabled' : 'enabled';
+  const cwd = process.cwd();
+  const removedLegacyFiles = cwd !== HOME ? removeWorkspaceHookDefaults(cwd) : [];
+
+  saveStartupPreferences(mode, HOME);
+  const updatedFiles = applyStoredStartupPreferences(HOME);
+  const status = getStartupStatus(HOME);
+
+  fmt.outro([
+    `⟁  Session routing ${action === 'disable' ? 'disabled' : 'enabled'}`,
+    '',
+    `  ${chalk.green('✓')} Preference saved: ${chalk.dim(status.preferencesPath.replace(`${HOME}/`, '~/'))}`,
+    `  ${chalk.green('✓')} Claude session routing: ${status.claudeDisabled ? chalk.yellow('disabled') : chalk.green('enabled')}`,
+    `  ${chalk.green('✓')} Codex session routing: ${status.codexHooksEnabled && status.codexSessionStartPresent ? chalk.green('enabled') : chalk.yellow('disabled')}`,
+    `  ${chalk.green('✓')} Cursor session routing: ${status.cursorSessionStartPresent ? chalk.green('enabled') : chalk.yellow('disabled')}`,
+    removedLegacyFiles.length > 0
+      ? `  ${chalk.green('✓')} Removed ${removedLegacyFiles.length} legacy repo routing file${removedLegacyFiles.length > 1 ? 's' : ''} from the current project`
+      : null,
+    updatedFiles.length === 0
+      ? `  ${chalk.dim('Note:')} no global routing files needed changes`
+      : null,
+  ].filter(Boolean).join('\n'));
+}
+
+function renderStatus() {
+  const status = getStartupStatus(HOME);
+  const codexStatus = status.codexHooksEnabled && status.codexSessionStartPresent
+    ? 'enabled'
+    : status.codexSessionStartPresent && !status.codexHooksEnabled
+      ? 'hook installed but codex_hooks is disabled'
+      : 'disabled';
+  const claudeStatus = status.claudeDisabled
+    ? 'disabled via ~/.claude/settings.json override'
+    : status.claudeLegacySessionStartPresent
+      ? 'enabled (legacy hook present; run aw routing enable to clean)'
+      : status.claudePluginEnabled && status.claudePluginInstalled
+        ? 'enabled (plugin installed)'
+        : status.claudePluginEnabled && !status.claudePluginInstalled
+          ? 'misconfigured (plugin enabled in settings but not installed)'
+          : 'disabled (plugin not installed)';
+
+  fmt.note([
+    `${chalk.dim('mode:')} ${status.mode}`,
+    `${chalk.dim('prefs:')} ${status.preferencesPath.replace(`${HOME}/`, '~/')}`,
+    `${chalk.dim('claude session routing:')} ${claudeStatus}`,
+    `${chalk.dim('codex session routing:')} ${codexStatus}`,
+    `${chalk.dim('codex runtime:')} ${status.codexSessionStartScriptInstalled ? 'installed' : 'not installed'}`,
+    `${chalk.dim('cursor session routing:')} ${status.cursorSessionStartPresent ? 'enabled' : 'disabled'}`,
+    `${chalk.dim('cursor runtime:')} ${status.cursorSessionStartScriptInstalled ? 'installed' : 'not installed'}`,
+    process.cwd() !== HOME
+      ? `${chalk.dim('current repo legacy routing files:')} ${hasLegacyRepoStartupDefaults(process.cwd()) ? 'present' : 'not detected'}`
+      : null,
+  ].join('\n'), 'Routing');
+
+  fmt.outro('⟁  Routing status complete');
+}
+
+export const startupCommand = routingCommand;

package/constants.mjs

@@ -25,8 +25,10 @@ export const DOCS_SOURCE_DIR = 'content';
 /** Persistent git clone root — ~/.aw/ */
 export const AW_HOME = join(homedir(), '.aw');
 
-/** Directory in platform-docs repo containing platform rules (pulled into .aw_registry/.aw_rules/) */
+/** Directory in platform-docs repo containing platform rules (synced into root-level .aw_rules/) */
 export const RULES_SOURCE_DIR = '.aw_rules';
+/** Runtime location exposed to harnesses and generated instructions */
+export const RULES_RUNTIME_DIR = '.aw/.aw_rules';
 /** Telemetry endpoint — override with AW_TELEMETRY_URL env var */
 export const TELEMETRY_URL = process.env.AW_TELEMETRY_URL || 'https://services.leadconnectorhq.com/agentic-workspace/api/telemetry/events';
 

package/ecc.mjs

@@ -6,21 +6,30 @@ import {
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import * as fmt from "./fmt.mjs";
+import { applyStoredStartupPreferences } from "./startup.mjs";
 
 const AW_ECC_REPO_SSH = "git@github.com:shreyansh-ghl/aw-ecc.git";
 const AW_ECC_REPO_HTTPS = "https://github.com/shreyansh-ghl/aw-ecc.git";
-const AW_ECC_TAG = "v1.4.32";
+export const AW_ECC_TAG = "v1.4.37";
 
 const MARKETPLACE_NAME = "aw-marketplace";
 const PLUGIN_KEY = `aw@${MARKETPLACE_NAME}`;
 
 function eccDir() { return join(homedir(), ".aw-ecc"); }
 
-// "claude" runs install-apply.js --without baseline:commands so hooks, rules,
-// and agents land in ~/.claude/ — but commands are skipped because the plugin
-// marketplace (installClaudePlugin) already registers them under /aw:tdd.
-// File-copying commands would create a duplicate flat /tdd alongside /aw:tdd.
+// "claude" uses a no-commands module set so hooks, rules, shared references,
+// and install-state land in ~/.claude/ — while slash commands stay owned by
+// the marketplace plugin under /aw:*.
+// Using `--without baseline:commands` with broader profiles is unsafe because
+// some optional modules depend on commands-core and cause install-apply to fail.
 const FILE_COPY_TARGETS = ["claude", "cursor", "codex"];
+const CLAUDE_FILE_COPY_MODULES = [
+  "rules-core",
+  "agents-core",
+  "hooks-runtime",
+  "platform-configs",
+  "workflow-quality",
+];
 
 const TARGET_STATE = {
   claude: { state: ".claude/ecc/install-state.json" },
@@ -40,6 +49,20 @@ function run(cmd, opts = {}) {
   return execSync(cmd, { stdio: "pipe", ...opts });
 }
 
+function fetchOverrideRef(dest, ref) {
+  run(`git -C ${dest} fetch --quiet --depth 1 origin ${ref}`);
+  run(`git -C ${dest} checkout --quiet FETCH_HEAD`);
+}
+
+function cloneWithRef(url, ref, dest) {
+  try {
+    run(`git clone --quiet --depth 1 --branch ${ref} "${url}" "${dest}"`);
+  } catch {
+    run(`git clone --quiet --depth 1 "${url}" "${dest}"`);
+    fetchOverrideRef(dest, ref);
+  }
+}
+
 function readIfExists(path) {
   try { return existsSync(path) ? readFileSync(path, "utf8") : null; } catch { return null; }
 }
@@ -96,20 +119,39 @@ function relProtectedPath(absPath, home) {
 function cloneOrUpdate(tag, dest) {
   // AW_ECC_CLONE_URL overrides the remote (used in tests to point at a local fake repo)
   const overrideUrl = process.env.AW_ECC_CLONE_URL;
+  // AW_ECC_CLONE_REF lets aw init install ECC from a non-default branch or tag.
+  const overrideRef = process.env.AW_ECC_CLONE_REF?.trim();
 
   if (existsSync(join(dest, ".git"))) {
     try {
-      if (!overrideUrl) {
+      if (!overrideUrl && !overrideRef) {
         run(`git -C ${dest} fetch --quiet --depth 1 origin tag ${tag}`);
         run(`git -C ${dest} checkout --quiet ${tag}`);
+      } else {
+        if (overrideUrl) {
+          run(`git -C ${dest} remote set-url origin "${overrideUrl}"`);
+        }
+        fetchOverrideRef(dest, overrideRef || tag);
       }
       return;
     } catch { /* fall through to fresh clone */ }
   }
   if (existsSync(dest)) rmSync(dest, { recursive: true, force: true });
   if (overrideUrl) {
-    run(`git clone --quiet --depth 1 "${overrideUrl}" "${dest}"`);
+    if (overrideRef) {
+      cloneWithRef(overrideUrl, overrideRef, dest);
+    } else {
+      run(`git clone --quiet --depth 1 "${overrideUrl}" "${dest}"`);
+    }
   } else {
+    if (overrideRef) {
+      try {
+        cloneWithRef(AW_ECC_REPO_SSH, overrideRef, dest);
+      } catch {
+        cloneWithRef(AW_ECC_REPO_HTTPS, overrideRef, dest);
+      }
+      return;
+    }
     try {
       run(`git clone --quiet --depth 1 --branch ${tag} ${AW_ECC_REPO_SSH} ${dest}`);
     } catch {
@@ -118,6 +160,32 @@ function cloneOrUpdate(tag, dest) {
   }
 }
 
+/**
+ * Transform canonical /aw: references to Cursor-compatible /aw- in installed
+ * skill and rule files. Cursor namespaces commands via directory structure
+ * (commands/aw/plan.md → /aw-plan) rather than colons.
+ */
+function transformCursorAwRefs(home) {
+  const dirs = [
+    join(home, ".cursor", "skills"),
+    join(home, ".cursor", "rules"),
+  ];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    for (const entry of readdirSync(dir, { withFileTypes: true, recursive: true })) {
+      if (!entry.isFile()) continue;
+      const ext = entry.name.split(".").pop();
+      if (!["md", "mdc"].includes(ext)) continue;
+      const filePath = join(entry.parentPath || entry.path, entry.name);
+      try {
+        const content = readFileSync(filePath, "utf8");
+        if (!content.includes("/aw:")) continue;
+        writeFileSync(filePath, content.replace(/\/aw:/g, "/aw-"));
+      } catch { /* best effort */ }
+    }
+  }
+}
+
 function installClaudePlugin(repoDir) {
   // Always remove first so we re-register from the correct repoDir.
   // Falling back to `marketplace update` is unsafe — it updates from the
@@ -174,7 +242,8 @@ function namespaceCursorCommands(home) {
 
 /**
  * Run scripts/sync-ecc-to-codex.sh from the cloned ecc repo.
- * Generates ~/.codex/prompts/ecc-*.md (Codex equivalent of slash commands)
+ * Generates ~/.codex/prompts/*.md (Codex equivalent of slash commands),
+ * using aw-*.md for AW-namespaced commands and ecc-*.md for the rest,
  * and merges ~/.codex/AGENTS.md. Best-effort — failure doesn't block init.
  */
 function syncEccToCodex(repoDir) {
@@ -185,25 +254,6 @@ function syncEccToCodex(repoDir) {
   } catch { /* best effort — codex sync failure is non-blocking */ }
 }
 
-/**
- * Run ECC repair after install so managed home manifests self-heal when local
- * hook/config files have drifted. This is especially important for Codex where
- * hook registration and wrapper scripts can get out of sync with ~/.aw-ecc.
- */
-function repairEccInstall(repoDir, targets) {
-  const repairScript = join(repoDir, "scripts", "repair.js");
-  if (!existsSync(repairScript) || !Array.isArray(targets) || targets.length === 0) return;
-
-  const targetArgs = targets
-    .filter(Boolean)
-    .map((target) => ` --target ${target}`)
-    .join("");
-
-  try {
-    run(`node "${repairScript}"${targetArgs}`, { cwd: homedir() });
-  } catch { /* best effort — repair failure is non-blocking */ }
-}
-
 export async function installAwEcc(
   cwd,
   { targets = ["cursor", "claude", "codex"], silent = false } = {},
@@ -232,25 +282,41 @@ export async function installAwEcc(
       run("npm install --no-audit --no-fund --ignore-scripts --loglevel=error", {
         cwd: repoDir,
       });
+      // generate-aw-hooks.js produces hooks.json and hook script sources that
+      // install-apply.js needs.  npm install uses --ignore-scripts so the
+      // prepare script (which normally runs this) is skipped — call explicitly.
+      const generateHooksScript = join(repoDir, "scripts", "generate-aw-hooks.js");
+      if (existsSync(generateHooksScript)) {
+        try {
+          run(`node "${generateHooksScript}"`, { cwd: repoDir });
+        } catch { /* best effort — older engine versions may not have this script */ }
+      }
       for (const target of fileCopyTargets) {
         try {
           const snapshot = snapshotProtectedConfigs(home, target);
 
           // Always use HOME as cwd so files land in ~/.<target>/ globally.
           const runCwd = homedir();
-          // For claude: skip commands (plugin handles them as /aw:tdd) but
-          // install hooks, rules, agents into ~/.claude/.
-          const withoutFlag = target === "claude" ? " --without baseline:commands" : "";
+          // For claude: install the safe no-commands module set. The plugin
+          // already owns /aw:* command registration, and broader profiles with
+          // `--without baseline:commands` can fail on commands-core deps.
+          const installArgs = target === "claude"
+            ? `--target ${target} --modules ${CLAUDE_FILE_COPY_MODULES.join(",")}`
+            : `--target ${target} --profile full`;
           run(
-            `node ${join(repoDir, "scripts/install-apply.js")} --target ${target} --profile full${withoutFlag}`,
+            `node ${join(repoDir, "scripts/install-apply.js")} ${installArgs}`,
             { cwd: runCwd },
           );
           // Move cursor commands into aw/ subfolder for namespace consistency
           // so they're accessible as /aw:tdd, /aw:plan — same as Claude Code plugin.
           if (target === "cursor") {
             namespaceCursorCommands(runCwd);
+            // Cursor commands use hyphens (commands/aw/plan.md -> /aw-plan)
+            // but source skill/rule files use canonical colons (/aw:plan).
+            // Transform /aw: -> /aw- in installed cursor skill/rule files.
+            transformCursorAwRefs(home);
           }
-          // Run sync script for codex: generates ~/.codex/prompts/ecc-*.md and
+          // Run sync script for codex: generates ~/.codex/prompts/*.md and
           // merges AGENTS.md — Codex has no slash commands, so prompts are the
           // equivalent of commands.
           if (target === "codex") {
@@ -262,13 +328,10 @@ export async function installAwEcc(
           restoreProtectedConfigs(snapshot);
         } catch { /* target not supported — skip */ }
       }
-
-      // Enforce post-install parity for managed home files after all target-
-      // specific steps have run. This catches drifted local manifests that the
-      // initial install/sync path may otherwise leave partially updated.
-      repairEccInstall(repoDir, fileCopyTargets);
     }
 
+    applyStoredStartupPreferences();
+
     if (!silent) fmt.logSuccess("aw-ecc engine installed");
   } catch (err) {
     if (!silent) fmt.logWarn(`aw-ecc install failed: ${err.message}`);
@@ -312,17 +375,42 @@ export function uninstallAwEcc({ silent = false } = {}) {
     } catch { /* corrupted state — skip */ }
   }
 
-  // Codex: remove ecc prompt files generated by sync-ecc-to-codex.sh
-  // (not tracked in install-state — cleaned by prefix pattern ecc-*.md)
+  // Codex: remove generated prompt files from sync-ecc-to-codex.sh
+  // (not tracked in install-state — cleaned via manifests, with prefix fallback)
   const codexPromptsDir = join(HOME, ".codex", "prompts");
   if (existsSync(codexPromptsDir)) {
     try {
-      for (const file of readdirSync(codexPromptsDir)) {
-        if (file.startsWith("ecc-") && file.endsWith(".md")) {
-          rmSync(join(codexPromptsDir, file), { force: true });
+      const promptFiles = new Set();
+      for (const manifestName of ["ecc-prompts-manifest.txt", "ecc-extension-prompts-manifest.txt"]) {
+        const manifestPath = join(codexPromptsDir, manifestName);
+        if (!existsSync(manifestPath)) continue;
+        try {
+          const entries = readFileSync(manifestPath, "utf8")
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean);
+          for (const entry of entries) promptFiles.add(entry);
+        } catch { /* best effort */ }
+        rmSync(manifestPath, { force: true });
+      }
+
+      for (const file of promptFiles) {
+        const promptPath = join(codexPromptsDir, file);
+        if (existsSync(promptPath)) {
+          rmSync(promptPath, { force: true });
           removed++;
         }
       }
+
+      for (const file of readdirSync(codexPromptsDir)) {
+        const isLegacyGeneratedPrompt = file.endsWith(".md")
+          && (file.startsWith("ecc-") || file.startsWith("aw-"));
+        if (!isLegacyGeneratedPrompt) continue;
+
+        rmSync(join(codexPromptsDir, file), { force: true });
+        removed++;
+      }
+
       pruneEmptyParents(codexPromptsDir, join(HOME, ".codex"));
     } catch { /* best effort */ }
   }

package/git.mjs

@@ -124,34 +124,15 @@ export async function initPersistentClone(repoUrl, awHome, sparsePaths) {
   }
 
   try {
-    execSync(`git clone --filter=blob:none --no-checkout "${repoUrl}" "${awHome}"`, {
-      stdio: 'pipe',
-      encoding: 'utf8',
-      env: {
-        ...process.env,
-        GIT_TERMINAL_PROMPT: process.env.GIT_TERMINAL_PROMPT ?? '0',
-      },
-    });
+    await exec(`git clone --filter=blob:none --no-checkout "${repoUrl}" "${awHome}"`);
   } catch (e) {
     throw new Error(`Failed to clone ${repoUrl}: ${e.message}`);
   }
 
   try {
-    execSync('git sparse-checkout init --no-cone', {
-      cwd: awHome,
-      stdio: 'pipe',
-      encoding: 'utf8',
-    });
-    execSync(`git sparse-checkout set ${sparsePaths.map(p => `"${p}"`).join(' ')}`, {
-      cwd: awHome,
-      stdio: 'pipe',
-      encoding: 'utf8',
-    });
-    execSync(`git checkout ${REGISTRY_BASE_BRANCH}`, {
-      cwd: awHome,
-      stdio: 'pipe',
-      encoding: 'utf8',
-    });
+    await exec('git sparse-checkout init --no-cone', { cwd: awHome });
+    await exec(`git sparse-checkout set ${sparsePaths.map(p => `"${p}"`).join(' ')}`, { cwd: awHome });
+    await exec(`git checkout ${REGISTRY_BASE_BRANCH}`, { cwd: awHome });
   } catch (e) {
     throw new Error(`Failed to configure sparse checkout: ${e.message}`);
   }

package/hook-manifest.mjs

@@ -0,0 +1,195 @@
+export const AW_HOOK_PHASES = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PostToolUse',
+  'Stop',
+  'SessionEnd',
+  'PostToolUseFailure',
+  'PreCompact',
+];
+
+const REQUIRED = 'required';
+const EXTENDED = 'extended';
+
+const NATIVE = 'native';
+const EQUIVALENT = 'equivalent';
+const UNSUPPORTED = 'unsupported';
+
+export const AW_HOOK_MANIFEST = [
+  {
+    phase: 'SessionStart',
+    tier: REQUIRED,
+    sharedImplementation: 'session-start',
+    harnesses: {
+      claude: {
+        home: { status: NATIVE, events: ['SessionStart'] },
+        workspace: { status: NATIVE, events: ['SessionStart'] },
+      },
+      codex: {
+        home: { status: NATIVE, events: ['SessionStart'] },
+        workspace: { status: NATIVE, events: ['SessionStart'] },
+      },
+      cursor: {
+        home: { status: NATIVE, events: ['sessionStart'] },
+        workspace: { status: NATIVE, events: ['sessionStart'] },
+      },
+    },
+  },
+  {
+    phase: 'UserPromptSubmit',
+    tier: REQUIRED,
+    sharedImplementation: 'user-prompt-submit',
+    harnesses: {
+      claude: {
+        home: { status: NATIVE, events: ['UserPromptSubmit'] },
+        workspace: { status: NATIVE, events: ['UserPromptSubmit'] },
+      },
+      codex: {
+        home: { status: NATIVE, events: ['UserPromptSubmit'] },
+        workspace: { status: NATIVE, events: ['UserPromptSubmit'] },
+      },
+      cursor: {
+        home: { status: EQUIVALENT, events: ['beforeSubmitPrompt'] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+    },
+  },
+  {
+    phase: 'PreToolUse',
+    tier: REQUIRED,
+    sharedImplementation: 'pre-tool-use',
+    harnesses: {
+      claude: {
+        home: { status: NATIVE, events: ['PreToolUse'] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+      codex: {
+        home: { status: NATIVE, events: ['PreToolUse'] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+      cursor: {
+        home: { status: EQUIVALENT, events: ['beforeShellExecution', 'beforeMCPExecution'] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+    },
+  },
+  {
+    phase: 'PostToolUse',
+    tier: REQUIRED,
+    sharedImplementation: 'post-tool-use',
+    harnesses: {
+      claude: {
+        home: { status: NATIVE, events: ['PostToolUse'] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+      codex: {
+        home: { status: NATIVE, events: ['PostToolUse'] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+      cursor: {
+        home: { status: EQUIVALENT, events: ['afterShellExecution', 'afterFileEdit', 'afterMCPExecution'] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+    },
+  },
+  {
+    phase: 'Stop',
+    tier: REQUIRED,
+    sharedImplementation: 'stop',
+    harnesses: {
+      claude: {
+        home: { status: NATIVE, events: ['Stop'] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+      codex: {
+        home: { status: NATIVE, events: ['Stop'] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+      cursor: {
+        home: { status: NATIVE, events: ['stop'] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+    },
+  },
+  {
+    phase: 'SessionEnd',
+    tier: EXTENDED,
+    sharedImplementation: 'session-end',
+    harnesses: {
+      claude: {
+        home: { status: UNSUPPORTED, events: [] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+      codex: {
+        home: { status: UNSUPPORTED, events: [] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+      cursor: {
+        home: { status: NATIVE, events: ['sessionEnd'] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+    },
+  },
+  {
+    phase: 'PostToolUseFailure',
+    tier: EXTENDED,
+    sharedImplementation: 'post-tool-use-failure',
+    harnesses: {
+      claude: {
+        home: { status: NATIVE, events: ['PostToolUseFailure'] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+      codex: {
+        home: { status: UNSUPPORTED, events: [] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+      cursor: {
+        home: { status: UNSUPPORTED, events: [] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+    },
+  },
+  {
+    phase: 'PreCompact',
+    tier: EXTENDED,
+    sharedImplementation: 'pre-compact',
+    harnesses: {
+      claude: {
+        home: { status: NATIVE, events: ['PreCompact'] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+      codex: {
+        home: { status: UNSUPPORTED, events: [] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+      cursor: {
+        home: { status: NATIVE, events: ['preCompact'] },
+        workspace: { status: UNSUPPORTED, events: [] },
+      },
+    },
+  },
+];
+
+export function getHookManifestEntry(phase) {
+  const entry = AW_HOOK_MANIFEST.find(item => item.phase === phase);
+  if (!entry) {
+    throw new Error(`Unknown AW hook phase: ${phase}`);
+  }
+  return entry;
+}
+
+export function getHarnessPhaseEntries(harness, surface = 'home') {
+  return AW_HOOK_MANIFEST.map(entry => ({
+    ...entry,
+    harness: entry.harnesses[harness]?.[surface] || { status: UNSUPPORTED, events: [] },
+  }));
+}
+
+export function getSupportedHarnessPhaseEntries(harness, surface = 'home') {
+  return getHarnessPhaseEntries(harness, surface).filter(entry => entry.harness.status !== UNSUPPORTED);
+}
+
+export function getRequiredHarnessPhaseEntries(harness, surface = 'home') {
+  return getSupportedHarnessPhaseEntries(harness, surface).filter(entry => entry.tier === REQUIRED);
+}