@@ -165,23 +165,8 @@ Per-script quirks (auth style, pagination, sentinels, reports) live in [`docs/sc
 
 ### Testing Approach
 
-The project has a bats unit-test suite in `tests/`. Run the full suite with:
-
-```bash
-bats tests/
-```
-
-| File | What it covers |
-|------|----------------|
-| `tests/test_common.bats` | `lib/github-common.sh` pure-logic functions and API helpers |
-| `tests/test_script_validation.bats` | Every script — missing env vars, invalid args, `--help`, script-specific guards |
-| `tests/mock_curl.sh` | Universal curl mock used by both test files |
-
-Every new script **must** include a test section in `tests/test_script_validation.bats` before it is merged. At minimum test: each required env var missing exits 1, unknown CLI args exit 1, and any enum or allowlist validation specific to the script.
-
-Additional testing approaches:
-- **Always test on a test organization first** before running against production
-- **Dry-run flags** — several scripts support `--dry-run` to preview changes without applying them
+Run `bats tests/`. Test files, the mocking pattern and the required cases for
+every new script are in the "Testing" section of [`AGENTS.md`](../AGENTS.md).
 
 ### Commit Messages — Conventional Commits (required)
 
@@ -222,7 +207,7 @@ When you change one of these files, you must also update the files in the "Also
 
 | When you change… | Also update |
 |------------------|-------------|
-| `lib/github-common.sh` — any public function signature or behaviour | All 18 scripts that source it; verify each caller still passes the right arguments. Check with: `grep -r "github-common" . --include="*.sh"` |
+| `lib/github-common.sh` — any public function signature or behaviour | Every script that sources it; verify each caller still passes the right arguments. List them with: `grep -rl "github-common" . --include="*.sh"` |
 | `lib/github-common.sh` — add a new helper function | `AGENTS.md` shared library table; `README.md` if the function affects usage |
 | `gh_api_paginate` signature or pagination behaviour | `github-repo-permissions-report.sh` (3 call sites), `github-copilot-report.sh` (`fetch_seats`) — both pipe output through `jq -s '.'` and depend on the `jq_filter`/`api_version` parameter order |
 | Any script's required env vars | That script's `# ===` header comment; the corresponding README.md section's env var table; that script's `action.yml` inputs (add/remove required inputs to match) |
 
@@ -3,21 +3,34 @@
 # block-file-writes-via-bash.sh
 #
 # preToolUse hook for the bash tool. Denies commands that write file contents
-# through heredocs or tee, steering the agent to the create/edit tools.
+# through heredocs, tee, or interpreter heredoc scripts, steering the agent to
+# the create/edit tools. Allows the command if the payload cannot be parsed.
 # =============================================================================
 
 set -euo pipefail
 
+deny() {
+  jq -nc '{permissionDecision: "deny",
+           permissionDecisionReason: "Write files with the create or edit tools; bash heredoc writes are blocked."}'
+  exit 0
+}
+
+# Fail open: an unparseable payload must not block every bash call
 payload="$(cat)"
-tool_name="$(printf '%s' "${payload}" | jq -r '.toolName // ""')"
+tool_name="$(printf '%s' "${payload}" | jq -r '.toolName // ""' 2>/dev/null)" || exit 0
 [[ "${tool_name}" == "bash" ]] || exit 0
 
 # toolArgs arrives as a JSON string on some hosts and as an object on others
-command="$(printf '%s' "${payload}" | jq -r '.toolArgs // {} | if type == "string" then fromjson else . end | .command // ""')"
+command="$(printf '%s' "${payload}" | jq -r '.toolArgs // {} | if type == "string" then fromjson else . end | .command // ""' 2>/dev/null)" || exit 0
 
 # Heredoc redirected into a file or tee: cat > f <<EOF, tee f <<'EOF', cat >> f <<-EOF
 if printf '%s' "${command}" | grep -Eq '(>|tee)[^<|;&]*<<-?[[:space:]]*['\''"\\]?[A-Za-z_]'; then
-  jq -nc '{permissionDecision: "deny",
-           permissionDecisionReason: "Write files with the create or edit tools; bash heredoc writes are blocked."}'
+  deny
+fi
+
+# Heredoc script for an interpreter that opens a file for writing
+if printf '%s' "${command}" | grep -Eq '(python3?|node|ruby|perl)[^<|;&]*<<' \
+  && printf '%s' "${command}" | grep -Eq 'open\([^)]*['\''"][wa]\+?['\''"]|writeFile|write_text|File\.write'; then
+  deny
 fi
 exit 0
@@ -1,190 +1,20 @@
 ---
-description: "Write only the resulting content into files. Never echo prompt instructions, rationale, or meta-commentary into documentation, comments, or code being produced from a prompt."
+description: "Write only the resulting content into files, with no prompt framing or meta-commentary"
 applyTo: '**'
 ---
 
 # Exclude Prompt Data
 
