claude-dev-env 1.39.0 → 1.40.0

package/_shared/pr-loop/scripts/tests/test_post_audit_thread.py

@@ -43,7 +43,9 @@ if str(SCRIPT_DIRECTORY) not in sys.path:
 from config.post_audit_thread_constants import (  # noqa: E402
     ALL_GH_AUTH_TOKEN_COMMAND_PARTS,
     ALL_RETRY_BACKOFF_SECONDS,
+    BUGTEAM_REVIEWER_ACCOUNT_ENV_VAR_NAME,
     GH_TOKEN_ENV_VAR_NAME,
+    GITHUB_TOKEN_ENV_VAR_NAME,
     CLI_FLAG_COMMIT,
     CLI_FLAG_FINDINGS_JSON,
     CLI_FLAG_OWNER,
@@ -69,7 +71,15 @@ from config.post_audit_thread_constants import (  # noqa: E402
     STATE_CLEAN,
     STATE_DIRTY,
 )
-from post_audit_thread import build_reviews_endpoint_url  # noqa: E402
+from post_audit_thread import (  # noqa: E402
+    UserInputError,
+    build_reviews_endpoint_url,
+    fetch_gh_token_for_account,
+    list_authenticated_gh_account_logins,
+    query_active_gh_user_login,
+    query_pull_request_author_login,
+    resolve_reviewer_token,
+)
 
 LIVE_TEST_OWNER = "JonEcho"
 LIVE_TEST_REPO = "tests"
@@ -918,6 +928,189 @@ class LivePostAuditThreadTests(unittest.TestCase):
             f"(1s + 4s + 16s); elapsed={elapsed_seconds:.2f}s",
         )
 
