claude-dev-env 8.40.0 → 8.41.0

package/hooks/test_transcript_skill_scan.py

@@ -0,0 +1,58 @@
+"""Tests for skill invocation state across transcript compactions."""
+
+import json
+import sys
+from pathlib import Path
+
+HOOKS_DIRECTORY = Path(__file__).resolve().parent
+if str(HOOKS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(HOOKS_DIRECTORY))
+
+from transcript_skill_scan import is_skill_loaded_after_last_compaction, skill_invocation_status
+
+
+def _skill_entry(name: str) -> str:
+    return json.dumps(
+        {"type": "assistant", "message": {"content": [{"type": "tool_use", "name": "Skill", "input": {"skill": name}}]}}
+    )
+
+
+def test_matching_skill_after_compaction_loads() -> None:
+    lines = [
+        _skill_entry("pr-lifecycle"),
+        json.dumps({"type": "system", "subtype": "compact_boundary"}),
+        _skill_entry("plugin:pr-lifecycle"),
+    ]
+    assert is_skill_loaded_after_last_compaction(
+        lines, ("pr-lifecycle",), ("<command-name>/pr-lifecycle</command-name>",)
+    )
+
+
+def test_compaction_drops_a_loaded_skill() -> None:
+    lines = [_skill_entry("pr-lifecycle"), json.dumps({"subtype": "compact_boundary"})]
+    assert not is_skill_loaded_after_last_compaction(lines, ("pr-lifecycle",), ())
+
+
+def test_user_command_loads_and_quoted_tool_result_does_not() -> None:
+    marker = "<command-name>/pr-lifecycle</command-name>"
+    user_entry = json.dumps({"type": "user", "message": {"content": marker}})
+    quoted_result = json.dumps(
+        {"type": "user", "message": {"content": [{"type": "tool_result", "content": marker}]}}
+    )
+    assert is_skill_loaded_after_last_compaction([user_entry], ("pr-lifecycle",), (marker,))
+    assert not is_skill_loaded_after_last_compaction([quoted_result], ("pr-lifecycle",), (marker,))
+
+
+def test_malformed_entries_do_not_load() -> None:
+    assert not is_skill_loaded_after_last_compaction(
+        ["pr-lifecycle {", json.dumps({"type": "assistant", "message": {"content": "pr-lifecycle"}})],
+        ("pr-lifecycle",),
+        (),
+    )
+
+
+def test_invocation_status_separates_ever_invoked_from_loaded_now() -> None:
+    compaction = json.dumps({"subtype": "compact_boundary"})
+    assert skill_invocation_status([_skill_entry("pr-lifecycle")], ("pr-lifecycle",), ()) == (True, True)
+    assert skill_invocation_status([_skill_entry("pr-lifecycle"), compaction], ("pr-lifecycle",), ()) == (True, False)
+    assert skill_invocation_status([compaction, _skill_entry("other")], ("pr-lifecycle",), ()) == (False, False)

package/hooks/transcript_skill_scan.py