-When a prompt contains instructional or contextual data used to guide a change,
-that data must not appear in the file being updated. The output must reflect
-only the *result* of the instruction — not the instruction itself, the
-reasoning behind it, or any acknowledgment that it was applied.
+Write each file as if its content always belonged there. A reader with no
+knowledge of the prompt should find it natural and self-contained.
 
-## Core Rule
+- Describe the subject, not the change: "Validates email format", not
+  "Added email validation as requested".
+- Example data uses generic placeholders (`Jane Doe`, `jane.doe@example.com`,
+  `Acme Corp`, `my-org`, `example.com`), never real names, emails, domains,
+  enterprises or organizations from the prompt or local configuration.
+- Output is polished and production-ready regardless of how the prompt was
+  phrased.
 
-> **Never echo prompt content into the file being changed.**
->
-> Only write the outcome. Strip any meta-commentary, rationale, or framing that
-> originated in the prompt.
-
-## What Counts as Prompt Data
-
-Prompt data is any content the user provides as instruction or context rather
-than as intended file content:
-
-- Descriptions of what to add or change (`"add a --verbose flag that..."`)
-- Inline rationale or motivation (`"because the old behavior caused..."`)
-- References to the prompt itself (`"as requested"`, `"per the prompt"`,
- `"the new feature has been added as"`)
-- Meta-commentary about the update
- (`"This section has been updated to reflect..."`)
-- Code comments that narrate a change rather than describe the code
- (`"// Added email validation as requested"`,
- `"// Now validates the input per the new requirement"`)
-- Structural scaffold labels used as section markers or template slots
- (the word `this` in `## this Title` is scaffolding, not heading text)
-
-## What Belongs in the Output
-
-The output file should contain only:
-
-- The feature, fix, or content the prompt requested — written as if it always
- belonged there
-- Documentation or code that a reader would find useful independent of how the
- change was requested
-- Generic, cliche placeholder data in examples (e.g., `Jane Doe`,
- `jane.doe@example.com`, `Acme Corp`, `example.com`) — never real names,
- emails, domains, or organization identifiers pulled from the prompt or local
- configuration
-- Language formatting applied to terms in the prompt carries through to the
- output — if the prompt wraps a term in backticks or uses a specific syntax
- convention, follow that same convention in the output
-
-## Output Quality
-
-The prompt's writing quality does not set the bar for the output. Regardless
-of how a prompt is phrased, the result must be polished and production-ready:
-
-- Correct grammar, capitalization, and punctuation throughout
-- No draft-quality prose or casually written sections
-- Informal or sloppy phrasing in the prompt must not carry into the output
-
-## Use Cases
-
-### Adding a Feature Flag to Documentation
-
-**Prompt**
-
-```text
-Update file.ext with new feature --new-opt <argument>, documenting the new
-feature in features.md
-```
-
-**Acceptable result — `features.md`**
-
-```text
-### --new-opt
-
-Enables extended output. Requires a value argument. Example:
-
-    ```bash
-    file --new-opt foo
-    ```
-```
-
-**Unacceptable result — `features.md`**
-
-```text
-### --new-opt
-
-The new feature `--new-opt` requiring an argument has now been added as
-requested. The feature is documented as such.
-
-Enables extended output. Requires a value argument. Example:
-
-    ```bash
-    file --new-opt foo
-    ```
-```
-
-The unacceptable version echoes the prompt's framing
-(`"has now been added as requested"`, `"The feature is documented as such"`).
-That language belongs in the prompt, not the file.
-
----
-
-### Updating a Code File
-
-**Prompt**
-
-```text
-Add input validation to the createUser function — email must be a valid format.
-```
-
-**Acceptable result**
-
-```js
-function createUser(name, email) {
-  // Rejects addresses missing a local part, @ sign, or domain
-  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
-    throw new Error('Invalid email address.');
-  }
-  // ...
-}
-```
-
-**Unacceptable result**
-
-```js
-// Added email validation as requested in the prompt
-function createUser(name, email) {
-  // Per the instruction, we now validate that email must be a valid format
-  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
-    throw new Error('Invalid email address.');
-  }
-  // ...
-}
-```
-
-The unacceptable version leaks prompt phrasing into code comments. Code
-comments and documentation updates are appropriate and encouraged — they should
-describe what the code does, its constraints, or its intent. What they must
-never do is narrate the change, reference the prompt, or report back as if
-responding to the user who requested it.
-
-## Exceptions
-
-A small number of cases legitimately require prompt content to appear in the
-file. Treat these as exceptions, not loopholes:
-
-- **Verbatim transcription requested.** The user explicitly asks for prompt
- text to be inserted as-is (e.g., "paste this block into the README under
- `## Notice`"). Insert exactly what was requested and nothing more.
-- **The file *is* a prompt or instruction artifact.** When editing prompt
- files, skill definitions, or instruction files, instructional content is the
- intended payload. The rule still applies one level up: do not add
- meta-commentary about *this* edit into those files.
-- **Changelog or release-note entries.** A short, factual line describing the
- change is appropriate. Keep it about the change, not about the request
- (`Added --verbose flag` ✓ / `Added --verbose flag as requested by user` ✗).
-
-## Self-Check Before Saving
-
-Before committing an edit produced from a prompt, scan the diff for any of the
-following and remove what you find:
-
-- [ ] Phrases like "as requested", "per the prompt", "per your instruction",
- "as you asked"
-- [ ] Sentences that announce a change rather than describe the subject
- ("This section now covers...", "Updated to include...")
-- [ ] Comments that explain why code was written instead of what it does
-- [ ] Verbatim restatement of the user's request inside the file
-- [ ] Acknowledgments of the prompt's existence at all
-
-If any of these appear, rewrite the affected section so a fresh reader — with
-no knowledge of the prompt — would find the content natural and self-contained.
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| Output contains "as requested" or "per the prompt" | Remove it |
-| Docs announce a change instead of documenting it | Rewrite directly |
-| Code comments narrate the change | Describe the code's behavior |
-| Prompt scaffold labels appear in output headings | Replace with original |
-
-## Summary
-
-Write the result, not the story of how you got there. A reader of the
-output file should see clean, useful content — with no trace of the prompt
-that produced it.
+Exceptions: verbatim text the user asks to insert, and prompt or instruction
+files whose payload is instructions.
@@ -1,78 +1,12 @@
 ---
 name: 'No Heredoc File Operations'
-description: 'Prevents terminal heredoc file corruption in VS Code Copilot by enforcing use of file editing tools instead of shell redirections'
+description: 'Write file contents with the create and edit tools'
 applyTo: '**'
 ---
 
-# MANDATORY: File Operation Override
+# File Writes
 
-This instruction applies to ALL agents and ALL file operations. It takes precedence over any other learned behavior.
-
-## The Problem
-
-Terminal heredoc operations are BROKEN in VS Code's Copilot integration. They cause:
-
-- File corruption from tab characters triggering shell completion
-- Mangled content from quote/backtick escaping failures
-- Truncated files from exit code 130 interruptions
-- Garbage output from special character interpretation
-
-## The Rule
-
-**BEFORE writing ANY terminal command that creates or modifies a file, STOP.**
-
-Ask yourself: "Am I about to use `cat`, `echo`, `printf`, `tee`, or `>>`/`>` to write content to a file?"
-
-If YES → **DO NOT EXECUTE.** Use file editing tools instead.
-
-## Forbidden Patterns
-
-```bash
-# ALL OF THESE CORRUPT FILES - NEVER USE THEM
-cat > file << EOF
-cat > file << 'EOF'
-cat > file <<EOF
-cat > file <<'EOF'
-cat > file <<-EOF
-cat >> file << EOF
-echo "multi
-line" > file
-printf '%s\n' "line1" "line2" > file
-tee file << EOF
-tee file << 'EOF'
-```
-
-## Required Approach
-
-Instead of terminal commands for file content:
-
-- **New files** → Use the file creation/editing tool provided by your environment
-- **Modify files** → Use the file editing tool provided by your environment
-- **Delete files** → Use the file deletion tool or `rm` command
-
-## Terminal IS Allowed For
-
-- `npm install`, `pip install`, `cargo add` (package management)
-- `npm run build`, `make`, `cargo build` (builds)
-- `npm test`, `pytest`, `go test` (testing)
-- `git add`, `git commit`, `git push` (version control)
-- `node script.js`, `python app.py` (running existing code)
-- `ls`, `cd`, `mkdir`, `pwd`, `rm` (filesystem navigation)
-- `curl`, `wget` (downloading, but not piping to files with content manipulation)
-
-## Terminal is FORBIDDEN For
-
-- ANY file creation with content
-- ANY file modification with content
-- ANY heredoc syntax (`<<`)
-- ANY multi-line string redirection
-
-## Enforcement
-
-This is not a suggestion. This is a hard technical requirement due to VS Code terminal integration bugs. Ignoring this instruction will result in corrupted files that the user must manually fix.
-
-When you need to create or edit a file:
-
-1. Stop before typing any terminal command
-2. Use the appropriate file editing tool
-3. The tool will handle the content correctly without corruption
+Write and modify file contents with the create and edit tools. Terminal
+heredocs, `tee`, and interpreter heredoc scripts that open files for writing
+corrupt content in the VS Code terminal; the preToolUse hook
+`.github/hooks/scripts/block-file-writes-via-bash.sh` denies them.