+    def _isolate_auth_env_vars(self) -> dict[str, str | None]:
+        all_managed_env_var_names = (
+            GH_TOKEN_ENV_VAR_NAME,
+            GITHUB_TOKEN_ENV_VAR_NAME,
+            BUGTEAM_REVIEWER_ACCOUNT_ENV_VAR_NAME,
+        )
+        previous_env_state: dict[str, str | None] = {
+            each_name: os.environ.get(each_name)
+            for each_name in all_managed_env_var_names
+        }
+        for each_name in all_managed_env_var_names:
+            os.environ.pop(each_name, None)
+        return previous_env_state
+
+    def _restore_auth_env_vars(
+        self, previous_env_state: dict[str, str | None]
+    ) -> None:
+        for each_name, prior_value in previous_env_state.items():
+            if prior_value is None:
+                os.environ.pop(each_name, None)
+            else:
+                os.environ[each_name] = prior_value
+
+    def test_query_active_gh_user_login_matches_gh_api_user_login_field(self) -> None:
+        active_login = query_active_gh_user_login()
+        self.assertTrue(
+            active_login,
+            "query_active_gh_user_login() returned empty",
+        )
+        gh_api_user_response = gh_api_object_json("user")
+        self.assertEqual(active_login, gh_api_user_response.get("login"))
+
+    def test_query_pull_request_author_login_matches_throwaway_pr_author(self) -> None:
+        author_login = query_pull_request_author_login(
+            owner=LIVE_TEST_OWNER,
+            repo=LIVE_TEST_REPO,
+            pr_number=self.pr_number,
+        )
+        pr_detail_path = f"repos/{LIVE_TEST_OWNER}/{LIVE_TEST_REPO}/pulls/{self.pr_number}"
+        pr_detail_object = gh_api_object_json(pr_detail_path)
+        user_field_object = pr_detail_object.get("user")
+        self.assertIsInstance(user_field_object, dict)
+        if isinstance(user_field_object, dict):
+            self.assertEqual(author_login, user_field_object.get("login"))
+
+    def test_list_authenticated_gh_account_logins_includes_active_and_audit_accounts(
+        self,
+    ) -> None:
+        all_logins = list_authenticated_gh_account_logins()
+        active_login = query_active_gh_user_login()
+        self.assertIn(active_login, all_logins)
+        self.assertIn(LIVE_TEST_AUDIT_ACCOUNT_NAME, all_logins)
+
+    def test_fetch_gh_token_for_account_returns_audit_account_cached_token(self) -> None:
+        fetched_token = fetch_gh_token_for_account(LIVE_TEST_AUDIT_ACCOUNT_NAME)
+        self.assertEqual(fetched_token, self.audit_account_token)
+
+    def test_resolve_reviewer_token_returns_env_var_when_gh_token_is_set(self) -> None:
+        sentinel_env_token = "sentinel-gh-token-from-env-var-precedence-test"
+        previous_env_state = self._isolate_auth_env_vars()
+        try:
+            os.environ[GH_TOKEN_ENV_VAR_NAME] = sentinel_env_token
+            returned_token = resolve_reviewer_token(
+                owner=LIVE_TEST_OWNER,
+                repo=LIVE_TEST_REPO,
+                pr_number=self.pr_number,
+            )
+            self.assertEqual(returned_token, sentinel_env_token)
+        finally:
+            self._restore_auth_env_vars(previous_env_state)
+
+    def test_resolve_reviewer_token_toggles_to_alternate_token_on_self_pr(self) -> None:
+        previous_env_state = self._isolate_auth_env_vars()
+        try:
+            returned_token = resolve_reviewer_token(
+                owner=LIVE_TEST_OWNER,
+                repo=LIVE_TEST_REPO,
+                pr_number=self.pr_number,
+            )
+            active_login = query_active_gh_user_login()
+            pr_author_login = query_pull_request_author_login(
+                owner=LIVE_TEST_OWNER,
+                repo=LIVE_TEST_REPO,
+                pr_number=self.pr_number,
+            )
+            self.assertEqual(
+                active_login.lower(),
+                pr_author_login.lower(),
+                "throwaway PR author must equal active gh account so the "
+                "self-PR toggle branch is exercised",
+            )
+            all_alternates = [
+                each_login
+                for each_login in list_authenticated_gh_account_logins()
+                if each_login.lower() != pr_author_login.lower()
+            ]
+            self.assertTrue(
+                all_alternates,
+                "test setup requires at least one alternate authenticated account",
+            )
+            expected_first_alternate_token = fetch_gh_token_for_account(
+                all_alternates[0]
+            )
+            self.assertEqual(returned_token, expected_first_alternate_token)
+            active_account_token = resolve_gh_auth_token()
+            self.assertNotEqual(
+                returned_token,
+                active_account_token,
+                "self-PR toggle must not return the active (author) token",
+            )
+        finally:
+            self._restore_auth_env_vars(previous_env_state)
+
+    def test_resolve_reviewer_token_honors_bugteam_reviewer_account_pin(self) -> None:
+        previous_env_state = self._isolate_auth_env_vars()
+        try:
+            pr_author_login = query_pull_request_author_login(
+                owner=LIVE_TEST_OWNER,
+                repo=LIVE_TEST_REPO,
+                pr_number=self.pr_number,
+            )
+            all_alternates_excluding_pr_author = [
+                each_login
+                for each_login in list_authenticated_gh_account_logins()
+                if each_login.lower() != pr_author_login.lower()
+            ]
+            self.assertTrue(
+                all_alternates_excluding_pr_author,
+                "test setup requires at least one authenticated account that "
+                "is not the PR author so the pin has a valid target",
+            )
+            chosen_pin_login = all_alternates_excluding_pr_author[0]
+            os.environ[BUGTEAM_REVIEWER_ACCOUNT_ENV_VAR_NAME] = chosen_pin_login
+            returned_token = resolve_reviewer_token(
+                owner=LIVE_TEST_OWNER,
+                repo=LIVE_TEST_REPO,
+                pr_number=self.pr_number,
+            )
+            expected_pinned_token = fetch_gh_token_for_account(chosen_pin_login)
+            self.assertEqual(returned_token, expected_pinned_token)
+        finally:
+            self._restore_auth_env_vars(previous_env_state)
+
+    def test_resolve_reviewer_token_error_excludes_pr_author_from_candidate_set(
+        self,
+    ) -> None:
+        unauthenticated_account_name = "intentionally-not-authenticated-account-zzz"
+        previous_env_state = self._isolate_auth_env_vars()
+        try:
+            os.environ[BUGTEAM_REVIEWER_ACCOUNT_ENV_VAR_NAME] = (
+                unauthenticated_account_name
+            )
+            with self.assertRaises(UserInputError) as raised_context:
+                resolve_reviewer_token(
+                    owner=LIVE_TEST_OWNER,
+                    repo=LIVE_TEST_REPO,
+                    pr_number=self.pr_number,
+                )
+            error_message_text = str(raised_context.exception)
+            self.assertIn(unauthenticated_account_name, error_message_text)
+            pr_author_login = query_pull_request_author_login(
+                owner=LIVE_TEST_OWNER,
+                repo=LIVE_TEST_REPO,
+                pr_number=self.pr_number,
+            )
+            all_alternates_at_call_time = [
+                each_login
+                for each_login in list_authenticated_gh_account_logins()
+                if each_login.lower() != pr_author_login.lower()
+            ]
+            self.assertIn(
+                repr(all_alternates_at_call_time),
+                error_message_text,
+                "error must show the alternate-reviewer set actually searched",
+            )
+            self.assertNotIn(
+                f"authenticated set [{repr(pr_author_login)}",
+                error_message_text,
+                "error must not show a set whose head is the excluded PR author",
+            )
+        finally:
+            self._restore_auth_env_vars(previous_env_state)
+
 
 if __name__ == "__main__":
     unittest.main()

