Problem

The PreToolUse Write hook in hooks.json (line 36-44) hard-blocks creation of any .md or .txt file that isn't in the whitelist (README.md, CLAUDE.md, AGENTS.md, CONTRIBUTING.md, .claude/plans/*).

This causes issues for projects that legitimately need non-whitelisted markdown files. For example, MCP Server projects require:

• CHANGELOG.md — standard versioning file, needed for mcpb deployment
• mcpb/PRIVACY.md — required by the MCP registry publishing workflow
• LICENSE — not blocked (no .md extension), but similar category

The current behavior is a hard exit(2) block with no way to proceed, forcing users to work around it via Bash cat > redirection.

Context

The hook's intent — preventing Claude from creating random documentation files and keeping docs consolidated — is sound for general projects. But the whitelist approach is too rigid for projects with legitimate needs.

Proposed Solution

Change from hard block (exit(2)) to soft warning (exit(0) + stderr message) for non-whitelisted .md files. This lets the AI see the warning and make its own judgment about whether the file is truly necessary.

// Current: hard block
if (isNonWhitelistedMd) {
  console.error('[Hook] BLOCKED: Unnecessary documentation file creation');
  process.exit(2);  // AI cannot proceed
}

// Proposed: soft warning — AI decides
if (isNonWhitelistedMd) {
  console.error('[Hook] WARNING: Creating non-standard .md file: ' + p);
  console.error('[Hook] Only create if truly necessary (e.g., CHANGELOG.md, PRIVACY.md for publishing).');
  console.error('[Hook] If this is just notes or docs, consolidate into README.md instead.');
  // exit(0) — AI sees warning and decides whether to proceed
}

Why this works

• AI sees the warning in stderr and understands it should be cautious
• Legitimate files (CHANGELOG.md, PRIVACY.md, etc.) can still be created when genuinely needed
• Random docs (notes.md, todo.md, etc.) — AI will typically self-correct after seeing the warning
• No whitelist maintenance — no need to keep adding exceptions for every valid file pattern

Alternative (less preferred)

Expand the whitelist to include CHANGELOG.md, LICENSE.md, PRIVACY.md, mcpb/*, etc. But this requires ongoing maintenance as new legitimate patterns emerge, which is why the soft-warning approach is better.

Affected Hook

hooks.json → PreToolUse → matcher "Write" (line 36-44):

{
  "matcher": "Write",
  "hooks": [{
    "type": "command",
    "command": "node -e \"...process.exit(2)...\""
  }],
  "description": "Block creation of random .md files - keeps docs consolidated"
}