[DESIGN] .gitignore should not double as AI access control — introduce clear .claudeignore semantics

Problem

\.gitignore\ and AI-access-control are orthogonal concerns, but Claude Code currently lacks a proper mechanism to express the latter. A directory can be gitignored for perfectly legitimate reasons — for example, internal planning/spec documents generated by plugins (e.g. \docs/superpowers/\) that should never be committed but that the AI needs to read and write freely.

The absence of a proper \.claudeignore\ leads to two problems:

1. Users who want to restrict AI access to sensitive files have no official mechanism (issue #16704 documents the confusion — Claude Code the model sometimes recommends a \.claudeignore\ file that doesn't actually exist, causing users to think the feature is real).
2. Users who gitignore a directory for legitimate reasons (e.g. internal scaffolding artefacts) may find Claude Code treating those paths as off-limits, since \.gitignore\ ends up being used as a proxy.

Expected behaviour

• \.gitignore\ → tells git what not to track. The AI should be indifferent to this.
• \.claudeignore\ → tells Claude Code what not to read/touch. Separate file, separate semantics, explicit opt-in.

These two files may overlap, but they should be independent. A file can be:

• gitignored + claudeignored (e.g. \.env\ secrets)
• gitignored but NOT claudeignored (e.g. local planning docs the AI generates and uses)
• tracked by git but claudeignored (e.g. a large binary the AI should skip)
• neither (normal files)

Current workaround pain

Plugins like superpowers write implementation plans to \docs/superpowers/plans/\ and specs to \docs/superpowers/specs/\. Users correctly gitignore \docs/superpowers/\ because these are internal scaffolding artefacts. But then Claude Code may block or warn on operations touching those paths, forcing users to either commit the artefacts (wrong) or not gitignore them (also wrong).

Proposal

1. Introduce \.claudeignore\ as a first-class, officially supported file with documented glob semantics.
2. Stop using \.gitignore\ as a proxy for AI access restrictions.
3. Stop the model from hallucinating \.claudeignore\ support in responses when the feature doesn't exist (see #16704).
4. Document the distinction clearly.

Note: Gemini CLI already ships \.geminiignore\ as an officially supported equivalent.