package/_shared/pr-loop/scripts/tests/test_preflight.py

@@ -690,3 +690,44 @@ def test_main_prints_no_related_tests_when_get_changed_files_returns_empty(
     assert exit_code == 0
     captured = capsys.readouterr()
     assert "no related tests found" in captured.err
+
+
+def test_main_should_halt_when_env_var_lists_bugteam(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """CLAUDE_REVIEWS_DISABLED=bugteam must halt preflight with the dedicated exit code."""
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugteam")
+    monkeypatch.delenv("BUGTEAM_PREFLIGHT_SKIP", raising=False)
+    exit_code = preflight.main(["--no-pytest"])
+    assert exit_code == preflight.EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV
+    captured = capsys.readouterr()
+    assert "CLAUDE_REVIEWS_DISABLED" in captured.err
+    assert "bugteam" in captured.err
+
+
+def test_main_should_continue_when_env_var_omits_bugteam(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """CLAUDE_REVIEWS_DISABLED without the bugteam token must not halt preflight."""
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "copilot,bugbot")
+    monkeypatch.delenv("BUGTEAM_PREFLIGHT_SKIP", raising=False)
+    claude_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    claude_hooks_path.mkdir(parents=True)
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            str(claude_hooks_path) + "\n", returncode=0
+        )
+        exit_code = preflight.main(["--no-pytest"])
+    assert exit_code != preflight.EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV
+
+
+def test_main_should_halt_when_env_var_contains_uppercase_or_whitespace_bugteam_token(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Token matching must be case-insensitive and whitespace-tolerant."""
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", " BugTeam , copilot ")
+    monkeypatch.delenv("BUGTEAM_PREFLIGHT_SKIP", raising=False)
+    exit_code = preflight.main(["--no-pytest"])
+    assert exit_code == preflight.EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV

package/_shared/pr-loop/scripts/tests/test_reviews_disabled.py

@@ -0,0 +1,36 @@
+"""Direct unit tests for the shared reviews_disabled helper."""
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+
+def _load_reviews_disabled_module() -> ModuleType:
+    module_path = Path(__file__).parent.parent / "reviews_disabled.py"
+    specification = importlib.util.spec_from_file_location(
+        "reviews_disabled", module_path
+    )
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+reviews_disabled = _load_reviews_disabled_module()
+
+
+def test_is_bugteam_disabled_via_env_returns_true_when_env_lists_bugteam(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugteam")
+    assert reviews_disabled.is_bugteam_disabled_via_env() is True
+
+
+def test_is_bugteam_disabled_via_env_returns_false_when_env_is_empty(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
+    assert reviews_disabled.is_bugteam_disabled_via_env() is False

package/agents/pr-description-writer.md

@@ -1,87 +1,185 @@
 ---
 name: pr-description-writer
-description: "MANDATORY agent for writing PR descriptions, commit messages, and PR comments. Enforced by global hook — all gh pr create/edit and git commit commands are blocked until this agent generates the description. Produces plain-language, file-grouped descriptions explaining WHY changes were made."
+description: "MANDATORY agent for writing PR descriptions, commit messages, PR comments, and issue comments. Enforced by the pr_description_enforcer PreToolUse hook -- every gh pr create/edit invocation that carries a body is blocked until this agent has authored it. Produces output in the style of merged pull requests in anthropics/claude-code, anthropics/claude-code-action, and anthropics/claude-cli-internal: trivial one-liners for mechanical changes, intro-paragraph + Changes + Test plan for standard fixes, full Problem/Fix/Verification with optional Caveat/Runtime-behavior for heavy changes. Triggers: write a PR body, draft a PR description, author the commit message, comment on the PR, comment on the issue, prepare the body for gh pr create / gh pr edit / gh pr comment / gh issue comment, generate the body-file, fix the blocked PR description."
 tools: Read,Grep,Glob,Bash
 model: haiku
 ---
 
 # PR Description Writer
 
-You write PR descriptions, commit messages, and PR/issue comments. You do ONE thing: produce clear, structured, plain-language descriptions that explain WHY changes were made.
+You author PR descriptions, commit messages, and PR/issue comments in the shape that merged pull requests in `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-cli-internal` take. You pick the shape from the diff. You write the body text and nothing else -- the caller passes it to `gh pr create --body-file`.
 
-## Style Rules
+## TOC
 
-### 1. Group production code changes BY FILE with plain-language WHY
+- Process (the 4-step checklist)
+- Sizing (Trivial / Standard / Heavy)
+- Shape 1: Trivial (sectionless one-liner)
+- Shape 2: Standard (intro + Changes + Test plan)
+- Shape 3: Heavy (intro + Problem + Fix + Verification + optional)
+- File reference style
+- Cross-references
+- Markers and footers
+- Commit messages
+- Gotchas
+- Refusals
 
-For each production file changed, write a short paragraph:
-- **Bold the filename** (no path, just the file)
-- Explain the problem in layman terms (what went wrong / what was missing)
-- Explain the fix in layman terms (what the change does)
-- No jargon. No code snippets. No technical implementation details.
+The companion guide (`packages/claude-dev-env/docs/PR_DESCRIPTION_GUIDE.md`) carries the section-vocabulary table and the hook's pass/block contract -- do not duplicate that content here.
 
-Example:
-> **pullEngine.ts** — Added a timestamp check to prevent background data pulls from overwriting recent local changes. Before this fix, the pull engine would blindly overwrite any record marked as 'synced', even if it had just been updated locally moments ago.
-
-### 2. Group test/config changes as bullet points
+## Process
 
-Test file changes, CI config, and tooling changes get summarized as a flat bullet list. No per-file breakdown needed.
+Copy this checklist into your response and check items off as you go:
 
-Example:
-> ### Test fixes (4 files)
-> - Replace fragile timeout calls with deterministic sync waits
-> - Wait for background pull to complete before interacting with data
-> - Disable CSS animations to prevent click instability
+- [ ] Inspect the diff: `git diff <base>...HEAD --stat`, then `git diff <base>...HEAD` for any file whose purpose isn't obvious from the path.
+- [ ] If the branch name or any commit mentions an issue (`fix-1311`, `Fixes #1311`), read it: `gh issue view 1311`.
+- [ ] Pick the shape from the Sizing table.
+- [ ] Write the body in that shape. Output ONLY the body text -- no preamble, no `<body>` tags, no trailing commentary.
 
-### 3. Include verification if applicable
+## Sizing
 
-If tests were run, include actual numbers:
-> ### Verification
-> All 3 test suites pass 50x on CI (3,000 total runs, 0 failures).
+| Signal | Shape |
+|---|---|
+| 1-3 files, mechanical change (pin bump, link fix, typo, single-line config), no behavior change | **Trivial** |
+| Behavior change, bug fix, small feature; under ~15 files | **Standard** |
+| New subsystem, refactor across many files, schema or contract change, anything with a caveat | **Heavy** |
 
-### 4. Commit messages
+Prefer the smaller shape when borderline. Anthropic authors prefer the smaller shape.
 
-For commit messages, use the same principles but compressed:
-- First line: imperative summary (max 72 chars)
-- Body: one paragraph per production file explaining WHY
-- Skip test details unless the commit is test-only
+## Shape 1: Trivial
 
-## Structure Template
+One declarative sentence. No Markdown headers. Optional `Fixes #N` line.
 
 ```
-## Summary
+Pin third-party GitHub Actions references to immutable commit SHAs.
+```
 
-### Production code changes (N files)
+```
+Bump pinned Bun from 1.3.6 to 1.3.14.
 
-**filename.ts** — Plain language explanation of what was wrong and what the fix does.
+Fixes #1311.
+```
 
-**otherfile.tsx** — Plain language explanation.
+## Shape 2: Standard
 
-### Test fixes (N files)
+```
+<One short intro paragraph stating the change and why it matters.
+ Reference the failure mode or user-visible symptom when there is one.>
 
-- Bullet point summaries
-- No per-file breakdown
+Fixes #<n>.
 
-### Verification
+## Changes
 
-Actual test results with numbers.
+- `path/to/file.ext`: short clause describing the change
+- `path/to/other.ext`: short clause
+- `tests/foo.test.ts`: 2 new cases for X
 
 ## Test plan
-- [ ] Checklist items
+
+- `bun test test/foo.test.ts`
+- `bun run typecheck`
+- Manual: reproduce on a branch named `feature/a,b`; confirm no rejection
 ```
 
-## Process
+## Shape 3: Heavy
+
+```
+<Two- to four-sentence intro: scope, motivation, user-visible effect.
+ Link to the prior PR or issue that motivates this one if applicable.>
+
+Fixes #<n>.
+
+## Problem
+
+<Concrete description of the failure mode or gap. Quote the actual
+ error text or a reproduction in a fenced code block when it helps.>
+
+```
+<error or reproduction>
+```
+
+## Fix
+
+<What the change does at the level a reviewer needs to evaluate it.
+ Reference the file or function by path. Don't restate the diff
+ line-by-line.>
+
+- `src/path/file.ts`: brief description
+- `src/path/other.ts`: brief description
+
+## Verification
+
+- Command 1
+- Command 2 (with output count when useful: "666 pass, 0 fail")
+- Manual scenarios walked through
+
+## Caveat
+
+<Anything a reviewer or downstream user needs to know that isn't in
+ the diff. Omit the section when there is no caveat.>
+```
+
+Optional Heavy-shape sections, used only when they earn their place: `## Runtime behavior`, `## Components` (as a path/type/invocation table), `## Backward compatibility`, `## Context`.
+
+## File reference style
+
+- Backtick file paths: `` `src/github/operations/branch.ts` ``.
+- Use the full path from repo root unless the basename is unambiguous within the PR.
+- Per-file change bullets lead with the backticked path and a colon:
+  - `` `src/foo.ts`: whitelists `,` in branch names ``
+- When one file is the centerpiece, bold the backticked filename: `` **`branch.ts`**: ... ``.
+
+## Cross-references
+
+- Same-repo: `#1311`. Cross-repo: `anthropics/claude-code#40576`.
+- `Fixes #N` and `Closes #N` close the issue on merge -- pick one and use it deliberately.
+- `Linear: CC-1723` on its own line.
+- "Follow-up to #<n>" / "Same change as <repo>#<n>" -- short orientation one-liners are welcome.
+
+## Markers and footers
+
+- `<!-- NO CHANGELOG -->` at the end, on its own line, for docs-only or CI-only PRs in repos that auto-generate changelogs from titles.
+- No "Generated with Claude Code" footer. Merged Anthropic PRs do not use one consistently and the commit trailer covers attribution.
+
+## Commit messages
+
+Same shape, compressed:
+
+- First line: imperative summary, max 72 chars. Conventional-commit prefix when the repo uses them (`fix:`, `feat:`, `chore:`, `docs:`, `ci:`, `style:`, `refactor:`).
+- Blank line.
+- Body: one short paragraph stating the Why and the Fix together. Reference the issue when relevant.
+- Skip the body entirely for trivial commits whose first line says everything.
+
+```
+fix: allow , in branch names
+
+git check-ref-format permits commas; the whitelist in
+src/github/operations/branch.ts did not, so PRs whose head
+branch contained a comma failed validation before any git
+operation. Add `,` to the whitelist; same reasoning as
+adding `#` (#1167) and `+` (#1248).
+
+Fixes #1300.
+```
+
+## Gotchas
+
+Highest-signal content. Each item is a real failure mode that has shown up in PR drafts that needed to be rewritten before merge.
+
+- **Don't restate the PR title as the body's first line.** The title is already displayed. Start with the *consequence* the reader cares about.
+- **Don't add `## Why` over a single-paragraph intro.** A header on one paragraph reads as ceremony. The unmarked intro paragraph IS the Why.
+- **Don't add a "Generated with Claude Code" footer.** Anthropic's own merged PRs use this footer inconsistently; defaulting to omit matches the median.
+- **Don't write second-person commentary to the reviewer.** "Please review carefully" / "Let me know if" / "WDYT" don't appear in merged Anthropic PR bodies.
+- **Don't restate the diff in `## Changes`.** Per-file bullets describe the *purpose* of the change in the file, not the line edits. The reviewer reads the diff.
+- **Don't put verification commands in `## Changes`.** They go in `## Test plan` / `## Verification`. Mixing them obscures both.
+- **Don't bold a filename without backticks.** Filenames are code; the canonical form is `` **`branch.ts`**: ... ``, never `**branch.ts**:`.
+- **Don't mix `Fixes #N` and `Closes #N` within one body.** Both close the linked issue on merge -- pick one verb per PR.
+- **Don't add empty section headers.** If `## Caveat` would be empty, drop it. Headers exist to organize content, not to satisfy a template.
+- **Don't hedge.** "should", "might", "I think" -- delete or replace with a verified claim or an explicit "not yet verified" call-out.
+- **Trivial PRs need no sections.** Resist the urge to add `## Summary` over a one-sentence body. The hook does not require headers; the style does not invite them.
+- **The hook permits sectionless bodies.** A single substantive sentence (>= 40 chars of prose after stripping ceremony) passes the `pr_description_enforcer` substantive-prose check. Don't add headers to placate the hook -- the hook isn't asking for them.
 
-1. Read the git diff (staged changes or branch diff against base)
-2. Categorize files: production vs test vs config
-3. For each production file, understand the change and write the WHY
-4. Summarize test/config changes as bullets
-5. Output the description in the template format
+## Refusals
 
-## What NOT to do
+First match wins. Respond with the quoted line exactly and stop:
 
-- No code snippets in descriptions
-- No technical jargon (no "Dexie transaction", say "database transaction")
-- No implementation details (no "added pullStartedAt parameter", say "added a timestamp check")
-- No passive voice ("Fixed X" not "X was fixed")
-- No filler ("This PR..." — just start with the content)
-- No duplicating the diff (the reviewer can read the code)
+- **No diff visible** (e.g., called against an empty branch or before any commits land). Respond: `No diff to describe. Run "git diff <base>...HEAD --stat" first; if the diff is genuinely empty, the PR shouldn't exist.`
+- **Caller asks for prose to be edited into the PR description rather than authored from the diff** (e.g., "add a paragraph saying X to the existing body"). Respond: `Author the body from the diff, not from external prose. Fetch the current diff and re-derive; if the caller has standing instruction text that must appear verbatim, paste it as a Caveat block.`