@@ -0,0 +1,93 @@
+"""Find a skill invocation after the last transcript compaction."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Collection, Iterable
+
+from hooks_constants.transcript_skill_scan_constants import (
+    ASSISTANT_ENTRY_TYPE,
+    COMPACT_BOUNDARY_SUBTYPE,
+    SKILL_TOOL_NAME,
+    TOOL_USE_BLOCK_TYPE,
+    USER_ENTRY_TYPE,
+)
+
+
+def _invokes_skill(
+    all_entry_fields: dict[str, object],
+    skill_names: Collection[str],
+    slash_command_markers: Collection[str],
+) -> bool:
+    message = all_entry_fields.get("message")
+    if not isinstance(message, dict):
+        return False
+    content = message.get("content")
+    if all_entry_fields.get("type") == USER_ENTRY_TYPE and isinstance(content, str):
+        return any(marker in content for marker in slash_command_markers)
+    if all_entry_fields.get("type") != ASSISTANT_ENTRY_TYPE or not isinstance(content, list):
+        return False
+    for each_block in content:
+        if not isinstance(each_block, dict) or each_block.get("type") != TOOL_USE_BLOCK_TYPE:
+            continue
+        if each_block.get("name") != SKILL_TOOL_NAME or not isinstance(each_block.get("input"), dict):
+            continue
+        invoked_name = each_block["input"].get("skill")
+        if isinstance(invoked_name, str) and any(
+            invoked_name == name or invoked_name.endswith(":" + name) for name in skill_names
+        ):
+            return True
+    return False
+
+
+def _relevant_entry(each_line: str, skill_names: Collection[str]) -> dict[str, object] | None:
+    if not any(name in each_line for name in skill_names) and COMPACT_BOUNDARY_SUBTYPE not in each_line:
+        return None
+    try:
+        all_entry_fields = json.loads(each_line)
+    except json.JSONDecodeError:
+        return None
+    return all_entry_fields if isinstance(all_entry_fields, dict) else None
+
+
+def skill_invocation_status(
+    all_transcript_lines: Iterable[str],
+    skill_names: Collection[str],
+    slash_command_markers: Collection[str],
+) -> tuple[bool, bool]:
+    """Report whether the skill was ever invoked and whether it is loaded now.
+
+    Args:
+        all_transcript_lines: JSON transcript entries, one per line.
+        skill_names: Accepted skill names, with plugin prefixes accepted.
+        slash_command_markers: Accepted user command tags.
+
+    Returns:
+        Whether any entry invoked the skill, and whether an invocation follows
+        the last compact boundary.
+    """
+    was_invoked = False
+    loaded = False
+    for each_line in all_transcript_lines:
+        all_entry_fields = _relevant_entry(each_line, skill_names)
+        if all_entry_fields is not None:
+            loaded = all_entry_fields.get("subtype") != COMPACT_BOUNDARY_SUBTYPE and (
+                loaded or _invokes_skill(all_entry_fields, skill_names, slash_command_markers)
+            )
+            was_invoked = was_invoked or loaded
+    return was_invoked, loaded
+
+
+def is_skill_loaded_after_last_compaction(
+    all_transcript_lines: Iterable[str],
+    skill_names: Collection[str],
+    slash_command_markers: Collection[str],
+) -> bool:
+    """Return whether a matching invocation follows the last compact boundary.
+
+    Args:
+        all_transcript_lines: JSON transcript entries, one per line.
+        skill_names: Accepted skill names, with plugin prefixes accepted.
+        slash_command_markers: Accepted user command tags.
+    """
+    return skill_invocation_status(all_transcript_lines, skill_names, slash_command_markers)[1]

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.40.0",
+    "version": "8.41.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/flag-non-breaking-findings.md

@@ -130,5 +130,5 @@ zero when no error remains.
 
 | Rule | Role |
 |---|---|
-| [`ci-owns-the-gate.md`](ci-owns-the-gate.md) | The full check suite runs once, on CI |
-| [`git-workflow.md`](git-workflow.md) | A red required check blocks the branch |
+| [CI Owns the Gate](../.agents/skills/pr-lifecycle/SKILL.md#ci-owns-the-gate) | The full check suite runs once, on CI |
+| [Git workflow](../.agents/skills/pr-lifecycle/SKILL.md#git-workflow) | A red required check blocks the branch |

package/rules/shell-invocation.md

@@ -18,18 +18,6 @@ When a script file's literal body needs `$(...)`, author it with the Write tool,
 
 ## Enforcement
 
-No PreToolUse hook denies a Bash command. The substitution constraint above is guidance a reader follows, and a permission prompt on a wrapped command is the signal that one slipped through.
+No PreToolUse hook denies a Bash command for its shell form. The substitution constraint above is guidance a reader follows, and a permission prompt on a wrapped command is the signal that one slipped through.
 
-One PreToolUse hook does run on a Bash command, and it only rewrites. `blocking/msys_rev_path_rewriter.py` (PreToolUse on Bash, hosted by `bash_pre_tool_use_dispatcher`) reads a git command before it runs and keeps Git Bash from converting a `<rev>:<path>` argument. That roster holds this one hook, and a test asserts its whole content, so a blocking hook added beside it fails the suite.
-
-Git Bash rewrites that argument when the revision holds a slash and the path after the colon starts with a slash or a dot. It turns the colon into a semicolon and the slashes into backslashes, so `git show origin/main:.claude/settings.json` reaches git as `origin\main;.claude\settings.json` and git reports a revision that does not exist. A leading dot on a file is enough. `origin/main:.gitignore` reaches git as `origin\main;.gitignore`. `git show origin/main:packages/app.py` passes through untouched, and so does any path after the colon that starts with `./`, `../`, or `~/`. A revision without a slash, such as `HEAD:.claude/settings.json`, passes through too.
-
-On that shape the rewriter names only the arguments it found, so `git show origin/main:.claude/settings.json` runs as:
-
-```
-export MSYS2_ARG_CONV_EXCL='origin/main:'; git show origin/main:.claude/settings.json
-```
-
-`MSYS2_ARG_CONV_EXCL` takes a semicolon-separated list of argument prefixes. Naming one prefix per detected token leaves every other argument in the command converting as before. The blanket pair `MSYS_NO_PATHCONV=1 MSYS2_ARG_CONV_EXCL='*'` turns conversion off for the whole command, which changes a path the command meant to convert, so the rewriter does not emit it.
-
-A quoted token is not a revision. `git commit -m "fix a/b:.py"` carries a slash and a dot in one token, and a rewrite there would break the message, so the detection skips a token holding whitespace or a quote.
+`blocking/msys_rev_path_rewriter.py` only rewrites a Bash command. It keeps Git Bash from converting a `<rev>:<path>` argument when the revision holds a slash. A test pins the dispatcher roster to this one hook.

package/rules/skill-pointers.md

@@ -0,0 +1,3 @@
+# Pull request lifecycle skill
+
+Before a commit, a push, a pull request action or a merge, invoke the `pr-lifecycle` skill; a PreToolUse hook denies those commands until it loads.

package/scripts/policy_lint/adapter_configuration.py

@@ -127,6 +127,7 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
     ::
 
         hooks/blocking/bash_pre_tool_use_dispatcher.py   -> exempt
+        hooks/blocking/pr_lifecycle_skill_gate.py        -> exempt
         hooks/blocking/step_note_gate.py                 -> exempt
         hooks/blocking/reply_length_gate.py              -> exempt
         hooks/blocking/edit_marker_gate.py               -> exempt
@@ -137,6 +138,10 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
     while its roster hosts one allow-and-rewrite hook. Its path segment reads as
     a policy boundary that the chain never carries.
 
+    The pull request lifecycle gate denies a commit, push, pull request, or
+    merge call once, until the session loads the ``pr-lifecycle`` skill. It
+    decides when a rule set loads and no code or safety policy.
+
     The step-note gate allows every call until the user runs ``/step-notes on``.
     It asks for a readable status line and decides no code or safety policy.
 

package/scripts/policy_lint/config/constants.py

@@ -63,6 +63,7 @@ ALL_ACTION_BOUNDARY_SEGMENTS = frozenset(
 ALL_ACTION_BOUNDARY_PREFIXES = ("deny_", "block_", "ask_")
 ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/bash_pre_tool_use_dispatcher.py",
+    "blocking/pr_lifecycle_skill_gate.py",
     "blocking/step_note_gate.py",
     "blocking/reply_length_gate.py",
     "blocking/edit_marker_gate.py",

package/scripts/tests/test_adapter_configuration.py

@@ -50,6 +50,14 @@ def test_new_bash_pre_tool_use_dispatcher_registration_is_clean(tmp_path: Path)
     assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
 
 
+def test_pull_request_lifecycle_gate_registration_is_clean(tmp_path: Path) -> None:
+    current_document = _hook_document(
+        ["hooks/blocking/pr_lifecycle_skill_gate.py"],
+        '{"hooks": {}}',
+    )
+    assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
+
+
 def test_new_step_note_gate_registration_is_clean(tmp_path: Path) -> None:
     current_document = _hook_document(
         ["hooks/blocking/step_note_gate.py"],

package/scripts/tests/test_banned_prose_words.py

@@ -84,7 +84,7 @@ def test_governed_paths_lists_the_shipped_surfaces(tmp_path: Path) -> None:
 
 
 def test_governed_paths_cover_instruction_surfaces_and_skip_archives() -> None:
-    assert governs_path("rules/git-workflow.md")
+    assert governs_path(".agents/skills/pr-lifecycle/SKILL.md")
     assert governs_path(".agents/skills/eli5/SKILL.md")
     assert governs_path("audit-rubrics/prompts/category-o-docstring-vs-impl-drift.md")
     assert governs_path("system-prompts/software-engineer.xml")

package/scripts/tests/test_rule_load_scopes.py

@@ -10,23 +10,17 @@ ALWAYS_ON_RULE_NAMES = frozenset(
     {
         "AGENTS.md",
         "CLAUDE.md",
-        "agent-merges-its-own-green-pull-request.md",
         "asd-ste100-language.md",
-        "ci-owns-the-gate.md",
         "cleanup-temp-files.md",
         "correction-lens.md",
         "destructive-commands.md",
-        "durable-post-artifacts.md",
         "explore-thoroughly.md",
         "filesystem-search.md",
-        "gh-cli-conventions.md",
-        "git-workflow.md",
         "memory-stores-durable-facts.md",
         "no-contrast-framing.md",
         "question-presentation.md",
-        "re-stage-before-commit.md",
         "research-mode.md",
-        "review-closure-is-a-check.md",
+        "skill-pointers.md",
         "shell-invocation.md",
         "verify-before-asking.md",
         "verify-runtime-state.md",

package/rules/agent-merges-its-own-green-pull-request.md

@@ -1,55 +0,0 @@
-# The Agent Merges Its Own Green Pull Request
-
-**When this applies:** Any pull request an agent opened or was asked to drive, once its checks report.
-
-## Rule
-
-The agent that drives a pull request merges it. A pull request that is green, carries no open review thread, and sits at a merge state of `clean` is merged in the same run that brought it there. A merge state of `unstable` counts as `clean` when every check's newest report on the head passes. GitHub also counts the older runs of a check that ran again, so a cancelled run followed by a passing re-run still reads `unstable`. Waiting for the owner to type "merge" parks finished work on the person the work was done for.
-
-Three things stay with the owner, and nothing else does:
-
-- A pull request the owner asked to hold.
-- A change the owner said they want to read first.
-- A repository whose branch rule requires an approving review the agent cannot give.
-
-Where the branch rule requires zero approvals and one status check, that check is the gate, and the agent merges on its verdict.
-
-Validation is the precondition, and green means every check reported on the exact head commit. A branch rule that requires one status check names the floor a merge needs; a pull request whose other checks are red or still running is held until they report.
-
-## The precondition is mechanical
-
-One command prints the verdict:
-
-```
-python packages/claude-dev-env/scripts/agent_merge_check.py <owner>/<name> <number>
-```
-
-It prints `MERGE` and exits 0 when the pull request is ready. It prints `HOLD` with the reason and exits 1 for a draft, for a head behind or conflicting with the base, for a required check that is not passing, for a check whose newest report on the head is still running, cancelled, or red, for a head the merge queue ejected for failed checks, and for an open review thread. It exits 2 when the state could not be read.
-
-Each hold reason names its own repair, and each repair belongs to the agent:
-
-| Hold | What the agent does |
-|---|---|
-| Head behind the base | Merge the base branch in and push |
-| Head conflicts with the base | Merge the base branch in, resolve, push |
-| A required check is red | Read the failing check, fix it, push |
-| A check is red, cancelled, or still running | Fix a red one, re-run a cancelled one, or wait for a running one, then read the verdict again |
-| A review thread is open | Answer it, push the fix, resolve the thread |
-| Ejected from the merge queue for failed checks on this head | Read the merge_group run, fix the failure, push, then read the verdict again |
-| The pull request is a draft | Mark it ready once the checks pass |
-
-## When a gate elsewhere holds the merge command
-
-A session working inside another repository can sit behind that repository's own pre-merge gate, which reads the checkout the session works in and refuses a merge command whatever repository the pull request belongs to. That session hands the merge to the session that owns this repository's pull requests, by message, naming the pull request. The receiving session reads the verdict above and merges. The hand-off carries the work; it never lands on the owner.
-
-## After the merge
-
-Delete nothing by hand. The repository deletes the head branch on merge.
-
-## Sibling rules
-
-| Rule | Role |
-|---|---|
-| [`git-workflow.md`](git-workflow.md) | Open ready for review, and confirm each required context fired after the push |
-| [`ci-owns-the-gate.md`](ci-owns-the-gate.md) | The gate runs once, and it runs on CI |
-| [`correction-lens.md`](correction-lens.md) | A correction becomes a control at the highest layer that can hold it |

package/rules/ci-owns-the-gate.md

@@ -1,101 +0,0 @@
-# CI Owns the Gate
-
-**When this applies:** Before pushing a branch, and any time a repository's full
-check suite or policy gate is about to run on your own machine.
-
-## Rule
-
-The gate runs once, and it runs on CI. Push the branch, read the verdict, act on
-what it says.
-
-The inner development loop stays yours. Run the single test you are writing, as
-often as it helps. That is how the change gets built. This rule governs the
-second full pass, the one whose only product is a prediction of CI's answer.
-Push instead, and spend the wait on the next piece of work.
-
-## Why
-
-**A pinned gate answers only from its pinned revision.** The workflow names an
-exact revision of the policy package, and that revision decides which rules run.
-The copy under your home directory is a separate artifact at its own revision. A
-run against the home copy reports on those rules, which are a different question
-from the one CI asks. Treat its exit code as information about the home copy
-alone.
-
-**Self-hosted runners often share your machine.** Where the runners execute on
-the same host as your shell, a local suite run draws its processor time from the
-runners, and it does so while they work on the branch you just pushed. Read
-where the runners live, and count a local run against the same budget.
-
-**One authoritative answer beats two.** Where both runs agree, the second one
-restated the first. Where they differ, the environments differ, and CI is the
-environment that decides.
-
-## Running a gate locally
-
-Clone the revision the workflow pins, then point the gate at that clone. That
-run asks CI's question and its answer carries. Report a local result by naming
-the revision it used, so a reader can tell which question it answered.
-
-The selection flag decides which question the staged policy lint answers.
-`--staged` and `--base <revision>` carry each file's prior text, so the lint
-subtracts what the prior text already reported and only a breach the change
-introduced survives. `--files` and `--repository` carry no prior text, so every
-breach in the file reports and the command exits non-zero on debt the change
-never touched. CI runs the merge-base form, so reproduce a CI verdict with it:
-
-```
-git merge-base HEAD origin/main
-python packages/claude-dev-env/scripts/cde_lint.py --base <the revision that printed>
-```
-
-A `--files` run that comes back red on a file you touched has answered a
-different question. Read the reported line before you treat it as yours.
-
-## The verdict belongs to CI
-
-CI decides whether a change passed, from evidence CI gathered. Keep that loop
-closed. A flag, trailer, receipt, or environment variable through which the
-change under test announces its own result hands the verdict to the subject.
-Where the runner and the agent share one host, a signature names the same party
-twice, so it carries the claim no further.
-
-A cache stays available on one condition. CI derives the key itself from the
-tree it is about to test, looks for a previous run under that key, and
-republishes that result. CI computes, CI verifies, CI decides.
-
-## A repository that runs no CI
-
-An owner can rule that a repository spends no CI minutes. There the local gate
-is the gate, and the agent that drives the pull request runs it on every head
-it asks to merge. The repository carries the gate as a `cde verify` manifest at
-`.claude/local-gate.json`: tests with collection floors, and lint.
-
-1. Check out the pull request head with a clean tree and fetch its base.
-2. Run the manifest against the base commit the pull request names:
-
-   ```
-   python <cde>/scripts/local_verification/cli.py --manifest .claude/local-gate.json --repo . --base <base sha> --output <outside the repository>/report.json
-   ```
-
-3. Publish the report:
-
-   ```
-   python <cde>/scripts/local_report_publisher.py --token-environment GH_TOKEN --repository <owner>/<name> --pull-number <number> --local-repo . --manifest .claude/local-gate.json --report <outside the repository>/report.json
-   ```
-
-The publisher checks the report against the manifest digest, the clean tree,
-and the live head and base, then posts the `local-checks` commit status. A
-report that fails any of those posts a failure or an error. The branch ruleset
-lists `local-checks` as a required status check, so the host refuses a merge
-until a passing report covers the head, and `agent_merge_check.py` prints
-`HOLD` on the same requirement. A push moves the head and leaves the status
-behind, so each new head runs the gate again.
-
-## Sibling rules
-
-| Rule | Role |
-|---|---|
-| [`git-workflow.md`](git-workflow.md) | Confirm each required context fired after the push |
-| [`verify-runtime-state.md`](verify-runtime-state.md) | A status field is a report; read the thing the work was meant to make |
-| [`falsify-before-green.md`](falsify-before-green.md) | A green counts as evidence once the check has run red on a deliberate break |

package/rules/durable-post-artifacts.md

@@ -1,76 +0,0 @@
-# GitHub post input rules
-
-## When this applies
-
-Use this rule for a GitHub issue, pull request, comment, or review created
-through `gh` or a GitHub MCP post tool. The image section also covers a PNG a
-commit adds and a file a release upload sends.
-
-## Rule
-
-A post remains after the job ends. Job scratch directories, worktrees, and
-system temp folders do not. Do not put a path from one of those directories in
-a post.
-
-Handle text and binary content differently:
-
-- **Text data** such as logs, tables, diffs, and stack traces belongs inline in
-  the post body. Do not link a scratch file that holds text data.
-- **Binary artifacts** such as images, screenshots, and archives belong in the
-  repository's durable `artifacts` release. Use the helper:
-
-  ```
-  python3 ~/.claude/scripts/gh_artifact_upload.py <file-path> <owner/repo>
-  ```
-
-  The helper creates the `artifacts` prerelease when needed, uploads the file
-  under a `YYYYMMDD_HHMMSS_<name>` asset name, and prints a permanent download
-  URL. Put that URL in the post.
-
-## Optimize every image before it reaches GitHub
-
-The helper shrinks a PNG with [oxipng](https://github.com/oxipng/oxipng) before
-it uploads, and prints the size before and after. Oxipng is lossless.
-`--strip none` keeps every chunk, and `--nb --nc` keep the bit depth and the
-color type, so a reader that checks the image mode sees the same file shape.
-
-Any other route to GitHub runs the same pass first: a PNG a commit adds, and a
-file sent with `gh release upload`.
-
-```
-oxipng --opt 4 --strip none --nb --nc <file> [<file> ...]
-```
-
-The `Binary optimization` check fails a pull request whose changed PNG files
-still shrink under that pass. A fixture whose exact bytes a test pins takes
-`binary-optimizer=keep` in `.gitattributes`, and the check skips it.
-
-## Volatile paths that must not appear in a post body
-
-- A job scratch directory: `.claude-profile-a/jobs/`
-- A worktree: `.claude/worktrees/`
-- A system temp location: `AppData\\Local\\Temp`, `%TEMP%`, `$env:TEMP`, or
-  `/tmp/`
-- The job scratch environment variable: `$CLAUDE_JOB_DIR`
-
-Both slash directions count. The path rule applies when a slash or backslash
-precedes a marker, or when a path segment follows it. A standalone directory
-name does not form a path.
-
-## Validation
-
-Resolve the active managed root (`CLAUDE_CONFIG_DIR` when set, `~/.claude`
-otherwise), then run `<managed-root>/scripts/durable_post_lint.py` before the
-server write. Pass the matching action and body file. Use `pr-create`,
-`pr-edit`, `pr-comment`, `pr-review`, `issue-create`, `issue-edit`,
-`issue-comment`, or `github-mcp-post`.
-
-Pass `--repository <owner>/<name>` for the repository the post targets. A
-post may name a private organization only inside a repository that
-organization owns. The same digests cover the owner's private repository, the
-owner's personal handle, and a private client. The linter holds the names as
-digests, so it reports the line that names one without printing the name.
-Describe the name in general terms and drop the link.
-
-The linter reads the body file and reports a volatile local path without
-printing the body. Fix the body and rerun the linter before posting.

package/rules/gh-cli-conventions.md

@@ -1,36 +0,0 @@
-# gh CLI conventions
-
-Two `gh` call shapes need explicit handling.
-
-## Put body content in a file
-
-Every `gh` command that carries markdown body content uses
-`--body-file <path>`. This applies to `gh pr create`, `gh pr edit`,
-`gh pr comment`, `gh pr review`, `gh issue create`, `gh issue edit`, and
-`gh issue comment`. Never pass a `--body` or `-b` string. Write the file as
-BOM-free UTF-8:
-
-```powershell
-[IO.File]::WriteAllText($bodyPath, $body, [Text.UTF8Encoding]::new($false))
-```
-
-MCP GitHub tools take `body` as a structured parameter. Write the same body to
-a UTF-8 file and run the shared linter before sending that parameter.
-
-For pull requests, use
-`.agents/skills/pull-request/scripts/pull_request.py`. It passes
-`--body-file` to `gh` after the action-aware linter succeeds. For issues and
-GitHub MCP posts, run the linter directly with `issue-create`, `issue-edit`,
-`issue-comment`, or `github-mcp-post` as the action.
-
-## Paginated reads slurp before they filter
-
-Every `gh api` read of a paginated GitHub list endpoint uses
-`--paginate --slurp` and pipes the result to external `jq`. This applies to PR
-reviews, comments, and files, plus issue comments, pulls, and issues. The
-built-in `--jq` runs once per page and can produce a wrong cross-page result.
-
-Single-object endpoints such as `pulls/<n>` and `issues/<n>` do not need
-pagination and may use `--jq` directly. For a newest-first walk, sort the
-slurped array and take the last element. For one page, cap the request with a
-`per_page` query parameter.