./mfc.sh context: what to re-read to check a diff

.claude/CLAUDE.md

@@ -19,7 +19,7 @@ It holds policy and pointers only; facts live in the linked docs, and `./mfc.sh
     * Comments should be as short as possible without sacrificing value
     * GPU macros should follow the source's existing GPU macro principles and patterns
     * Functions/subroutines/modules shorter is better while being correct, fast, and separating concerns
-    * When a fix fails twice, stop and re-read in full the code you are changing, its callers and callees, and where each global it uses is set, before the next attempt. Repeated failures usually come from a detail remembered wrong
+    * When a fix fails twice, stop and re-read in full the code you are changing, its callers and callees, and where each global it uses is set, before the next attempt (`./mfc.sh context` lists them for your diff). Repeated failures usually come from a detail remembered wrong
 
 ## Where to look
 

.github/workflows/claude-code-review.yml

@@ -130,6 +130,24 @@ jobs:
           echo "review_diff_path=.claude-review/review.diff" >> "$GITHUB_OUTPUT"
           echo "changed_files_path=.claude-review/changed_files.txt" >> "$GITHUB_OUTPUT"
 
+      # Never the PR head: the tool from this trusted checkout analyzes a worktree of the PR's merge base, which is
+      # in the base branch's history, so the diff's old-side line numbers point at the code they came from and no PR
+      # code runs in this privileged job.
+      - name: What the diff touches beyond its hunks
+        continue-on-error: true
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          PR_NUMBER="${{ steps.mode.outputs.pr_number }}"
+          REPO="${{ github.repository }}"
+          BASE_REF="$(gh pr view "$PR_NUMBER" --repo "$REPO" --json baseRefName --jq .baseRefName)"
+          MERGE_BASE="$(gh api "repos/$REPO/compare/$BASE_REF...${{ steps.state.outputs.current_head_sha }}" --jq .merge_base_commit.sha)"
+          git worktree add --detach .claude-review/merge-base "$MERGE_BASE" > /dev/null
+          ./mfc.sh context --root .claude-review/merge-base --diff "${{ steps.review_input.outputs.review_diff_path }}" \
+            --expand base -o .claude-review/context.md > .claude-review/context.log 2>&1 || : > .claude-review/context.md
+          [ -s .claude-review/context.md ] || echo "::warning::./mfc.sh context produced no output; see .claude-review/context.log"
+
       - name: Prefetch bounded context for changed files only
         id: context
         shell: bash
@@ -203,7 +221,8 @@ jobs:
 
             Scope:
             - Read only these files: ./.claude/CLAUDE.md, ./docs/documentation/contributing.md,
-              ./docs/documentation/gpuParallelization.md, the prepared inputs above, and files inside the context directory.
+              ./docs/documentation/gpuParallelization.md, .claude-review/context.md, the prepared inputs above, and files
+              inside the context directory.
             - Every finding must be grounded in a changed hunk. Unchanged lines in changed files are context only.
             - Do not comment on code outside the changed files, and do not give general repo suggestions or style nitpicks.
 
@@ -215,7 +234,10 @@ jobs:
             4) For each changed Fortran or Python file that has a context file, open it and check each changed hunk against
                its surroundings: declarations, loop bounds, callers and callees within the file, comments that state what
                the code does, and the matching code paths in other directions, targets or branches.
-            5) Write .claude-review/output.md in the format below, then STOP. Do not post GitHub comments yourself.
+            5) Read .claude-review/context.md: what the diff touches beyond its hunks (Fypp-generated copies of changed
+               lines, call sites of changed macros, callers, callees, module variables set elsewhere). Check the diff
+               against it; findings must still be grounded in changed hunks.
+            6) Write .claude-review/output.md in the format below, then STOP. Do not post GitHub comments yourself.
 
             What to report: correctness bugs first (logic, numerics, array bounds, precision, memory, MPI, GPU macros,
             physics consistency, compiler portability), then code that contradicts its own comments or docs. Report a

toolchain/main.py

@@ -124,7 +124,7 @@ def __print_greeting():
 
 
 def __checks():
-    if ARG("command") == "viz":
+    if ARG("command") in ("viz", "context"):
         return
     if not does_command_exist("cmake"):
         raise MFCException("CMake is required to build MFC but couldn't be located on your system. Please ensure it installed and discoverable (e.g in your system's $PATH).")
@@ -162,6 +162,10 @@ def __run():
         from mfc import count
 
         count.count_diff()
+    elif cmd == "context":
+        from mfc import context
+
+        context.context()
     elif cmd == "clean":
         from mfc import clean
 
@@ -226,7 +230,8 @@ def __run():
         # Auto-regenerate completion scripts if source files changed
         __ensure_generated_files()
 
-        __print_greeting()
+        if ARG("command") != "context":  # its output is meant to be read or captured whole
+            __print_greeting()
         __checks()
         __run()
 

toolchain/mfc/cli/commands.py

@@ -903,6 +903,29 @@
     ],
 )
 
+CONTEXT_COMMAND = Command(
+    name="context",
+    help="List what to re-read to check a diff: changed routines and their Fypp copies, changed-macro call sites, callers, callees, and module variables set elsewhere.",
+    include_common=["targets"],
+    arguments=[
+        Argument(name="base", help="Diff the working tree against REV (default: the merge base with origin/master).", type=str, default=None, metavar="REV"),
+        Argument(name="diff", help="Read the diff from FILE instead of running git diff.", type=str, default=None, metavar="FILE"),
+        Argument(name="output", short="o", help="Write the report to FILE instead of standard output.", type=str, default=None, metavar="FILE"),
+        Argument(name="root", help="Analyze the source tree at DIR instead of this checkout (CI: a worktree of the PR's merge base).", type=str, default=None, metavar="DIR"),
+        Argument(
+            name="expand",
+            help="worktree: expand the working tree and map the diff's new side. base: expand the checked-out base and map the old side (CI).",
+            type=str,
+            default="worktree",
+            choices=["worktree", "base"],
+        ),
+    ],
+    examples=[
+        Example("./mfc.sh context", "What to re-read for this branch's changes"),
+        Example("./mfc.sh context --base HEAD", "Only uncommitted changes"),
+    ],
+)
+
 FP_STABILITY_COMMAND = Command(
     name="fp-stability",
     help="Run floating-point stability tests using Verrou.",
@@ -1474,6 +1497,7 @@
         BENCH_DIFF_COMMAND,
         COUNT_COMMAND,
         COUNT_DIFF_COMMAND,
+        CONTEXT_COMMAND,
         FP_STABILITY_COMMAND,
     ],
     common_sets=[