PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

• Decision: Approve
• Rationale: Correct, complete-per-AC, backward-compatible context-efficiency feature with a Contract-Ledger-matching diff and verified tests. Not Approve+Follow-Up — the one adoption nudge I'd suggest (pointing backlog-scan workflows at projection:'title') is already covered by the tool-description guidance, so there's no required residual. No blocking findings.

Peer-Review Opening: Nice, tightly-scoped MX-loop win — agents can now title-scan the backlog without burning context on bodies, and the fail-fast invalid-projection guard + default-full backward-compat are exactly right. Checked it out and ran the spec; clean. Approving.

🧭 Patch-Blind Premise Snapshot

• Inputs Read Before Patch: #12706 (close-target + its Contract Ledger Matrix + ACs), the 4-file diff, current dev IssueService.listIssues + issueQueries.mjs + openapi.yaml, the existing IssueService.spec.mjs stub pattern, and a local checkout + spec run.
• Expected Solution Shape: An optional projection param on list_issues/IssueService.listIssues, defaulting to full (zero behavior change for existing callers), applied after the label/assignee filters, omitting body for lean shapes while preserving triage metadata, with an invalid-value guard and unit coverage for default + lean + invalid. Must NOT break the existing full-response shape.
• Patch Verdict: Matches the expected shape precisely. Projection is applied post-filter / pre-return (projectListedIssue), default full returns the issue untouched, invalid values reject before GraphQL fires, and updatedAt is added coherently across query + schema + summary output. Diff matches the Contract Ledger row-for-row.

🕸️ Context & Graph Linking

• Target Epic / Issue ID: Resolves #12706
• Related Graph Nodes: IssueService.listIssues, github-workflow/openapi.yaml /issues, post-review-pickup / mailbox self-survey (intended consumer per ledger row 3), #12696 (release umbrella)

🔬 Depth Floor

Challenge: Two non-blocking observations. (1) Wire-fetch vs. projection: FETCH_ISSUES_LIST still requests body (and now updatedAt) even for title/summary, with the trim happening client-side. The stated goal — saving the agent's context — is fully met (the MCP response omits body); but the GitHub API still transfers bodies over the wire. Keeping one query shape is simpler/cacheable, so this is a fine trade-off — just flagging that the win is context-side, not bandwidth-side, in case a future query-level projection is wanted. (2) Adoption: the capability exists, but its value depends on agents actually invoking projection:'title' during backlog self-surveys (ledger row 3's intent). The tool description guides this, so it's covered — a workflow-doc nudge would be a marginal future enhancement, not a residual.

Rhetorical-Drift Audit:

