fix(wizard): stop the agent guard from blocking .env.example

Completes the review fix on #594. The doctrine now says `.env.example` is
exempt from the secrets read-ban; the wizard's runtime guard still blocked it.

`SENSITIVE_FILE_PATTERNS` matched `/\.env($|\.)/`, which tests true against
`.env.example`. Because `wizardCanUseTool` applies that guard to `Edit` and
`Write` as well as `Read`, the agent could not create or edit the one file the
doctrine explicitly instructs it to write. Committed env templates carry
placeholder key names, not values.

Narrow the rule with an anchored negative lookahead so `.env.example`,
`.env.sample` and `.env.template` are reachable, while `.env`, `.env.local`,
`.env.production` and near-miss names that do carry values
(`.env.example.local`, `.env.example.bak`) stay blocked. `auth.json`,
`secretkey.json` and credential files are untouched.

Bash remains deliberately stricter: no env file, template or not, is reachable
from a shell. `cat` isn't in the bash allowlist anyway, and Read/Write is the
sanctioned path -- so there's no reason to widen the riskiest surface. Noted
inline.

Adds five cases covering the exemption, the near-miss names, and the Bash
asymmetry. `pnpm --filter @cipherstash/wizard test` passes (150).

Author: coderdan

.changeset/wizard-allow-env-templates.md

@@ -0,0 +1,18 @@
+---
+"@cipherstash/wizard": patch
+---
+
+Stop the agent guard from blocking `.env.example`.
+
+`SENSITIVE_FILE_PATTERNS` matched `/\.env($|\.)/`, which tests true against
+`.env.example`. Because the guard covers `Edit` and `Write` as well as `Read`,
+the wizard's agent was blocked from creating or editing the very file the
+CipherStash doctrine tells it to write ("New env keys go in `.env.example` with
+placeholders"). Committed env templates carry placeholder key names, not values.
+
+`.env.example`, `.env.sample` and `.env.template` are now readable and writable.
+Everything else is unchanged: `.env`, `.env.local`, `.env.production`, and
+value-bearing files that merely start with a template name
+(`.env.example.local`, `.env.example.bak`) stay blocked, as do `auth.json`,
+`secretkey.json` and credential files. Bash access to any env file — including
+the templates — remains blocked; `Read`/`Write` is the sanctioned path.

packages/wizard/src/__tests__/interface.test.ts

@@ -72,6 +72,42 @@ describe('wizardCanUseTool', () => {
     })
   })
 
+  describe('.env templates are not sensitive', () => {
+    // The doctrine tells the agent to add placeholder keys to `.env.example`.
+    // The guard covers Edit and Write as well as Read, so a blanket `.env.`
+    // rule made the file the agent is told to write unreachable.
+    it.each(['.env.example', '.env.sample', '.env.template'])(
+      'allows Read/Edit/Write/Glob on %s',
+      (name) => {
+        expect(wizardCanUseTool('Read', { file_path: `/project/${name}` })).toBe(
+          true,
+        )
+        expect(wizardCanUseTool('Edit', { file_path: `/project/${name}` })).toBe(
+          true,
+        )
+        expect(
+          wizardCanUseTool('Write', { file_path: `/project/${name}` }),
+        ).toBe(true)
+        expect(wizardCanUseTool('Glob', { pattern: name })).toBe(true)
+      },
+    )
+
+    it('still blocks value-bearing files that only start with a template name', () => {
+      expect(
+        wizardCanUseTool('Read', { file_path: '/project/.env.example.local' }),
+      ).toContain('blocked')
+      expect(
+        wizardCanUseTool('Write', { file_path: '/project/.env.example.bak' }),
+      ).toContain('blocked')
+    })
+
+    it('still blocks env templates from Bash — Read/Write is the sanctioned path', () => {
+      expect(
+        wizardCanUseTool('Bash', { command: 'cat .env.example' }),
+      ).toContain('.env')
+    })
+  })
+
   describe('Bash commands', () => {
     it('allows allowlisted npm commands', () => {
       expect(

packages/wizard/src/agent/interface.ts

@@ -114,7 +114,17 @@ const ALLOWED_WRITE_PATHS = [
 
 /** Sensitive file patterns the agent must not read directly. */
 const SENSITIVE_FILE_PATTERNS = [
-  /\.env($|\.)/, // .env, .env.local, .env.production, etc.
+  // `.env`, `.env.local`, `.env.production`, … but not the committed templates
+  // `.env.example` / `.env.sample` / `.env.template`. Those carry placeholder
+  // key names rather than values, and the agent doctrine
+  // (`packages/cli/src/commands/init/doctrine/AGENTS-doctrine.md`, invariant 3)
+  // instructs the agent to create and edit them — a blanket `.env.` rule made
+  // that impossible, since this guard also covers Edit and Write.
+  //
+  // The negative lookahead is anchored, so a value-bearing file that merely
+  // starts with a template name (`.env.example.bak`, `.env.example.local`)
+  // stays blocked.
+  /\.env($|\.(?!(example|sample|template)$))/,
   /auth\.json$/, // ~/.cipherstash/auth.json
   /secretkey\.json$/, // ~/.cipherstash/secretkey.json
   /credentials/i, // Various credential files
@@ -178,7 +188,9 @@ export function wizardCanUseTool(
       return 'Multi-line commands are not allowed for security reasons.'
     }
 
-    // Block direct .env access via Bash
+    // Block direct .env access via Bash. Deliberately stricter than the
+    // file-path guard above: `.env.example` is reachable through Read/Edit/Write,
+    // so there is no reason for the agent to touch any env file from a shell.
     if (/\.(env|env\.local)/.test(command)) {
       return 'Direct .env file access via Bash is blocked. Use the wizard-tools MCP server instead.'
     }