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

package/.next/standalone/docs/configuration.mdx

@@ -116,6 +116,35 @@ If a policy has parameters but you don't specify them, the policy's built-in def
 
 Unknown keys inside a policy's params block are silently ignored at hook-fire time but flagged as warnings when you run `failproofai policies`.
 
+#### `hint` (cross-cutting)
+
+Type: `string` (optional)
+
+A message appended to the reason when a policy returns `deny` or `instruct`. Use it to give Claude actionable guidance without modifying the policy itself.
+
+Works with any policy type — built-in, custom (`custom/`), project convention (`.failproofai-project/`), or user convention (`.failproofai-user/`).
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Try creating a fresh branch instead."
+    },
+    "block-sudo": {
+      "allowPatterns": ["sudo apt-get"],
+      "hint": "Use apt-get directly without sudo."
+    },
+    "custom/my-policy": {
+      "hint": "Ask the user for approval first."
+    }
+  }
+}
+```
+
+When `block-force-push` denies, Claude sees: *"Force-pushing is blocked. Try creating a fresh branch instead."*
+
+Non-string values and empty strings are silently ignored. If `hint` is not set, behavior is unchanged (backward-compatible).
+
 ### `customPoliciesPath`
 
 Type: `string` (absolute path)
@@ -124,6 +153,23 @@ Path to a JavaScript file containing custom hook policies. This is set automatic
 
 The file is loaded fresh on every hook event - there is no caching. See [Custom Policies](/custom-policies) for authoring details.
 
+### Convention-based policies (v0.0.2-beta.7+)
+
+In addition to the explicit `customPoliciesPath`, failproofai automatically discovers and loads policy files from `.failproofai/policies/` directories:
+
+| Level | Directory | Scope |
+|-------|-----------|-------|
+| Project | `.failproofai/policies/` | Shared with team via version control |
+| User | `~/.failproofai/policies/` | Personal, applies to all projects |
+
+**File matching:** Only files matching `*policies.{js,mjs,ts}` are loaded (e.g. `security-policies.mjs`, `workflow-policies.js`). Other files in the directory are ignored.
+
+**No config needed:** Convention policies require no entries in `policies-config.json`. Just drop files into the directory and they're picked up on the next hook event.
+
+**Union loading:** Both project and user convention directories are scanned. All matching files from both levels are loaded (unlike `customPoliciesPath` which uses first-scope-wins).
+
+See [Custom Policies](/custom-policies) for more details and examples.
+
 ### `llm`
 
 Type: `object` (optional)

package/.next/standalone/docs/custom-policies.mdx

@@ -37,7 +37,33 @@ failproofai policies --install --custom ./my-policies.js
 
 ---
 
-## Installing and updating
+## Two ways to load custom policies
+
+### Option 1: Convention-based (recommended, v0.0.2-beta.7+)
+
+Drop `*policies.{js,mjs,ts}` files into `.failproofai/policies/` and they're automatically loaded — no flags or config changes needed. This works like git hooks: drop a file, it just works.
+
+```
+# Project level — committed to git, shared with the team
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# User level — personal, applies to all projects
+~/.failproofai/policies/my-policies.mjs
+```
+
+**How it works:**
+- Both project and user directories are scanned (union — not first-scope-wins)
+- Files are loaded alphabetically within each directory. Prefix with `01-`, `02-` to control order
+- Only files matching `*policies.{js,mjs,ts}` are loaded; other files are ignored
+- Each file is loaded independently (fail-open per file)
+- Works alongside explicit `--custom` and built-in policies
+
+<Tip>
+Convention policies are the easiest way to share policies across a team. Commit `.failproofai/policies/` to git and every team member gets them automatically.
+</Tip>
+
+### Option 2: Explicit file path
 
 ```bash
 # Install with a custom policies file
@@ -52,6 +78,14 @@ failproofai policies --uninstall --custom
 
 The resolved absolute path is stored in `policies-config.json` as `customPoliciesPath`. The file is loaded fresh on every hook event - there is no caching between events.
 
+### Using both together
+
+Convention policies and the explicit `--custom` file can coexist. Load order:
+
+1. Explicit `customPoliciesPath` file (if configured)
+2. Project convention files (`{cwd}/.failproofai/policies/`, alphabetical)
+3. User convention files (`~/.failproofai/policies/`, alphabetical)
+
 ---
 
 ## API
