principles: add "Avoiding prompt fatigue" as §1, ahead of the security principle (PMC vote required)

[potiuk]

Summary

• Principle amendment proposal — needs a PMC vote before merge. Adds ## 1. Avoiding prompt fatigue to PRINCIPLES.md, ahead of "Privacy, security, and supply-chain integrity ship before features". Per Amending these principles, adding a principle and changing the ordering require a [VOTE] on private@ mirrored to dev@, ≥3 binding +1, no binding -1, a 72-hour window, and the result recorded on dev@ and linked from the merge commit.
• Why now: fix(agent-isolation): list gh write subcommands in ask instead of a catch-all that prompted on every read #1290 found that the reference config's catch-all Bash(gh *) ask rule had been prompting on every gh read since it was written, because Claude Code evaluates ask before allow regardless of specificity. Nobody noticed for months because the prompts were being clicked through — which is RFC-AI-0002 § Layer 3a's prompt-fatigue argument playing out on the framework's own maintainers. The principle names the rule the fix relied on: read-only actions do not prompt, writes prompt once in a judgeable shape, bulk work is a bounded operation, and a prompt on a read is a defect of the same severity as a missing prompt on a write.
• Placement before the security principle is deliberate and is the part most worth debating on the vote thread: earlier principles outrank later ones, and the claim here is that a confirmation the human has learned to click through is no control at all, so keeping prompts meaningful is a precondition of the security principle, not a competitor to it.

Type of change

• Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Groovy reference impl
• Project template (projects/_template/)
• CI / dev loop (prek, workflows, validators)
• Other:

Test plan

• prek run --files <all changed files> passes, including lychee — the renumbering touches every PRINCIPLES.md#N-… anchor in the tree (21 files) and lychee's fragment check is what proves none dangle
• Renumbering done by script (descending, boundary-anchored regex) rather than by hand: link anchors, bare PRINCIPLES.md#N, §N on lines that link the file, and the three unlinked "Principle N" mentions in the optimize-skill docs
• Token table regenerated (optimize-skill's SKILL.md changed by one digit)
• Stacked on fix(agent-isolation): list gh write subcommands in ask instead of a catch-all that prompted on every read #1290 so sandbox-lint's live-vs-baseline check passes on the same working tree; rebase onto main once fix(agent-isolation): list gh write subcommands in ask instead of a catch-all that prompted on every read #1290 merges

RFC-AI-0004 compliance

• HITL — the principle strengthens the confirmation gate by keeping it readable; it does not remove any prompt on a write
• Sandbox — n/a
• Vendor neutrality — no project-specific values
• Conversational + correctable — n/a
• Write-access discipline — n/a
• Privacy LLM — n/a

Linked issues

Refs #1290 (the fix that motivated this), #1289.

Notes for reviewers (optional)

• Vote threads: a [VOTE] on private@magpie.apache.org mirrored on dev@magpie.apache.org will follow this PR; the merge commit must link the recorded result.
• If the PMC prefers the principle after the security principle, only PRINCIPLES.md and the renumbering change; the text stands either way. The ordering argument is in the Summary.
• docs/rfcs/RFC-AI-0002.md § Layer 3a gains one sentence linking the principle; no other RFC text changes beyond anchor numbers.

🤖 Generated with Claude Code

[potiuk]

Converted to draft while the Vote is runnning https://lists.apache.org/thread/bl8lhj9c0jls8h5s3172vw6gg1pvwkwb