failproofai 0.0.2 → 0.0.3

package/dist/cli.mjs

@@ -149,11 +149,19 @@ function readMergedHooksConfig(cwd) {
     ...llm !== undefined ? { llm } : {}
   };
 }
-function getConfigPath() {
-  return resolve(homedir2(), ".failproofai", "policies-config.json");
+function getConfigPathForScope(scope, cwd) {
+  const base = cwd ? resolve(cwd) : process.cwd();
+  switch (scope) {
+    case "user":
+      return resolve(homedir2(), ".failproofai", "policies-config.json");
+    case "project":
+      return resolve(base, ".failproofai", "policies-config.json");
+    case "local":
+      return resolve(base, ".failproofai", "policies-config.local.json");
+  }
 }
-function readHooksConfig() {
-  const configPath = getConfigPath();
+function readScopedHooksConfig(scope, cwd) {
+  const configPath = getConfigPathForScope(scope, cwd);
   if (!existsSync2(configPath)) {
     return { enabledPolicies: [] };
   }
@@ -165,8 +173,8 @@ function readHooksConfig() {
     return { enabledPolicies: [] };
   }
 }
-function writeHooksConfig(config) {
-  const configPath = getConfigPath();
+function writeScopedHooksConfig(config, scope, cwd) {
+  const configPath = getConfigPathForScope(scope, cwd);
   const dir = dirname(configPath);
   if (!existsSync2(dir)) {
     mkdirSync2(dir, { recursive: true });
@@ -179,8 +187,8 @@ var init_hooks_config = __esm(() => {
 });
 
 // src/hooks/policy-helpers.ts
-function allow() {
-  return { decision: "allow" };
+function allow(reason) {
+  return reason ? { decision: "allow", reason } : { decision: "allow" };
 }
 function deny(reason) {
   return { decision: "deny", reason };
@@ -248,7 +256,7 @@ var REGISTRY_KEY = "__FAILPROOFAI_POLICY_REGISTRY__", INDEX_CACHE_KEY = "__FAILP
 // src/hooks/builtin-policies.ts
 import { resolve as resolve2, join as join2 } from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
-import { execSync } from "node:child_process";
+import { execSync, execFileSync } from "node:child_process";
 import { homedir as homedir3 } from "node:os";
 function isClaudeInternalPath(resolved2) {
   const claudeDir = join2(homedir3(), ".claude");
@@ -266,6 +274,53 @@ function getFilePath(ctx) {
 function parseArgvTokens(cmd) {
   return cmd.trim().split(/\s+/).map((t) => t.replace(/^['"]|['"]$/g, ""));
 }
+function getCurrentBranch(cwd) {
+  try {
+    let branch = gitBranchCache.get(cwd);
+    if (branch === undefined) {
+      branch = execSync("git rev-parse --abbrev-ref HEAD", {
+        cwd,
+        encoding: "utf8",
+        timeout: 3000
+      }).trim();
+      gitBranchCache.set(cwd, branch);
+    }
+    return branch || null;
+  } catch {
+    return null;
+  }
+}
+function getHeadSha(cwd) {
+  try {
+    const sha = execSync("git rev-parse HEAD", {
+      cwd,
+      encoding: "utf8",
+      timeout: 3000
+    }).trim();
+    return sha || null;
+  } catch {
+    return null;
+  }
+}
+function getThirdPartyCheckRuns(cwd, sha) {
+  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);
+  } catch {
+    return [];
+  }
+}
 function matchesAllowedPattern(cmd, pattern) {
   const cmdTokens = parseArgvTokens(cmd);
   const patTokens = parseArgvTokens(pattern);
@@ -480,7 +535,8 @@ function rmTargetIsAllowed(cmd, allowPaths) {
     if (rmIdx < 0)
       continue;
     const flagTokens = tokens.slice(rmIdx + 1).filter((t) => /^-[^-]/.test(t));
-    if (!/r/i.test(flagTokens.join("")))
+    const longFlagsInSeg = tokens.slice(rmIdx + 1).filter((t) => /^--/.test(t));
+    if (!/r/i.test(flagTokens.join("")) && !longFlagsInSeg.some((f) => /^--recursive$/i.test(f)))
       continue;
     const pathArgs = tokens.slice(rmIdx + 1).filter((t) => !t.startsWith("-"));
     for (const target of pathArgs) {
@@ -505,7 +561,10 @@ function blockRmRf(ctx) {
   if (ctx.toolName !== "Bash")
     return allow();
   const cmd = getCommand(ctx);
-  const hasDestructivePath = /(?:\/\s*$|\/\*|~)/.test(cmd);
+  const hasDestructivePath = parseArgvTokens(cmd).some((token) => {
+    const normalized = token.replace(/\/\*$/, "").replace(/\/+$/, "") || (token.startsWith("/") ? "/" : "");
+    return normalized === "/" || normalized === "~" || /^\/[A-Za-z_][\w.-]*$/.test(normalized);
+  });
   if (hasDestructivePath && (/rm\s+-[^\s]*r[^\s]*f[^\s]*/.test(cmd) || /rm\s+-[^\s]*f[^\s]*r[^\s]*/.test(cmd))) {
     const allowPaths = ctx.params?.allowPaths ?? [];
     if (rmTargetIsAllowed(cmd, allowPaths))
@@ -515,7 +574,10 @@ function blockRmRf(ctx) {
   if (hasDestructivePath && /\brm\b/.test(cmd)) {
     const tokens = parseArgvTokens(cmd);
     const shortFlags = tokens.filter((t) => /^-[^-]/.test(t)).join("");
-    if (/r/i.test(shortFlags) && /f/.test(shortFlags)) {
+    const longFlags = tokens.filter((t) => /^--/.test(t));
+    const hasRecursive = /r/i.test(shortFlags) || longFlags.some((f) => /^--recursive$/i.test(f));
+    const hasForce = /f/.test(shortFlags) || longFlags.some((f) => /^--force$/i.test(f));
+    if (hasRecursive && hasForce) {
       const allowPaths = ctx.params?.allowPaths ?? [];
       if (rmTargetIsAllowed(cmd, allowPaths))
         return allow();
@@ -653,22 +715,12 @@ function blockWorkOnMain(ctx) {
   const cwd = ctx.session?.cwd;
   if (!cwd)
     return allow();
-  try {
-    let branch = gitBranchCache.get(cwd);
-    if (branch === undefined) {
-      branch = execSync("git rev-parse --abbrev-ref HEAD", {
-        cwd,
-        encoding: "utf8",
-        timeout: 3000
-      }).trim();
-      gitBranchCache.set(cwd, branch);
-    }
-    const protectedBranches = ctx.params?.protectedBranches ?? ["main", "master"];
-    if (protectedBranches.includes(branch)) {
-      return deny(`Git ${cmd.match(/git\s+(\S+)/)?.[1] ?? "operation"} on ${branch} is blocked. Create a feature branch first.`);
-    }
-  } catch {
+  const branch = getCurrentBranch(cwd);
+  if (!branch)
     return allow();
+  const protectedBranches = ctx.params?.protectedBranches ?? ["main", "master"];
+  if (protectedBranches.includes(branch)) {
+    return deny(`Git ${cmd.match(/git\s+(\S+)/)?.[1] ?? "operation"} on ${branch} is blocked. Create a feature branch first.`);
   }
   return allow();
 }
@@ -767,6 +819,170 @@ function warnBackgroundProcess(ctx) {
   }
   return allow();
 }
+function requireCommitBeforeStop(ctx) {
+  const cwd = ctx.session?.cwd;
+  if (!cwd)
+    return allow("No working directory available, skipping commit check.");
+  try {
+    const status = execSync("git status --porcelain", {
+      cwd,
+      encoding: "utf8",
+      timeout: 5000
+    }).trim();
+    if (status.length > 0) {
+      return deny("You have uncommitted changes in the working directory. Commit all changes before stopping.");
+    }
+    return allow("All changes are committed.");
+  } catch {
+    return allow("Not a git repository, skipping commit check.");
+  }
+}
+function requirePushBeforeStop(ctx) {
+  const cwd = ctx.session?.cwd;
+  if (!cwd)
+    return allow("No working directory available, skipping push check.");
+  try {
+    const remotes = execSync("git remote", {
+      cwd,
+      encoding: "utf8",
+      timeout: 3000
+    }).trim();
+    if (!remotes)
+      return allow("No git remote configured, skipping push check.");
+    const remote = ctx.params?.remote ?? "origin";
+    const branch = getCurrentBranch(cwd);
+    if (!branch || branch === "HEAD")
+      return allow("Detached HEAD, skipping push check.");
+    const baseBranch = ctx.params?.baseBranch ?? "main";
+    if (branch === baseBranch) {
+      return allow(`On base branch "${baseBranch}", skipping push check.`);
+    }
+    try {
+      const ahead = execFileSync("git", ["log", `${remote}/${baseBranch}..HEAD`, "--oneline"], { cwd, encoding: "utf8", timeout: 5000 }).trim();
+      if (!ahead) {
+        return allow(`No commits ahead of ${remote}/${baseBranch}, skipping push check.`);
+      }
+      const diff = execFileSync("git", ["diff", "--stat", `${remote}/${baseBranch}`, "HEAD"], { cwd, encoding: "utf8", timeout: 5000 }).trim();
+      if (!diff) {
+        return allow(`No file changes compared to ${remote}/${baseBranch}, skipping push check.`);
+      }
+    } catch {}
+    let hasTracking = false;
+    try {
+      execFileSync("git", ["rev-parse", "--verify", `${remote}/${branch}`], {
+        cwd,
+        encoding: "utf8",
+        timeout: 3000
+      });
+      hasTracking = true;
+    } catch {}
+    if (!hasTracking) {
+      return deny(`Branch "${branch}" has not been pushed to remote "${remote}". ` + `Push your branch with: git push -u ${remote} ${branch}`);
+    }
+    const unpushed = execFileSync("git", ["log", `${remote}/${branch}..HEAD`, "--oneline"], {
+      cwd,
+      encoding: "utf8",
+      timeout: 5000
+    }).trim();
+    if (unpushed.length > 0) {
+      const commitCount = unpushed.split(`
+`).length;
+      return deny(`You have ${commitCount} unpushed commit${commitCount > 1 ? "s" : ""} on branch "${branch}". ` + `Push your changes with: git push`);
+    }
+    return allow(`All commits pushed to "${remote}".`);
+  } catch {
+    return allow("Could not check push status, skipping.");
+  }
+}
+function requirePrBeforeStop(ctx) {
+  const cwd = ctx.session?.cwd;
+  if (!cwd)
+    return allow("No working directory available, skipping PR check.");
+  try {
+    try {
+      execSync("gh --version", { cwd, encoding: "utf8", timeout: 3000 });
+    } catch {
+      return allow("GitHub CLI (gh) not installed, skipping PR check.");
+    }
+    const branch = getCurrentBranch(cwd);
+    if (!branch || branch === "HEAD")
+      return allow("Detached HEAD, skipping PR check.");
+    const baseBranch = ctx.params?.baseBranch ?? "main";
+    if (branch === baseBranch) {
+      return allow(`On base branch "${baseBranch}", skipping PR check.`);
+    }
+    try {
+      const ahead = execFileSync("git", ["log", `origin/${baseBranch}..HEAD`, "--oneline"], { cwd, encoding: "utf8", timeout: 5000 }).trim();
+      if (!ahead) {
+        return allow(`No commits ahead of origin/${baseBranch}, skipping PR check.`);
+      }
+      const diff = execFileSync("git", ["diff", "--stat", `origin/${baseBranch}`, "HEAD"], { cwd, encoding: "utf8", timeout: 5000 }).trim();
+      if (!diff) {
+        return allow(`No file changes compared to origin/${baseBranch}, skipping PR check.`);
+      }
+    } catch {}
+    let prJson;
+    try {
+      prJson = execSync("gh pr view --json number,url,state", {
+        cwd,
+        encoding: "utf8",
+        timeout: 15000
+      }).trim();
+    } catch {
+      return deny(`No pull request found for branch "${branch}". ` + `Create one with: gh pr create`);
+    }
+    const pr = JSON.parse(prJson);
+    if (pr.state === "OPEN") {
+      return allow(`PR #${pr.number} exists: ${pr.url}`);
+    }
+    return deny(`Pull request for branch "${branch}" is ${pr.state.toLowerCase()}. Create a new PR with: gh pr create`);
+  } catch {
+    return allow("Could not check PR status, skipping.");
+  }
+}
+function requireCiGreenBeforeStop(ctx) {
+  const cwd = ctx.session?.cwd;
+  if (!cwd)
+    return allow("No working directory available, skipping CI check.");
+  try {
+    try {
+      execSync("gh --version", { cwd, encoding: "utf8", timeout: 3000 });
+    } catch {
+      return allow("GitHub CLI (gh) not installed, skipping CI check.");
+    }
+    const branch = getCurrentBranch(cwd);
+    if (!branch || branch === "HEAD")
+      return allow("Detached HEAD, skipping CI check.");
+    let workflowRuns = [];
+    try {
+      const runsJson = execFileSync("gh", ["run", "list", "--branch", branch, "--limit", "5", "--json", "status,conclusion,name"], { cwd, encoding: "utf8", timeout: 15000 }).trim();
+      if (runsJson && runsJson !== "[]") {
+        workflowRuns = JSON.parse(runsJson);
+      }
+    } catch {}
+    let thirdPartyChecks = [];
+    const sha = getHeadSha(cwd);
+    if (sha) {
+      thirdPartyChecks = getThirdPartyCheckRuns(cwd, sha);
+    }
+    const allChecks = [...workflowRuns, ...thirdPartyChecks];
+    if (allChecks.length === 0)
+      return allow(`No CI runs found for branch "${branch}".`);
+    const failing = allChecks.filter((r) => r.status === "completed" && r.conclusion !== "success" && r.conclusion !== "skipped");
+    if (failing.length > 0) {
+      const names = failing.map((r) => `"${r.name}"`).join(", ");
+      return deny(`CI checks are failing on branch "${branch}": ${names}. Fix the failing checks before stopping.`);
+    }
+    const pending = allChecks.filter((r) => r.status === "in_progress" || r.status === "queued" || r.status === "waiting");
+    if (pending.length > 0) {
+      const names = pending.map((r) => `"${r.name}"`).join(", ");
+      return deny(`CI checks are still running on branch "${branch}": ${names}. Wait for all checks to complete and verify they pass.`);
+    }
+    return allow(`All CI checks passed on branch "${branch}".`);
+  } catch {
+    return allow("Could not check CI status, skipping.");
+  }
+}
 function registerBuiltinPolicies(enabledNames) {
   const enabledSet = new Set(enabledNames);
   for (const policy of BUILTIN_POLICIES) {
@@ -802,7 +1018,7 @@ var init_builtin_policies = __esm(() => {
   SCHEMA_ALTER_RE = /\bALTER\s+TABLE\b[\s\S]*\b(?:DROP\s+COLUMN|ADD\s+COLUMN|RENAME\s+(?:COLUMN|TO)|MODIFY\s+COLUMN)\b/i;
   PUBLISH_CMD_RE = /(?:npm\s+publish|bun\s+publish|pnpm\s+publish|yarn\s+npm\s+publish|twine\s+upload|poetry\s+publish|cargo\s+publish|gem\s+push)\b/;
   ENV_PRINTENV_RE = /(?:^|\s|;|&&|\|\|)(?:env|printenv)(?:\s|$|;|&&|\|)/;
-  ECHO_ENV_RE = /echo\s+.*\$[A-Za-z_]/;
+  ECHO_ENV_RE = /echo\s+.*\$\{?[A-Za-z_]/;
   EXPORT_RE = /(?:^|\s|;|&&|\|\|)export\s+\w+/;
   PS_ENV_VAR_RE = /\$env:[A-Za-z_]/i;
   PS_CHILDITEM_ENV_RE = /(?:Get-ChildItem|dir|gci|ls)\s+Env:/i;
@@ -813,7 +1029,7 @@ var init_builtin_policies = __esm(() => {
   SUDO_RE = /(?:^|;|&&|\|\|)\s*sudo\s/;
   PS_ELEVATION_RE = /Start-Process\s+.*-Verb\s+RunAs/i;
   RUNAS_RE = /(?:^|;|&&|\|\|)\s*runas\s/i;
-  CURL_PIPE_SH_RE = /(?:curl|wget)\s.*\|\s*(?:sh|bash|zsh)/;
+  CURL_PIPE_SH_RE = /(?:curl|wget)\s.*\|\s*(?:sh|bash|zsh|dash|ksh|csh|tcsh|fish|ash)\b/;
   PS_WEB_PIPE_RE = /(?:Invoke-WebRequest|iwr|Invoke-RestMethod|irm)\s+.*\|\s*(?:Invoke-Expression|iex)/i;
   FORCE_PUSH_RE = /(?:--force|-f\b)/;
   SECRET_FILE_RE = /\.(?:pem|key)$/;
@@ -1102,11 +1318,75 @@ var init_builtin_policies = __esm(() => {
       match: { events: ["PreToolUse"] },
       defaultEnabled: false,
       category: "AI Behavior"
+    },
+    {
+      name: "require-commit-before-stop",
+      description: "Require all changes to be committed before Claude stops",
+      fn: requireCommitBeforeStop,
+      match: { events: ["Stop"] },
+      defaultEnabled: false,
+      category: "Workflow",
+      beta: true
+    },
+    {
+      name: "require-push-before-stop",
+      description: "Require all commits to be pushed to remote before Claude stops",
+      fn: requirePushBeforeStop,
+      match: { events: ["Stop"] },
+      defaultEnabled: false,
+      category: "Workflow",
+      beta: true,
+      params: {
+        remote: {
+          type: "string",
+          description: "Remote name to push to (default: origin)",
+          default: "origin"
+        },
+        baseBranch: {
+          type: "string",
+          description: "Base branch to compare against (default: main)",
+          default: "main"
+        }
+      }
+    },
+    {
+      name: "require-pr-before-stop",
+      description: "Require a pull request to exist for the current branch before Claude stops",
+      fn: requirePrBeforeStop,
+      match: { events: ["Stop"] },
+      defaultEnabled: false,
+      category: "Workflow",
+      beta: true,
+      params: {
+        baseBranch: {
+          type: "string",
+          description: "Base branch to compare against (default: main)",
+          default: "main"
+        }
+      }
+    },
+    {
+      name: "require-ci-green-before-stop",
+      description: "Require CI checks to pass on the current branch before Claude stops",
+      fn: requireCiGreenBeforeStop,
+      match: { events: ["Stop"] },
+      defaultEnabled: false,
+      category: "Workflow",
+      beta: true
     }
   ];
 });
 
 // src/hooks/policy-evaluator.ts
+function appendHint(baseReason, hint) {
+  const base = baseReason.trim();
+  const normalizedHint = typeof hint === "string" ? hint.trim() : "";
+  if (!normalizedHint)
+    return base;
+  if (!base)
+    return normalizedHint;
+  return `${base}. ${normalizedHint}`;
+}
 async function evaluatePolicies(eventType, payload, session, config) {
   const toolName = payload.tool_name;
   const toolInput = payload.tool_input;
@@ -1122,8 +1402,8 @@ async function evaluatePolicies(eventType, payload, session, config) {
     toolInput,
     session
   };
-  let instructPolicyName = null;
-  let instructReason = null;
+  const instructEntries = [];
+  const allowEntries = [];
   for (const policy of policies) {
     const schema = POLICY_PARAMS_MAP.get(policy.name);
     let ctx;
@@ -1145,7 +1425,7 @@ async function evaluatePolicies(eventType, payload, session, config) {
       continue;
     }
     if (result.decision === "deny") {
-      const reason = result.reason ?? `Blocked by policy: ${policy.name}`;
+      const reason = appendHint(result.reason ?? `Blocked by policy: ${policy.name}`, config?.policyParams?.[policy.name]?.hint);
       hookLogInfo(`deny by "${policy.name}": ${reason}`);
       const displayTool = ctx.toolName ?? "unknown tool";
       if (eventType === "PreToolUse") {
@@ -1184,44 +1464,63 @@ async function evaluatePolicies(eventType, payload, session, config) {
       return {
         exitCode: 2,
         stdout: "",
-        stderr: "",
+        stderr: reason,
         policyName: policy.name,
         reason,
         decision: "deny"
       };
     }
-    if (result.decision === "instruct" && !instructPolicyName) {
-      instructPolicyName = policy.name;
-      instructReason = result.reason ?? `Instruction from policy: ${policy.name}`;
-      hookLogInfo(`instruct by "${policy.name}": ${instructReason}`);
+    if (result.decision === "instruct") {
+      const reason = appendHint(result.reason ?? `Instruction from policy: ${policy.name}`, config?.policyParams?.[policy.name]?.hint);
+      instructEntries.push({ policyName: policy.name, reason });
+      hookLogInfo(`instruct by "${policy.name}": ${reason}`);
+    }
+    if (result.decision === "allow" && result.reason) {
+      allowEntries.push({ policyName: policy.name, reason: result.reason });
     }
   }
-  if (instructPolicyName && instructReason) {
+  if (instructEntries.length > 0) {
+    const combined = instructEntries.map((e) => e.reason).join(`
+`);
+    const policyNames = instructEntries.map((e) => e.policyName);
     if (eventType === "Stop") {
       return {
         exitCode: 2,
         stdout: "",
-        stderr: instructReason,
-        policyName: instructPolicyName,
-        reason: instructReason,
+        stderr: combined,
+        policyName: policyNames[0],
+        policyNames,
+        reason: combined,
         decision: "instruct"
       };
     }
     const response = {
       hookSpecificOutput: {
         hookEventName: eventType,
-        additionalContext: `Instruction from failproofai: ${instructReason}`
+        additionalContext: `Instruction from failproofai: ${combined}`
       }
     };
     return {
       exitCode: 0,
       stdout: JSON.stringify(response),
       stderr: "",
-      policyName: instructPolicyName,
-      reason: instructReason,
+      policyName: policyNames[0],
+      policyNames,
+      reason: combined,
       decision: "instruct"
     };
   }
+  if (allowEntries.length > 0) {
+    const combined = allowEntries.map((e) => e.reason).join(`
+`);
+    const policyNames = allowEntries.map((e) => e.policyName);
+    const supportsHookSpecificOutput = eventType === "PreToolUse" || eventType === "PostToolUse" || eventType === "UserPromptSubmit";
+    const response = supportsHookSpecificOutput ? { hookSpecificOutput: { hookEventName: eventType, additionalContext: `Note from failproofai: ${combined}` } } : { reason: combined };
+    const stderrMsg = allowEntries.map((e) => `[failproofai] ${e.policyName}: ${e.reason}`).join(`
+`);
+    return { exitCode: 0, stdout: JSON.stringify(response), stderr: stderrMsg + `
+`, policyName: policyNames[0], policyNames, reason: combined, decision: "allow" };
+  }
   return { exitCode: 0, stdout: "", stderr: "", policyName: null, reason: null, decision: "allow" };
 }
 var POLICY_PARAMS_MAP;
@@ -1291,10 +1590,9 @@ async function createEsmShim(distIndex, distUrl) {
   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;`,
@@ -1374,20 +1672,21 @@ var init_loader_utils = __esm(() => {
 });
 
 // src/hooks/custom-hooks-loader.ts
-import { resolve as resolve4, isAbsolute } from "node:path";
-import { existsSync as existsSync3 } from "node:fs";
+import { resolve as resolve4, isAbsolute, basename } from "node:path";
+import { existsSync as existsSync3, readdirSync } from "node:fs";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
-async function loadCustomHooks(customPoliciesPath, opts) {
-  if (!customPoliciesPath)
+import { homedir as homedir4 } from "node:os";
+function discoverPolicyFiles(dir) {
+  if (!existsSync3(dir))
     return [];
-  const absPath = isAbsolute(customPoliciesPath) ? customPoliciesPath : resolve4(process.cwd(), customPoliciesPath);
-  if (!existsSync3(absPath)) {
-    if (opts?.strict)
-      throw new Error(`Custom hooks file not found: ${absPath}`);
-    hookLogWarn(`customPoliciesPath not found: ${absPath}`);
+  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) => resolve4(dir, e.name));
+  } catch {
     return [];
   }
-  clearCustomHooks();
+}
+async function loadSingleFile(absPath, opts) {
   const g = globalThis;
   g[LOADING_KEY] = true;
   let tmpFiles = [];
@@ -1403,18 +1702,93 @@ async function loadCustomHooks(customPoliciesPath, opts) {
     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);
   }
+}
+async function loadCustomHooks(customPoliciesPath, opts) {
+  if (!customPoliciesPath)
+    return [];
+  const absPath = isAbsolute(customPoliciesPath) ? customPoliciesPath : resolve4(opts?.sessionCwd ?? process.cwd(), customPoliciesPath);
+  if (!existsSync3(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();
 }
-var LOADING_KEY = "__FAILPROOFAI_LOADING_HOOKS__";
+async function loadAllCustomHooks(customPoliciesPath, opts) {
+  clearCustomHooks();
+  const conventionSources = [];
+  if (customPoliciesPath) {
+    const absPath = isAbsolute(customPoliciesPath) ? customPoliciesPath : resolve4(opts?.sessionCwd ?? process.cwd(), customPoliciesPath);
+    if (existsSync3(absPath)) {
+      await loadSingleFile(absPath);
+    } else {
+      hookLogWarn(`customPoliciesPath not found: ${absPath}`);
+    }
+  }
+  const hooksBeforeConvention = getCustomHooks().length;
+  const projectDir = resolve4(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)
+      });
+    }
+  }
+  const userDir = resolve4(homedir4(), ".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)`);
+  }
+  const hookNameToScope = new Map;
+  for (const source of conventionSources) {
+    for (const name of source.hookNames) {
+      hookNameToScope.set(name, source.scope);
+    }
+  }
+  const conventionHookRefs = new Set;
+  for (const hook of allHooks.slice(hooksBeforeConvention)) {
+    conventionHookRefs.add(hook);
+  }
+  for (const hook of allHooks) {
+    if (conventionHookRefs.has(hook)) {
+      hook.__conventionScope = hookNameToScope.get(hook.name) ?? "project";
+    }
+  }
+  return { hooks: allHooks, conventionSources };
+}
+var LOADING_KEY = "__FAILPROOFAI_LOADING_HOOKS__", CONVENTION_FILE_RE;
 var init_custom_hooks_loader = __esm(() => {
   init_hook_logger();
   init_custom_hooks_registry();
   init_loader_utils();
+  CONVENTION_FILE_RE = /policies\.(js|mjs|ts)$/;
 });
 
 // src/hooks/hook-activity-store.ts
@@ -1423,14 +1797,14 @@ import {
   writeFileSync as writeFileSync2,
   appendFileSync as appendFileSync2,
   renameSync as renameSync2,
-  readdirSync,
+  readdirSync as readdirSync2,
   mkdirSync as mkdirSync3,
   existsSync as existsSync4,
   statSync as statSync2,
   unlinkSync
 } from "node:fs";
 import { join as join3 } from "node:path";
-import { homedir as homedir4 } from "node:os";
+import { homedir as homedir5 } from "node:os";
 function ensureDir() {
   if (!existsSync4(storeDir)) {
     mkdirSync3(storeDir, { recursive: true });
@@ -1516,7 +1890,11 @@ function updateStats(entry) {
   s.totalEvents += 1;
   if (entry.decision === "deny")
     s.denyCount += 1;
-  if (entry.policyName) {
+  if (entry.policyNames && entry.policyNames.length > 0) {
+    for (const name of entry.policyNames) {
+      s.policyMap[name] = (s.policyMap[name] ?? 0) + 1;
+    }
+  } else if (entry.policyName) {
     s.policyMap[entry.policyName] = (s.policyMap[entry.policyName] ?? 0) + 1;
   }
   const tmpPath = join3(storeDir, `stats.json.${process.pid}.tmp`);
@@ -1531,12 +1909,12 @@ function updateStats(entry) {
 }
 var PAGE_SIZE = 25, DEFAULT_STORE_DIR, CURRENT_FILE = "current.jsonl", COUNT_FILE = "current.count", STATS_FILE = "stats.json", LOCK_FILE = "current.lock", LOCK_STALE_MS = 2000, storeDir, rotateSeq = 0;
 var init_hook_activity_store = __esm(() => {
-  DEFAULT_STORE_DIR = join3(homedir4(), ".failproofai", "cache", "hook-activity");
+  DEFAULT_STORE_DIR = join3(homedir5(), ".failproofai", "cache", "hook-activity");
   storeDir = DEFAULT_STORE_DIR;
 });
 
 // package.json
-var version2 = "0.0.2";
+var version2 = "0.0.3";
 var init_package = () => {};
 
 // src/posthog-key.ts
@@ -1698,9 +2076,14 @@ async function handleHookEvent(eventType) {
   const config = readMergedHooksConfig(session.cwd);
   clearPolicies();
   registerBuiltinPolicies(config.enabledPolicies);
-  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.__conventionScope;
+    const isConvention = !!conventionScope;
+    const prefix = isConvention ? `.failproofai-${conventionScope}` : "custom";
     const fn = async (ctx) => {
       try {
         const result2 = await Promise.race([
@@ -1711,16 +2094,18 @@ async function handleHookEvent(eventType) {
       } 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}`);
         trackHookEvent(getInstanceId(), "custom_hook_error", {
           hook_name: hookName,
           error_type: isTimeout ? "timeout" : "exception",
-          event_type: eventType
+          event_type: eventType,
+          is_convention_policy: isConvention,
+          convention_scope: conventionScope ?? null
         });
         return { decision: "allow" };
       }
     };
-    registerPolicy(`custom/${hookName}`, hook.description ?? "", fn, hook.match ?? {}, -1);
+    registerPolicy(`${prefix}/${hookName}`, hook.description ?? "", fn, hook.match ?? {}, -1);
   }
   if (customHooksList.length > 0) {
     trackHookEvent(getInstanceId(), "custom_hooks_loaded", {
@@ -1729,7 +2114,16 @@ async function handleHookEvent(eventType) {
       event_types_covered: [...new Set(customHooksList.flatMap((h) => h.match?.events ?? []))]
     });
   }
-  hookLogInfo(`event=${eventType} policies=${config.enabledPolicies.length} custom=${customHooksList.length}`);
+  if (loadResult.conventionSources.length > 0) {
+    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}`);
   const result = await evaluatePolicies(eventType, parsed, session, config);
   const durationMs = Math.round(performance.now() - startTime);
   hookLogInfo(`result=${result.decision} policy=${result.policyName ?? "none"} duration=${durationMs}ms`);
@@ -1745,6 +2139,7 @@ async function handleHookEvent(eventType) {
       eventType,
       toolName: parsed.tool_name ?? null,
       policyName: result.policyName,
+      policyNames: result.policyNames,
       decision: result.decision,
       reason: result.reason,
       durationMs,
@@ -1760,7 +2155,9 @@ async function handleHookEvent(eventType) {
   if (result.decision === "deny" || result.decision === "instruct") {
     try {
       const isCustomHook = result.policyName?.startsWith("custom/") ?? false;
-      const hasCustomParams = !isCustomHook && !!(result.policyName && config.policyParams?.[result.policyName]);
+      const isConventionPolicy = result.policyName?.startsWith(".failproofai-") ?? false;
+      const conventionScope = isConventionPolicy ? result.policyName.match(/^\.failproofai-(project|user)\//)?.[1] ?? null : null;
+      const hasCustomParams = !isCustomHook && !isConventionPolicy && !!(result.policyName && config.policyParams?.[result.policyName]);
       const paramKeysOverridden = hasCustomParams ? Object.keys(config.policyParams[result.policyName]) : [];
       const distinctId = getInstanceId();
       await trackHookEvent(distinctId, "hook_policy_triggered", {
@@ -1769,6 +2166,8 @@ async function handleHookEvent(eventType) {
         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
       });
@@ -2101,13 +2500,13 @@ __export(exports_manager, {
 });
 import { execSync as execSync3 } from "node:child_process";
 import { readFileSync as readFileSync3, writeFileSync as writeFileSync3, existsSync as existsSync5, mkdirSync as mkdirSync4 } from "node:fs";
-import { resolve as resolve5, dirname as dirname3 } from "node:path";
-import { homedir as homedir5, platform, arch, release, hostname } from "node:os";
+import { resolve as resolve5, dirname as dirname3, basename as basename2 } from "node:path";
+import { homedir as homedir6, platform, arch, release, hostname } from "node:os";
 function getSettingsPath(scope, cwd) {
   const base = cwd ? resolve5(cwd) : process.cwd();
   switch (scope) {
     case "user":
-      return resolve5(homedir5(), ".claude", "settings.json");
+      return resolve5(homedir6(), ".claude", "settings.json");
     case "project":
       return resolve5(base, ".claude", "settings.json");
     case "local":
@@ -2234,7 +2633,7 @@ async function installHooks(policyNames, scope = "user", cwd, includeBeta = fals
     }
   }
   const binaryPath = resolveFailproofaiBinary();
-  const previousConfig = readHooksConfig();
+  const previousConfig = readScopedHooksConfig(scope, cwd);
   const previousEnabled = new Set(previousConfig.enabledPolicies);
   let selectedPolicies;
   if (policyNames !== undefined) {
@@ -2268,7 +2667,7 @@ async function installHooks(policyNames, scope = "user", cwd, includeBeta = fals
     console.log(`
 Validated ${validatedHooks.length} custom hook(s): ${validatedHooks.map((h) => h.name).join(", ")}`);
   }
-  writeHooksConfig(configToWrite);
+  writeScopedHooksConfig(configToWrite, scope, cwd);
   console.log(`
 Enabled ${selectedPolicies.length} policy(ies): ${selectedPolicies.join(", ")}`);
   if (removeCustomHooks) {
@@ -2282,7 +2681,7 @@ Enabled ${selectedPolicies.length} policy(ies): ${selectedPolicies.join(", ")}`)
     settings.hooks = {};
   }
   for (const eventType of HOOK_EVENT_TYPES) {
-    const command = `"${binaryPath}" --hook ${eventType}`;
+    const command = scope === "project" ? `npx -y failproofai --hook ${eventType}` : `"${binaryPath}" --hook ${eventType}`;
     const hookEntry = {
       type: "command",
       command,
@@ -2327,12 +2726,19 @@ Enabled ${selectedPolicies.length} policy(ies): ${selectedPolicies.join(", ")}`)
       hostname_hash: hashToId(hostname()),
       has_custom_hooks_path: !!configToWrite.customPoliciesPath,
       has_policy_params: !!(configToWrite.policyParams && Object.keys(configToWrite.policyParams).length > 0),
-      param_policy_names: configToWrite.policyParams ? Object.keys(configToWrite.policyParams) : []
+      param_policy_names: configToWrite.policyParams ? Object.keys(configToWrite.policyParams) : [],
+      command_format: scope === "project" ? "npx" : "absolute"
     });
   } catch {}
   console.log(`Failproof AI hooks installed for all ${HOOK_EVENT_TYPES.length} event types (scope: ${scope}).`);
   console.log(`Settings: ${settingsPath}`);
-  console.log(`Binary:   ${binaryPath}`);
+  if (scope === "project") {
+    console.log(`Command:  npx -y failproofai`);
+    console.log(`
+This file can be committed to git — no machine-specific paths.`);
+  } else {
+    console.log(`Binary:   ${binaryPath}`);
+  }
   const otherScopes = deduplicateScopes(HOOK_SCOPES, cwd).filter((s) => s !== scope);
   const duplicates = otherScopes.filter((s) => hooksInstalledInSettings(s, cwd));
   if (duplicates.length > 0) {
@@ -2345,15 +2751,16 @@ Enabled ${selectedPolicies.length} policy(ies): ${selectedPolicies.join(", ")}`)
   }
 }
 async function removeHooks(policyNames, scope = "user", cwd, opts) {
+  const configScope = scope === "all" ? "user" : scope;
   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.");
   }
   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));
@@ -2367,7 +2774,7 @@ async function removeHooks(policyNames, scope = "user", cwd, opts) {
       enabledPolicies: remaining,
       ...filteredParams && Object.keys(filteredParams).length > 0 ? { policyParams: filteredParams } : {}
     };
-    writeHooksConfig(updatedConfig);
+    writeScopedHooksConfig(updatedConfig, configScope, cwd);
     try {
       const distinctId = getInstanceId();
       const actuallyRemoved = policyNames.filter((p) => config.enabledPolicies.includes(p));
@@ -2388,7 +2795,7 @@ async function removeHooks(policyNames, scope = "user", cwd, opts) {
     console.log(`Remaining: ${remaining.length > 0 ? remaining.join(", ") : "(none)"}`);
     return;
   }
-  const configBeforeRemoval = readHooksConfig();
+  const configBeforeRemoval = readScopedHooksConfig(configScope, cwd);
   const scopesToRemove = scope === "all" ? [...HOOK_SCOPES] : [scope];
   let totalRemoved = 0;
   for (const s of scopesToRemove) {
@@ -2435,10 +2842,18 @@ async function removeHooks(policyNames, scope = "user", cwd, opts) {
       hostname_hash: hashToId(hostname())
     });
   } catch {}
-  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") {
+    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);
   }
 }
 async function listHooks(cwd) {
@@ -2575,6 +2990,35 @@ Failproof AI Hook Policies
     }
     console.log();
   }
+  const base = cwd ? resolve5(cwd) : process.cwd();
+  const conventionDirs = [
+    { label: "Project", dir: resolve5(base, ".failproofai", "policies") },
+    { label: "User", dir: resolve5(homedir6(), ".failproofai", "policies") }
+  ];
+  for (const { label, dir } of conventionDirs) {
+    const files = discoverPolicyFiles(dir);
+    if (files.length === 0)
+      continue;
+    console.log(`
+  ── Convention Policies — ${label} (${dir}) ──────────`);
+    for (const file of files) {
+      try {
+        const hooks = await loadCustomHooks(file);
+        if (hooks.length === 0) {
+          const filename = basename2(file);
+          console.log(`  \x1B[31m✗\x1B[0m       ${filename.padEnd(nameColWidth)}\x1B[31mfailed to load\x1B[0m`);
+        } else {
+          const filename = basename2(file);
+          const hookSummary = hooks.map((h) => h.name).join(", ");
+          console.log(`  \x1B[32m✓\x1B[0m       ${filename.padEnd(nameColWidth)}${hooks.length} hook(s): ${hookSummary}`);
+        }
+      } catch {
+        const filename = basename2(file);
+        console.log(`  \x1B[31m✗\x1B[0m       ${filename.padEnd(nameColWidth)}\x1B[31merror\x1B[0m`);
+      }
+    }
+    console.log();
+  }
 }
 var VALID_POLICY_NAMES;
 var init_manager = __esm(() => {
@@ -2590,10 +3034,10 @@ var init_manager = __esm(() => {
 });
 
 // lib/paths.ts
-import { homedir as homedir6 } from "os";
+import { homedir as homedir7 } from "os";
 import { join as join4 } from "path";
 function getDefaultClaudeProjectsPath() {
-  return join4(homedir6(), ".claude", "projects");
+  return join4(homedir7(), ".claude", "projects");
 }
 var init_paths = () => {};
 
@@ -2762,7 +3206,7 @@ import { realpathSync as realpathSync2 } from "fs";
 import { dirname as dirname5, resolve as resolve8 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 // package.json
-var version = "0.0.2";
+var version = "0.0.3";
 
 // bin/failproofai.mjs
 if (!process.env.FAILPROOFAI_PACKAGE_ROOT) {
@@ -2826,6 +3270,11 @@ COMMANDS
   --version, -v                  Print version and exit
   --help, -h                     Show this help message
 
+CONVENTION POLICIES
+  Drop *policies.{js,mjs,ts} files into .failproofai/policies/ for auto-loading.
+  Works at project level (.failproofai/policies/) and user level (~/.failproofai/policies/).
+  No --custom flag or config changes needed \u2014 just drop files and they're picked up.
+
 EXAMPLES
   failproofai policies
   failproofai policies --install