test: add Layer 1 security invariant tests + restore precedence docs

- Add tests proving built-in block rules (block-rm-rf-home, block-force-push)
  cannot be bypassed by a user-defined allow rule
- Restore Configuration Precedence section to README with 5-tier waterfall
  and note that built-in blocks always fire before user rules

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: nawi-25

README.md

@@ -136,6 +136,22 @@ node9 shield status             # see what's currently active
 
 ---
 
+## 🔗 Configuration Precedence
+
+Node9 merges configuration from multiple sources in priority order. Higher tiers win:
+
+| Tier | Source                    | Notes                                                     |
+| :--- | :------------------------ | :-------------------------------------------------------- |
+| 1    | **Environment variables** | `NODE9_MODE=strict` overrides everything                  |
+| 2    | **Cloud / Org policy**    | Set in the Node9 dashboard — cannot be overridden locally |
+| 3    | **Project config**        | `node9.config.json` in the working directory              |
+| 4    | **Global config**         | `~/.node9/config.json`                                    |
+| 5    | **Built-in defaults**     | Always active, no config needed                           |
+
+Smart rules from all layers are **concatenated** in evaluation order (first-match-wins): built-in defaults → global → project → shields → advisory defaults. This means built-in `block` rules always fire before any user-defined `allow` rules — a user config cannot bypass Layer 1 protection.
+
+---
+
 ## ⚙️ Custom Rules (Advanced)
 
 Most users never need this. If you need protection beyond Layer 1 and the available shields, add **Smart Rules** to `node9.config.json` in your project root or `~/.node9/config.json` globally.

src/__tests__/core.test.ts

@@ -827,6 +827,52 @@ describe('authorizeHeadless — smart rule hard block', () => {
   });
 });
 
+// ── Layer 1 security invariant ────────────────────────────────────────────────
+// Built-in block rules (Layer 1) are evaluated BEFORE user-defined rules.
+// A user allow rule must never be able to bypass a built-in block.
+
+describe('Layer 1 security invariant — built-in blocks cannot be bypassed', () => {
+  it('block-rm-rf-home fires before a user allow rule on the same command', async () => {
+    // User adds an allow rule that would match rm -rf ~ if evaluated first.
+    mockProjectConfig({
+      policy: {
+        smartRules: [
+          {
+            name: 'user-allow-rm',
+            tool: 'bash',
+            conditions: [{ field: 'command', op: 'matches', value: 'rm' }],
+            verdict: 'allow',
+            reason: 'user allow — should NOT fire before block-rm-rf-home',
+          },
+        ],
+      },
+    });
+    const result = await evaluatePolicy('bash', { command: 'rm -rf ~' });
+    // block-rm-rf-home (Layer 1) must win — not the user allow rule
+    expect(result.decision).toBe('block');
+    expect(result.blockedByLabel).toMatch(/block-rm-rf-home/);
+  });
+
+  it('block-force-push fires before a user allow rule on the same command', async () => {
+    mockProjectConfig({
+      policy: {
+        smartRules: [
+          {
+            name: 'user-allow-git',
+            tool: 'bash',
+            conditions: [{ field: 'command', op: 'matches', value: 'git' }],
+            verdict: 'allow',
+            reason: 'user allow — should NOT fire before block-force-push',
+          },
+        ],
+      },
+    });
+    const result = await evaluatePolicy('bash', { command: 'git push --force origin main' });
+    expect(result.decision).toBe('block');
+    expect(result.blockedByLabel).toMatch(/block-force-push/);
+  });
+});
+
 // ── shouldSnapshot ────────────────────────────────────────────────────────────
 describe('shouldSnapshot', () => {
   const baseConfig = () => JSON.parse(JSON.stringify(DEFAULT_CONFIG)) as typeof DEFAULT_CONFIG;