@@ -85,7 +119,11 @@ customPolicies.add({
 
 `deny(message)` - the message appears to Claude prefixed with `"Blocked by failproofai:"`. A single `deny` short-circuits all further evaluation.
 
-`instruct(message)` - the message is appended to Claude's context for the current tool call. The first `instruct` wins — subsequent `instruct` returns from other policies are ignored.
+`instruct(message)` - the message is appended to Claude's context for the current tool call. All `instruct` messages are accumulated and delivered together.
+
+<Tip>
+You can append extra guidance to any `deny` or `instruct` message by adding a `hint` field in `policyParams` — no code change needed. This works for custom (`custom/`), project convention (`.failproofai-project/`), and user convention (`.failproofai-user/`) policies too. See [Configuration → hint](/configuration#hint-cross-cutting) for details.
+</Tip>
 
 ### Informational allow messages (beta)
 
@@ -155,10 +193,12 @@ customPolicies.add({
 Policies are evaluated in this order:
 
 1. Built-in policies (in definition order)
-2. Custom policies (in `.add()` order)
+2. Explicit custom policies from `customPoliciesPath` (in `.add()` order)
+3. Convention policies from project `.failproofai/policies/` (files alphabetical, `.add()` order within)
+4. Convention policies from user `~/.failproofai/policies/` (files alphabetical, `.add()` order within)
 
 <Note>
-The first `deny` short-circuits all subsequent policies. The first `instruct` wins — subsequent `instruct` returns are ignored.
+The first `deny` short-circuits all subsequent policies. All `instruct` messages are accumulated and delivered together.
 </Note>
 
 ---
@@ -212,11 +252,13 @@ Custom policies are **fail-open**: errors never block built-in policies or crash
 
 | Failure | Behavior |
 |---------|----------|
-| `customPoliciesPath` not set | No custom policies run; built-ins continue normally |
+| `customPoliciesPath` not set | No explicit custom policies run; convention policies and built-ins continue normally |
 | File not found | Warning logged to `~/.failproofai/hook.log`; built-ins continue |
-| Syntax/import error | Error logged to `~/.failproofai/hook.log`; all custom policies skipped |
+| Syntax/import error (explicit) | Error logged to `~/.failproofai/hook.log`; explicit custom policies skipped |
+| Syntax/import error (convention) | Error logged; that file skipped, other convention files still load |
 | `fn` throws at runtime | Error logged; that hook treated as `allow`; other hooks continue |
 | `fn` takes longer than 10s | Timeout logged; treated as `allow` |
+| Convention directory missing | No convention policies run; no error |
 
 <Tip>
 To debug custom policy errors, watch the log file:
@@ -291,9 +333,25 @@ The `examples/` directory contains ready-to-run policy files:
 |------|----------|
 | `examples/policies-basic.js` | Five starter policies covering common agent failure modes |
 | `examples/policies-advanced/index.js` | Advanced patterns: transitive imports, async calls, output scrubbing, and session-end hooks |
+| `examples/convention-policies/security-policies.mjs` | Convention-based security policies (block .env writes, prevent git history rewriting) |
+| `examples/convention-policies/workflow-policies.mjs` | Convention-based workflow policies (test reminders, audit file writes) |
 
-Install the basic examples:
+### Using explicit file examples
 
 ```bash
 failproofai policies --install --custom ./examples/policies-basic.js
 ```
+
+### Using convention-based examples
+
+```bash
+# Copy to project level
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# Or copy to user level
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+No install command needed — the files are picked up automatically on the next hook event.

package/.next/standalone/docs/docs.json

@@ -86,9 +86,9 @@
           "icon": "npm"
         },
         {
-          "anchor": "Discord",
-          "href": "https://discord.com/invite/zT92CAgvkj",
-          "icon": "discord"
+          "anchor": "Slack",
+          "href": "https://join.slack.com/t/failproofai/shared_invite/zt-3v63b7k5e-O3NBHmj8X6n9gZSGDx6ggQ",
+          "icon": "slack"
         }
       ]
     }

package/.next/standalone/examples/convention-policies/security-policies.mjs

@@ -0,0 +1,40 @@
+/**
+ * security-policies.mjs — Convention-based security policies
+ *
+ * Drop this file into .failproofai/policies/ at the project or user level
+ * and it will be automatically loaded — no --custom flag needed.
+ *
+ * Project level:  .failproofai/policies/security-policies.mjs
+ * User level:     ~/.failproofai/policies/security-policies.mjs
+ */
+import { customPolicies, allow, deny } from "failproofai";
+
+// Block writes to .env files
+customPolicies.add({
+  name: "block-env-writes",
+  description: "Prevent Claude from writing to .env files",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = String(ctx.toolInput?.file_path ?? "");
+    if (/\.env($|\.)/.test(path)) {
+      return deny(`Writing to .env files is blocked: ${path}`);
+    }
+    return allow();
+  },
+});
+
+// Block commands that delete git history
+customPolicies.add({
+  name: "block-git-history-rewrite",
+  description: "Prevent destructive git history operations",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+(rebase\s+-i|filter-branch|reflog\s+expire)/.test(cmd)) {
+      return deny("Rewriting git history is not allowed — use a revert commit instead");
+    }
+    return allow();
+  },
+});

package/.next/standalone/examples/convention-policies/workflow-policies.mjs

@@ -0,0 +1,41 @@
+/**
+ * workflow-policies.mjs — Convention-based workflow policies
+ *
+ * Drop this file into .failproofai/policies/ at the project or user level
+ * and it will be automatically loaded — no --custom flag needed.
+ *
+ * Project level:  .failproofai/policies/workflow-policies.mjs
+ * User level:     ~/.failproofai/policies/workflow-policies.mjs
+ */
+import { customPolicies, allow, instruct } from "failproofai";
+
+// Remind to run tests before committing
+customPolicies.add({
+  name: "test-before-commit",
+  description: "Remind Claude to run tests before git commit",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+commit/.test(cmd)) {
+      return instruct(
+        "Before committing, make sure all tests pass. " +
+        "Run the test suite first if you haven't already."
+      );
+    }
+    return allow();
+  },
+});
+
+// Log all file writes for audit trail
+customPolicies.add({
+  name: "audit-file-writes",
+  description: "Log all file write operations",
+  match: { events: ["PostToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "unknown";
+    console.error(`[audit] File written: ${path}`);
+    return allow();
+  },
+});

package/.next/standalone/node_modules/@next/env/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next/env",
-  "version": "16.2.2",
+  "version": "16.2.3",
   "keywords": [
     "react",
     "next",

package/.next/standalone/node_modules/next/dist/build/swc/index.js

@@ -134,7 +134,7 @@ var HmrTarget = /*#__PURE__*/ function(HmrTarget) {
     HmrTarget["Server"] = "server";
     return HmrTarget;
 }({});
-const nextVersion = "16.2.2";
+const nextVersion = "16.2.3";
 const ArchName = (0, _os.arch)();
 const PlatformName = (0, _os.platform)();
 function infoLog(...args) {