Review bot false positives on docs/spec PRs from markdown code samples #53

Summary

The PR review bot posts correctness findings on docs/spec PRs by treating fenced TypeScript snippets in markdown as implementation code, which leads to false positives and occasional wrong file attribution.

Repro Context (baseline)

• PR: docs: align runtime specs with consolidated runtime APIs #52
• PR URL: docs: align runtime specs with consolidated runtime APIs #52
• Branch: docs/runtime-spec-alignment
• Head commit: 0eca22e02bd43a14ed3eff26428f68c4ff868db5
• Review comment: docs: align runtime specs with consolidated runtime APIs #52 (comment)
• Workflow run (PR Review): https://github.com/taras/executable-markdown-agents/actions/runs/23250893379

Observed Behavior

The review comment reports correctness findings against runtime/apis.ts:

• "Duplicate const runtime = { ... }; assignments..."
• "Redundant const readTextFile = API.Fs.operations.readTextFile;..."
• "createExecFactory function appears to forward calls..."

But PR #52 changed only docs/spec files:

• durable-effects/README.md
• durable-effects/specs/effect-types.md
• durable-streams/README.md
• specs/executable-mdx-spec.md

This suggests the policy is analyzing markdown code samples as if they were production TS, and/or misattributing findings to non-changed files.

Likely Source

• .reviews/policies/ExtraneousCodePolicy.md currently runs for pr.stats.totalChanges > 20 and frames the pass as a TypeScript PR review over diff preview text.

Expected Behavior

• Docs/spec-only PRs should not emit TS-correctness findings from fenced examples.
• File attribution should be restricted to changed files and real code paths only.

Suggested Fix Directions

• Add docs/spec-aware gating (skip or reduce correctness heuristics for markdown-only diffs).
• Exclude fenced code blocks in markdown from dead-code/wrapper heuristics.
• Validate findings against changed file list before posting comments.

Replay / Compare

Re-run the PR Review workflow on commit 0eca22e02bd43a14ed3eff26428f68c4ff868db5 and compare produced comment output against the linked baseline comment.

Note: output may drift if prompts/templates/workflow changed since baseline run.