failproofai 0.0.2-beta.6 → 0.0.2-beta.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "0.0.2-beta.6",
+  "version": "0.0.2-beta.8",
   "description": "The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously — for Claude Code & the Agents SDK",
   "bin": {
     "failproofai": "./dist/cli.mjs"

package/src/hooks/builtin-policies.ts

@@ -168,6 +168,50 @@ function getCurrentBranch(cwd: string): string | null {
   }
 }
 
+function getHeadSha(cwd: string): string | null {
+  try {
+    const sha = execSync("git rev-parse HEAD", {
+      cwd,
+      encoding: "utf8",
+      timeout: 3000,
+    }).trim();
+    return sha || null;
+  } catch {
+    return null;
+  }
+}
+
+interface CiCheck {
+  name: string;
+  status: string;
+  conclusion: string;
+}
+
+/** Fetch third-party check runs (non-GitHub-Actions) for a commit via the Checks API. */
+function getThirdPartyCheckRuns(cwd: string, sha: string): CiCheck[] {
+  try {
+    const json = execFileSync(
+      "gh",
+      [
+        "api",
+        `repos/{owner}/{repo}/commits/${sha}/check-runs`,
+        "--jq",
+        '.check_runs | map(select(.app.slug != "github-actions")) | map({name: .name, status: .status, conclusion: (.conclusion // "")})',
+      ],
+      {
+        cwd,
+        encoding: "utf8",
+        timeout: 15000,
+      },
+    ).trim();
+
+    if (!json || json === "[]") return [];
+    return JSON.parse(json) as CiCheck[];
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Check if a command matches an allow pattern using token-by-token comparison.
  * The "*" token is a wildcard. Extra command tokens beyond the pattern are allowed,
@@ -1013,27 +1057,35 @@ function requireCiGreenBeforeStop(ctx: PolicyContext): PolicyResult {
     const branch = getCurrentBranch(cwd);
     if (!branch || branch === "HEAD") return allow("Detached HEAD, skipping CI check.");
 
-    const runsJson = execFileSync(
-      "gh",
-      ["run", "list", "--branch", branch, "--limit", "5", "--json", "status,conclusion,name"],
-      {
-        cwd,
-        encoding: "utf8",
-        timeout: 15000,
-      },
-    ).trim();
+    // 1. GitHub Actions workflow runs
+    let workflowRuns: CiCheck[] = [];
+    try {
+      const runsJson = execFileSync(
+        "gh",
+        ["run", "list", "--branch", branch, "--limit", "5", "--json", "status,conclusion,name"],
+        { cwd, encoding: "utf8", timeout: 15000 },
+      ).trim();
 
-    if (!runsJson || runsJson === "[]") return allow(`No CI runs found for branch "${branch}".`);
+      if (runsJson && runsJson !== "[]") {
+        workflowRuns = JSON.parse(runsJson) as CiCheck[];
+      }
+    } catch {
+      // fail-open for workflow runs; continue to check third-party checks
+    }
+
+    // 2. Third-party check runs (CodeRabbit, SonarCloud, Codecov, etc.)
+    let thirdPartyChecks: CiCheck[] = [];
+    const sha = getHeadSha(cwd);
+    if (sha) {
+      thirdPartyChecks = getThirdPartyCheckRuns(cwd, sha);
+    }
 
-    const runs = JSON.parse(runsJson) as Array<{
-      status: string;
-      conclusion: string;
-      name: string;
-    }>;
+    // 3. Merge all checks
+    const allChecks = [...workflowRuns, ...thirdPartyChecks];
 
-    if (runs.length === 0) return allow(`No CI runs found for branch "${branch}".`);
+    if (allChecks.length === 0) return allow(`No CI runs found for branch "${branch}".`);
 
-    const failing = runs.filter(
+    const failing = allChecks.filter(
       (r) => r.status === "completed" && r.conclusion !== "success" && r.conclusion !== "skipped",
     );
     if (failing.length > 0) {
@@ -1043,7 +1095,7 @@ function requireCiGreenBeforeStop(ctx: PolicyContext): PolicyResult {
       );
     }
 
-    const pending = runs.filter(
+    const pending = allChecks.filter(
       (r) => r.status === "in_progress" || r.status === "queued" || r.status === "waiting",
     );
     if (pending.length > 0) {

package/src/hooks/custom-hooks-loader.ts

@@ -1,39 +1,51 @@
 /**
- * Loads a user-authored hooks.js file with ESM import rewriting.
+ * Loads user-authored policy files with ESM import rewriting.
  * Supports transitive local imports and `import { ... } from 'failproofai'`.
  *
+ * Two loading modes:
+ * 1. Explicit: a single file via `customPoliciesPath` in policies-config.json
+ * 2. Convention: auto-discovered *policies.{js,mjs,ts} files from
+ *    .failproofai/policies/ at project and user level (git-hooks style)
+ *
  * Fail-open: any error (file not found, syntax error, import failure) is logged
- * and results in an empty hook list. Builtins continue running normally.
+ * and results in an empty hook list for that file. Builtins continue normally.
  */
-import { resolve, isAbsolute } from "node:path";
-import { existsSync } from "node:fs";
+import { resolve, isAbsolute, basename } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
 import { pathToFileURL } from "node:url";
-import { hookLogWarn, hookLogError } from "./hook-logger";
+import { homedir } from "node:os";
+import { hookLogWarn, hookLogError, hookLogInfo } from "./hook-logger";
 import { getCustomHooks, clearCustomHooks } from "./custom-hooks-registry";
 import { findDistIndex, rewriteFileTree, TMP_SUFFIX, cleanupTmpFiles } from "./loader-utils";
 import type { CustomHook } from "./policy-types";
 
 const LOADING_KEY = "__FAILPROOFAI_LOADING_HOOKS__";
 
-export async function loadCustomHooks(
-  customPoliciesPath: string | undefined,
-  opts?: { strict?: boolean },
-): Promise<CustomHook[]> {
-  if (!customPoliciesPath) return [];
+/** Regex matching convention policy filenames: *policies.{js,mjs,ts} */
+const CONVENTION_FILE_RE = /policies\.(js|mjs|ts)$/;
 
-  const absPath = isAbsolute(customPoliciesPath)
-    ? customPoliciesPath
-    : resolve(process.cwd(), customPoliciesPath);
-
-  if (!existsSync(absPath)) {
-    if (opts?.strict) throw new Error(`Custom hooks file not found: ${absPath}`);
-    hookLogWarn(`customPoliciesPath not found: ${absPath}`);
+/**
+ * Scan a directory for convention policy files (*policies.{js,mjs,ts}).
+ * Returns sorted absolute paths. Returns [] if the directory doesn't exist.
+ */
+export function discoverPolicyFiles(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isFile() && CONVENTION_FILE_RE.test(e.name))
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .map((e) => resolve(dir, e.name));
+  } catch {
     return [];
   }
+}
 
-  // Clear registry before loading so each invocation starts fresh
-  clearCustomHooks();
-
+/**
+ * Load a single policy file into the globalThis custom hooks registry.
+ * Does NOT clear the registry — caller is responsible for that.
+ */
+async function loadSingleFile(absPath: string, opts?: { strict?: boolean }): Promise<void> {
   const g = globalThis as Record<string, unknown>;
   g[LOADING_KEY] = true;
 
@@ -51,11 +63,143 @@ export async function loadCustomHooks(
     const msg = err instanceof Error ? err.message : String(err);
     if (opts?.strict) throw new Error(`Failed to load custom hooks from ${absPath}: ${msg}`);
     hookLogError(`failed to load custom hooks from ${absPath}: ${msg}`);
-    return [];
   } finally {
     g[LOADING_KEY] = false;
     await cleanupTmpFiles(tmpFiles);
   }
+}
+
+/**
+ * Load a single explicit custom hooks file (legacy API).
+ * Clears the registry, loads the file, returns registered hooks.
+ */
+export async function loadCustomHooks(
+  customPoliciesPath: string | undefined,
+  opts?: { strict?: boolean; sessionCwd?: string },
+): Promise<CustomHook[]> {
+  if (!customPoliciesPath) return [];
+
+  const absPath = isAbsolute(customPoliciesPath)
+    ? customPoliciesPath
+    : resolve(opts?.sessionCwd ?? process.cwd(), customPoliciesPath);
+
+  if (!existsSync(absPath)) {
+    if (opts?.strict) throw new Error(`Custom hooks file not found: ${absPath}`);
+    hookLogWarn(`customPoliciesPath not found: ${absPath}`);
+    return [];
+  }
 
+  clearCustomHooks();
+  await loadSingleFile(absPath, opts);
   return getCustomHooks();
 }
+
+/** Source metadata for a loaded convention policy file. */
+export interface ConventionSource {
+  scope: "project" | "user";
+  file: string;
+  hookNames: string[];
+}
+
+/** Result of loadAllCustomHooks with source metadata. */
+export interface LoadAllResult {
+  hooks: CustomHook[];
+  conventionSources: ConventionSource[];
+}
+
+/**
+ * Load ALL custom hooks: explicit customPoliciesPath + convention-discovered files.
+ *
+ * Load order:
+ * 1. Explicit customPoliciesPath (if configured)
+ * 2. Project convention: {cwd}/.failproofai/policies/*policies.{js,mjs,ts} (alphabetical)
+ * 3. User convention: ~/.failproofai/policies/*policies.{js,mjs,ts} (alphabetical)
+ *
+ * Each file is loaded independently (fail-open per file).
+ * Convention hooks are tagged with __conventionScope so the handler can build scoped prefixes.
+ */
+export async function loadAllCustomHooks(
+  customPoliciesPath: string | undefined,
+  opts?: { sessionCwd?: string },
+): Promise<LoadAllResult> {
+  clearCustomHooks();
+
+  const conventionSources: ConventionSource[] = [];
+
+  // 1. Explicit customPoliciesPath (existing behavior)
+  if (customPoliciesPath) {
+    const absPath = isAbsolute(customPoliciesPath)
+      ? customPoliciesPath
+      : resolve(opts?.sessionCwd ?? process.cwd(), customPoliciesPath);
+    if (existsSync(absPath)) {
+      await loadSingleFile(absPath);
+    } else {
+      hookLogWarn(`customPoliciesPath not found: ${absPath}`);
+    }
+  }
+
+  const hooksBeforeConvention = getCustomHooks().length;
+
+  // 2. Project convention: {cwd}/.failproofai/policies/*policies.{js,mjs,ts}
+  const projectDir = resolve(opts?.sessionCwd ?? process.cwd(), ".failproofai", "policies");
+  const projectFiles = discoverPolicyFiles(projectDir);
+  for (const file of projectFiles) {
+    const hooksBefore = getCustomHooks().length;
+    await loadSingleFile(file);
+    const newHooks = getCustomHooks().slice(hooksBefore);
+    if (newHooks.length > 0) {
+      conventionSources.push({
+        scope: "project",
+        file: basename(file),
+        hookNames: newHooks.map((h) => h.name),
+      });
+    }
+  }
+
+  // 3. User convention: ~/.failproofai/policies/*policies.{js,mjs,ts}
+  const userDir = resolve(homedir(), ".failproofai", "policies");
+  const userFiles = discoverPolicyFiles(userDir);
+  for (const file of userFiles) {
+    const hooksBefore = getCustomHooks().length;
+    await loadSingleFile(file);
+    const newHooks = getCustomHooks().slice(hooksBefore);
+    if (newHooks.length > 0) {
+      conventionSources.push({
+        scope: "user",
+        file: basename(file),
+        hookNames: newHooks.map((h) => h.name),
+      });
+    }
+  }
+
+  const allHooks = getCustomHooks();
+  const conventionCount = allHooks.length - hooksBeforeConvention;
+
+  if (projectFiles.length > 0 || userFiles.length > 0) {
+    hookLogInfo(
+      `convention policies: ${projectFiles.length} project file(s), ${userFiles.length} user file(s), ${conventionCount} hook(s)`,
+    );
+  }
+
+  // Tag convention hooks with their scope so the handler can build scoped prefixes.
+  // Build a name→scope map from conventionSources, then tag by object reference
+  // to avoid mis-tagging an explicit custom hook that shares the same name.
+  const hookNameToScope = new Map<string, string>();
+  for (const source of conventionSources) {
+    for (const name of source.hookNames) {
+      hookNameToScope.set(name, source.scope);
+    }
+  }
+  const conventionHookRefs = new Set<CustomHook>();
+  for (const hook of allHooks.slice(hooksBeforeConvention)) {
+    conventionHookRefs.add(hook);
+  }
+  for (const hook of allHooks) {
+    if (conventionHookRefs.has(hook)) {
+      (hook as CustomHook & { __conventionScope?: string }).__conventionScope =
+        hookNameToScope.get(hook.name) ?? "project";
+    }
+  }
+
+  return { hooks: allHooks, conventionSources };
+}

package/src/hooks/handler.ts

@@ -11,7 +11,8 @@ import { readMergedHooksConfig } from "./hooks-config";
 import { registerBuiltinPolicies } from "./builtin-policies";
 import { evaluatePolicies } from "./policy-evaluator";
 import { clearPolicies, registerPolicy } from "./policy-registry";
-import { loadCustomHooks } from "./custom-hooks-loader";
+import { loadAllCustomHooks } from "./custom-hooks-loader";
+import type { CustomHook } from "./policy-types";
 import { persistHookActivity } from "./hook-activity-store";
 import { trackHookEvent } from "./hook-telemetry";
 import { getInstanceId } from "../../lib/telemetry-id";
@@ -71,9 +72,15 @@ export async function handleHookEvent(eventType: string): Promise<number> {
   registerBuiltinPolicies(config.enabledPolicies);
 
   // Load and register custom hooks (layer 2, after builtins)
-  const customHooksList = await loadCustomHooks(config.customPoliciesPath);
+  const loadResult = await loadAllCustomHooks(config.customPoliciesPath, { sessionCwd: session.cwd });
+  const customHooksList = loadResult.hooks;
+  const conventionHookNames = new Set(loadResult.conventionSources.flatMap((s) => s.hookNames));
+
   for (const hook of customHooksList) {
     const hookName = hook.name;
+    const conventionScope = (hook as CustomHook & { __conventionScope?: string }).__conventionScope;
+    const isConvention = !!conventionScope;
+    const prefix = isConvention ? `.failproofai-${conventionScope}` : "custom";
     const fn: PolicyFunction = async (ctx): Promise<PolicyResult> => {
       try {
         const result = await Promise.race([
@@ -86,17 +93,19 @@ export async function handleHookEvent(eventType: string): Promise<number> {
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         const isTimeout = msg === "timeout";
-        hookLogWarn(`custom hook "${hookName}" failed: ${msg}`);
+        hookLogWarn(`${prefix} hook "${hookName}" failed: ${msg}`);
         void trackHookEvent(getInstanceId(), "custom_hook_error", {
           hook_name: hookName,
           error_type: isTimeout ? "timeout" : "exception",
           event_type: eventType,
+          is_convention_policy: isConvention,
+          convention_scope: conventionScope ?? null,
         });
         return { decision: "allow" };
       }
     };
     registerPolicy(
-      `custom/${hookName}`,
+      `${prefix}/${hookName}`,
       hook.description ?? "",
       fn,
       hook.match ?? {},
@@ -113,7 +122,18 @@ export async function handleHookEvent(eventType: string): Promise<number> {
     });
   }
 
-  hookLogInfo(`event=${eventType} policies=${config.enabledPolicies.length} custom=${customHooksList.length}`);
+  // Fire telemetry for convention-based policy discovery
+  if (loadResult.conventionSources.length > 0) {
+    void trackHookEvent(getInstanceId(), "convention_policies_loaded", {
+      event_type: eventType,
+      project_file_count: loadResult.conventionSources.filter((s) => s.scope === "project").length,
+      user_file_count: loadResult.conventionSources.filter((s) => s.scope === "user").length,
+      convention_hook_count: conventionHookNames.size,
+      convention_hook_names: [...conventionHookNames],
+    });
+  }
+
+  hookLogInfo(`event=${eventType} policies=${config.enabledPolicies.length} custom=${customHooksList.length} convention=${conventionHookNames.size}`);
 
   // Evaluate policies
   const result = await evaluatePolicies(eventType as HookEventType, parsed, session, config);
@@ -152,8 +172,12 @@ export async function handleHookEvent(eventType: string): Promise<number> {
   if (result.decision === "deny" || result.decision === "instruct") {
     try {
       const isCustomHook = result.policyName?.startsWith("custom/") ?? false;
+      const isConventionPolicy = result.policyName?.startsWith(".failproofai-") ?? false;
+      const conventionScope = isConventionPolicy
+        ? result.policyName!.match(/^\.failproofai-(project|user)\//)?.[1] ?? null
+        : null;
       const hasCustomParams =
-        !isCustomHook && !!(result.policyName && config.policyParams?.[result.policyName]);
+        !isCustomHook && !isConventionPolicy && !!(result.policyName && config.policyParams?.[result.policyName]);
       const paramKeysOverridden = hasCustomParams
         ? Object.keys(config.policyParams![result.policyName!])
         : [];
@@ -164,6 +188,8 @@ export async function handleHookEvent(eventType: string): Promise<number> {
         policy_name: result.policyName,
         decision: result.decision,
         is_custom_hook: isCustomHook,
+        is_convention_policy: isConventionPolicy,
+        convention_scope: conventionScope,
         has_custom_params: hasCustomParams,
         param_keys_overridden: paramKeysOverridden,
       });

package/src/hooks/hooks-config.ts

@@ -5,6 +5,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { homedir } from "node:os";
 import type { HooksConfig } from "./policy-types";
+import type { HookScope } from "./types";
 import { hookLogInfo, hookLogWarn } from "./hook-logger";
 
 function readConfigAt(path: string): Partial<HooksConfig> {
@@ -100,14 +101,58 @@ export function writeHooksConfig(config: HooksConfig): void {
   writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
 }
 
+/**
+ * Resolve the policies-config path for a specific scope.
+ */
+export function getConfigPathForScope(scope: HookScope, cwd?: string): string {
+  const base = cwd ? resolve(cwd) : process.cwd();
+  switch (scope) {
+    case "user":
+      return resolve(homedir(), ".failproofai", "policies-config.json");
+    case "project":
+      return resolve(base, ".failproofai", "policies-config.json");
+    case "local":
+      return resolve(base, ".failproofai", "policies-config.local.json");
+  }
+}
+
+/**
+ * Read hooks config from a single specific scope (not merged).
+ */
+export function readScopedHooksConfig(scope: HookScope, cwd?: string): HooksConfig {
+  const configPath = getConfigPathForScope(scope, cwd);
+  if (!existsSync(configPath)) {
+    return { enabledPolicies: [] };
+  }
+  try {
+    const raw = readFileSync(configPath, "utf8");
+    return JSON.parse(raw) as HooksConfig;
+  } catch (err) {
+    hookLogWarn(`failed to parse config at ${configPath}: ${err instanceof Error ? err.message : String(err)}`);
+    return { enabledPolicies: [] };
+  }
+}
+
+/**
+ * Write hooks config to the scope-appropriate path.
+ */
+export function writeScopedHooksConfig(config: HooksConfig, scope: HookScope, cwd?: string): void {
+  const configPath = getConfigPathForScope(scope, cwd);
+  const dir = dirname(configPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+
 export interface ResolvedLlmConfig {
   baseUrl: string;
   apiKey: string;
   model: string;
 }
 
-export function readLlmConfig(): ResolvedLlmConfig | null {
-  const config = readHooksConfig();
+export function readLlmConfig(cwd?: string): ResolvedLlmConfig | null {
+  const config = readMergedHooksConfig(cwd);
   const baseUrl =
     process.env.FAILPROOFAI_LLM_BASE_URL ?? config.llm?.baseUrl ?? "https://api.openai.com/v1";
   const apiKey = process.env.FAILPROOFAI_LLM_API_KEY ?? config.llm?.apiKey;

package/src/hooks/llm-client.ts

@@ -30,9 +30,9 @@ export interface ChatCompletionResponse {
 
 export async function chatCompletion(
   messages: ChatMessage[],
-  options?: ChatCompletionOptions,
+  options?: ChatCompletionOptions & { cwd?: string },
 ): Promise<ChatCompletionResponse> {
-  const config = readLlmConfig();
+  const config = readLlmConfig(options?.cwd);
   if (!config) {
     throw new Error(
       "No LLM API key configured. Set FAILPROOFAI_LLM_API_KEY or configure llm.apiKey in policies-config.json",

package/src/hooks/loader-utils.ts

@@ -71,7 +71,8 @@ export async function resolveLocalImport(
 
 /**
  * Create an ESM shim that re-exports from the CJS dist module.
- * Includes all public API exports: createApp, customHooks, allow, deny, instruct.
+ * Exports the full public API of failproofai: customPolicies, allow, deny, instruct,
+ * getCustomHooks, clearCustomHooks.
  */
 export async function createEsmShim(
   distIndex: string,
@@ -80,10 +81,9 @@ export async function createEsmShim(
   const shimPath = distIndex + ".__failproofai_esm_shim__.mjs";
   const shimCode = [
     `import _cjs from '${distUrl}';`,
-    `export const createApp = _cjs.createApp;`,
-    `export const getQueueCondition = _cjs.getQueueCondition;`,
-    `export const clearQueueCondition = _cjs.clearQueueCondition;`,
     `export const customPolicies = _cjs.customPolicies;`,
+    `export const getCustomHooks = _cjs.getCustomHooks;`,
+    `export const clearCustomHooks = _cjs.clearCustomHooks;`,
     `export const allow = _cjs.allow;`,
     `export const deny = _cjs.deny;`,
     `export const instruct = _cjs.instruct;`,

package/src/hooks/manager.ts

@@ -3,7 +3,7 @@
  */
 import { execSync } from "node:child_process";
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, basename } from "node:path";
 import { homedir, platform, arch, release, hostname } from "node:os";
 import {
   HOOK_EVENT_TYPES,
@@ -15,10 +15,10 @@ import {
   type ClaudeSettings,
 } from "./types";
 import { promptPolicySelection } from "./install-prompt";
-import { readHooksConfig, writeHooksConfig, readMergedHooksConfig } from "./hooks-config";
+import { readMergedHooksConfig, readScopedHooksConfig, writeScopedHooksConfig } from "./hooks-config";
 import type { HooksConfig } from "./policy-types";
 import { BUILTIN_POLICIES } from "./builtin-policies";
-import { loadCustomHooks } from "./custom-hooks-loader";
+import { loadCustomHooks, discoverPolicyFiles } from "./custom-hooks-loader";
 import { trackHookEvent } from "./hook-telemetry";
 import { getInstanceId, hashToId } from "../../lib/telemetry-id";
 import { CliError } from "../cli-error";
@@ -203,7 +203,7 @@ export async function installHooks(
   const binaryPath = resolveFailproofaiBinary();
 
   // Capture existing config before overwriting (used for telemetry diff)
-  const previousConfig = readHooksConfig();
+  const previousConfig = readScopedHooksConfig(scope, cwd);
   const previousEnabled = new Set(previousConfig.enabledPolicies);
 
   let selectedPolicies: string[];
@@ -251,7 +251,7 @@ export async function installHooks(
       `\nValidated ${validatedHooks.length} custom hook(s): ${validatedHooks.map((h) => h.name).join(", ")}`,
     );
   }
-  writeHooksConfig(configToWrite);
+  writeScopedHooksConfig(configToWrite, scope, cwd);
   console.log(`\nEnabled ${selectedPolicies.length} policy(ies): ${selectedPolicies.join(", ")}`);
   if (removeCustomHooks) {
     console.log("Custom hooks path cleared.");
@@ -355,18 +355,21 @@ export async function installHooks(
  * @param opts.betaOnly — set to true when removing only beta policies (adds beta_only flag to telemetry)
  */
 export async function removeHooks(policyNames?: string[], scope: HookScope | "all" = "user", cwd?: string, opts?: { betaOnly?: boolean; source?: string; removeCustomHooks?: boolean }): Promise<void> {
+  // Resolve the effective config scope ("all" falls back to "user" for config reads/writes)
+  const configScope: HookScope = scope === "all" ? "user" : scope;
+
   // Clear custom hooks path if requested
   if (opts?.removeCustomHooks) {
-    const config = readHooksConfig();
+    const config = readScopedHooksConfig(configScope, cwd);
     delete config.customPoliciesPath;
-    writeHooksConfig(config);
+    writeScopedHooksConfig(config, configScope, cwd);
     console.log("Custom hooks path cleared.");
   }
 
   // Remove specific policies from config (keep hooks installed)
   if (policyNames && policyNames.length > 0 && !(policyNames.length === 1 && policyNames[0] === "all")) {
     validatePolicyNames(policyNames);
-    const config = readHooksConfig();
+    const config = readScopedHooksConfig(configScope, cwd);
     const removeSet = new Set(policyNames);
     const remaining = config.enabledPolicies.filter((p) => !removeSet.has(p));
     const notEnabled = policyNames.filter((p) => !config.enabledPolicies.includes(p));
@@ -382,7 +385,7 @@ export async function removeHooks(policyNames?: string[], scope: HookScope | "al
       enabledPolicies: remaining,
       ...(filteredParams && Object.keys(filteredParams).length > 0 ? { policyParams: filteredParams } : {}),
     };
-    writeHooksConfig(updatedConfig);
+    writeScopedHooksConfig(updatedConfig, configScope, cwd);
 
     // Telemetry: track policy-only removal from config
     try {
@@ -410,7 +413,7 @@ export async function removeHooks(policyNames?: string[], scope: HookScope | "al
   }
 
   // Capture enabled policies before clearing (used for accurate telemetry below)
-  const configBeforeRemoval = readHooksConfig();
+  const configBeforeRemoval = readScopedHooksConfig(configScope, cwd);
 
   // Remove all failproofai hooks from Claude Code settings
   const scopesToRemove: HookScope[] = scope === "all" ? [...HOOK_SCOPES] : [scope];
@@ -472,10 +475,19 @@ export async function removeHooks(policyNames?: string[], scope: HookScope | "al
   }
 
   // Clear policy config when removing from all scopes, or when no hooks remain in any scope
-  if (scope === "all" || !HOOK_SCOPES.some((s) => hooksInstalledInSettings(s, cwd))) {
-    const existingForClear = readHooksConfig();
-    const { customPoliciesPath: _drop, policyParams: _dropParams, ...restClear } = existingForClear;
-    writeHooksConfig({ ...restClear, enabledPolicies: [] });
+  if (scope === "all") {
+    // Clear config across all three scopes
+    for (const s of HOOK_SCOPES) {
+      const existing = readScopedHooksConfig(s, cwd);
+      if (existing.enabledPolicies.length > 0 || existing.customPoliciesPath || existing.policyParams) {
+        const { customPoliciesPath: _drop, policyParams: _dropParams, ...rest } = existing;
+        writeScopedHooksConfig({ ...rest, enabledPolicies: [] }, s, cwd);
+      }
+    }
+  } else if (!HOOK_SCOPES.some((s) => hooksInstalledInSettings(s, cwd))) {
+    const existing = readScopedHooksConfig(configScope, cwd);
+    const { customPoliciesPath: _drop, policyParams: _dropParams, ...rest } = existing;
+    writeScopedHooksConfig({ ...rest, enabledPolicies: [] }, configScope, cwd);
   }
 }
 
@@ -638,4 +650,35 @@ export async function listHooks(cwd?: string): Promise<void> {
     }
     console.log();
   }
+
+  // Convention Policies section (.failproofai/policies/*policies.{js,mjs,ts})
+  const base = cwd ? resolve(cwd) : process.cwd();
+  const conventionDirs: { label: string; dir: string }[] = [
+    { label: "Project", dir: resolve(base, ".failproofai", "policies") },
+    { label: "User", dir: resolve(homedir(), ".failproofai", "policies") },
+  ];
+
+  for (const { label, dir } of conventionDirs) {
+    const files = discoverPolicyFiles(dir);
+    if (files.length === 0) continue;
+
+    console.log(`\n  \u2500\u2500 Convention Policies \u2014 ${label} (${dir}) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    for (const file of files) {
+      try {
+        const hooks = await loadCustomHooks(file);
+        if (hooks.length === 0) {
+          const filename = basename(file);
+          console.log(`  \x1B[31m\u2717\x1B[0m       ${filename.padEnd(nameColWidth)}\x1B[31mfailed to load\x1B[0m`);
+        } else {
+          const filename = basename(file);
+          const hookSummary = hooks.map((h) => h.name).join(", ");
+          console.log(`  \x1B[32m\u2713\x1B[0m       ${filename.padEnd(nameColWidth)}${hooks.length} hook(s): ${hookSummary}`);
+        }
+      } catch {
+        const filename = basename(file);
+        console.log(`  \x1B[31m\u2717\x1B[0m       ${filename.padEnd(nameColWidth)}\x1B[31merror\x1B[0m`);
+      }
+    }
+    console.log();
+  }
 }