• PR description: framing matches the diff (modest, accurate — "lean projection contract", no overshoot).
• Anchor & Echo: the two new methods carry precise @summary JSDoc; the title_only→title alias rationale is accurate and useful.
• Drift-reducing (positive): the PR removes decay-prone ticket archaeology from durable @summary/comment prose (#10272 Phase 1, Pre-#11537, empirical anchor: PR #11245…) while correctly keeping the load-bearing @see discussion link and the describe-title ticket anchors — exactly the durable-prose-vs-traceability discrimination the repo convention wants.

Findings: Pass — accurate framing; the JSDoc cleanup improves drift posture.

🧠 Graph Ingestion Notes

• [TOOLING_GAP]: A freshly-created worktree can have zero hydrated ai/mcp/server/*/config.mjs, so a local unit run fails the whole IssueService.spec.mjs with Cannot find module …/config.mjs (13 false failures spanning untouched pre-existing tests) — a false-negative that looks like a code break. Hydrating via the exported bootstrapWorktree({mainCheckout, projectRoot}) (config-only, skips build-all) → 40/40 pass. Worth a one-liner in the unit-test/worktree onboarding docs: hydrate configs before running specs in a new worktree.
• [RETROSPECTIVE]: Clean pattern for response-shape projection — normalize+validate the projection key first (fail-fast before the network), then apply a pure post-filter transform with full as identity. Easy to extend to other list endpoints.

🎯 Close-Target Audit

• Close-targets identified: #12706
• #12706 confirmed not epic-labeled (labels: enhancement, ai, architecture, model-experience)

Findings: Pass.

📑 Contract Completeness Audit

• Originating ticket #12706 contains a ## Contract Ledger Matrix (3 rows: MCP tool / IssueService.listIssues / agent backlog-scan workflow)
• Implemented diff matches the ledger: projection param + default full + post-filter placement + invalid-rejection + body-omission-with-triage-fields + reproduce command (projection:'title') all present and accurate

Findings: Pass — ledger present and diff conforms.

🪜 Evidence Audit

• PR body contains an Evidence: line: L2 (targeted unit coverage + OpenAPI/tool-registration compatibility) → L2 required (service contract + MCP schema change)
• Achieved (L2) ≥ required (L2)
• Residual explicitly listed in ## Post-Merge Validation: stale MCP server processes need restart before already-running clients expose projection (accurate — the live list_issues schema won't show the param until the server restarts)
• No evidence-class inflation — L2 framed as L2

Findings: Pass.

📡 MCP-Tool-Description Budget Audit

• Added text describes call-site usage (when-to-use title vs full) — no architectural narrative
• No internal cross-refs (no ticket numbers / session IDs / memory anchors) in the description payload
• projection param description is single-line, enum-documented, default stated
• 1024-char cap respected (CI check + McpServerToolLimits green)

Findings: Pass.

🔗 Cross-Skill Integration Audit

• New MCP param documented in the tool's openapi.yaml description ✓
• Non-blocking consideration: ledger row 3 frames the consumer as "AGENTS.md mailbox/post-pickup self-survey behavior." No workflow-doc was updated to tell agents to prefer projection:'title' for those scans. The tool description covers discovery, so this isn't a gap — but a one-line nudge in the backlog-scan workflow would maximize adoption. Optional follow-up, not a merge condition.

Findings: No blocking gaps; one optional adoption nudge noted.

🧪 Test-Execution & Location Audit

• Branch checked out locally (gh pr checkout 12721)
• Canonical location: test/playwright/unit/ai/services/github-workflow/IssueService.spec.mjs — correct per unit-test.md
• Ran the spec: 40/40 passed (2.4s) after hydrating worktree configs (initial 13 failures were the missing-config env gap, not code — they hit untouched pre-existing tests identically; CI unit job green corroborates)
• New code has new tests: 4 projection tests (default-full, summary, title_only, invalid-rejected-before-GraphQL)

Findings: Tests pass; location correct; coverage proportionate.

📋 Required Actions

No required actions — eligible for human merge.

(Optional, non-blocking: consider a future query-level projection if API bandwidth — not just agent context — becomes a concern; and a one-line backlog-scan-workflow nudge toward projection:'title' for adoption.)

📊 Evaluation Metrics

• [ARCH_ALIGNMENT]: 90 — projection-after-filter with full as identity, fail-fast guard, coherent updatedAt across query/schema/output, fully backward-compatible. Client-side trim leaves wire-fetch unoptimized (acceptable trade-off).
• [CONTENT_COMPLETENESS]: 92 — Contract Ledger present and matched; openapi + JSDoc + query + tests all updated coherently. (## Test Evidence body section is empty — minor.)
• [EXECUTION_QUALITY]: 95 — verified 40/40 locally + CI green; clean code; correct durable-prose-archaeology discrimination.
• [PRODUCTIVITY]: 88 — focused, well-scoped diff shipping a real context-efficiency win.
• [IMPACT]: 80 — directly serves the MX-loop / agent context-efficiency; broad consumer base (every agent doing a backlog self-survey).
• [COMPLEXITY]: 35 — modest pure-transform + guard; low regression risk.
• [EFFORT_PROFILE]: Quick Win — small, well-tested, high-leverage.

Clean merge once a human picks it up. Thanks for the tidy ledger and the JSDoc hygiene pass along the way.