fix: review process and cleanup

mcp/checkout.ts

@@ -486,13 +486,19 @@ export function CheckoutPrTool(ctx: ToolContext) {
       commitLogUnavailable,
       hookWarning: checkoutResult.hookWarning,
       instructions:
-        `the diff file at diffPath contains a table of contents (TOC) listing every changed file with its line range. ` +
-        `use the read_file MCP tool to read sections of it. ` +
-        `for example, if the TOC says "src/foo.ts → lines 5-42", call: read_file({ path: diffPath, start_line: 5, end_line: 42 }). ` +
+        `the diff file at diffPath contains a table of contents (TOC) followed by the formatted diff for each file. ` +
+        `use read_file to read sections: if the TOC says "src/foo.ts → lines 5-42", call read_file({ path: diffPath, start_line: 5, end_line: 42 }). ` +
+        `IMPORTANT — two different sets of line numbers appear in the diff, do not confuse them: ` +
+        `(1) TOC line numbers like "lines 5-42" — these are DIFF-FILE positions for read_file calls only. ` +
+        `(2) Source file line numbers — inside each file's diff content, every line is prefixed "| oldLine | newLine | type | code". ` +
+        `These oldLine/newLine values are the ACTUAL file line numbers to use in create_pull_request_review comments. ` +
+        `For inline comments: path = the source file path from the "diff --git a/<path> b/<path>" header (e.g. "apps/foo/bar.ts"), NOT the diffPath. ` +
+        `line = the newLine column value for RIGHT-side (added/context lines), or oldLine for LEFT-side (removed lines). ` +
         `IMPORTANT: to inspect the PR's changed files, read diffPath directly — ` +
         `do NOT run git diff or git show. The PR base branch is '${pr.baseRef}', NOT necessarily 'main' — ` +
         `if you must use git, use 'origin/${pr.baseRef}' as the base (e.g. git log origin/${pr.baseRef}..HEAD), ` +
         `but prefer diffPath for all diff analysis. ` +
+        `PHANTOM ISSUES: the diff only shows what changed, not the entire file. Before reporting an issue, verify it is caused by lines marked "+" in the diff (new code). Do not flag issues in pre-existing code unless the PR directly introduced or amplified the problem. ` +
         (incrementalDiffPath
           ? ` IMPORTANT: read incrementalDiffPath FIRST to understand what changed since last review, then use diffPath for full context.`
           : "") +

mcp/review.ts

@@ -212,6 +212,8 @@ export function CreatePullRequestReviewTool(ctx: ToolContext) {
       "code block showing the corrected code. For example: " +
       "'SQL injection: id is interpolated directly into the query string.\\n\\n```ts\\nconst result = await db.query(\\'SELECT * FROM users WHERE id = $1\\', [id]);\\n```'. " +
       "The first submission may error once with a diff-coverage nudge — retry with the same arguments. " +
+      "Inline comments: 'path' must be the SOURCE FILE path (e.g. 'apps/foo/bar.ts') from the diff --git header, NOT the diffPath returned by checkout_pr. " +
+      "'line' must be the actual file line number from the '| newLine |' column in the formatted diff (not the TOC line range). " +
       "Inline comments can ONLY target files and lines that appear in the PR diff.",
     parameters: CreatePullRequestReview,
     execute: execute(async ({ pull_number, body, approved, commit_id, comments = [] }) => {