[Phase 1] Author the LSP pilot scoping doc — language, actions, SLA, metrics, cost cap, candidate shortlist

Story

As a pr-review pilot owner,
I want a single scoping doc that fixes the LSP pilot's target language, the specific agent actions it covers, the cold-start SLA, the success metrics, the cost cap, and the candidate-server shortlist,
so that the downstream wiring and measurement stories share one unambiguous, agreed definition of done instead of each re-deciding scope.

Acceptance Criteria

A new docs/lsp-pilot.md exists and names the pilot's target language (Shell) and pilot repo (.github-private), with the rationale tied to the discussion (agent's own substrate; lightweight bash-language-server).
The doc enumerates the specific pr-review actions LSP is scoped to (finding-verification via find-references / diagnostics in the deep/audit tiers) and explicitly states LSP is NOT applied to triage or to dev-lead code-writing in this pilot.
The doc states a concrete cold-start SLA (<=30s P95) and the graceful-degradation rule: if cold-start exceeds the SLA the LSP step is auto-skipped, never a workflow failure.
The doc records the initiative success metric (navigation-token reduction target AND no review-quality regression vs the frozen baseline) and the run-count cost cap, consistent with the epic body.
The doc lists the candidate LSP-MCP servers to compare (agent-lsp, Serena, lsp-mcp) with pinned versions, and states that final selection is decided by the comparative pilot, not pre-chosen.

Tasks / Subtasks

Draft docs/lsp-pilot.md sections: scope (language/repo/tier), in/out-of-scope actions, SLA + auto-skip policy. (AC: test issue from agent #1, Go-live improvements for PR review agent #2, Add @claude delegation, auto-merge, and rebase handling #3)
Transcribe the success metric and cost cap from the epic body so doc and epic stay one source of truth. (AC: Optimize review: small-PR and incremental fast paths #4)
List candidate servers with pinned versions and the 'selection decided by data' rule; cross-link the existing MCP plumbing in engine.sh and mcp-powered-review.md. (AC: feat: add Copilot engine support via REVIEW_ENGINE toggle #5)

Dev Notes

This doc is the contract every later story grounds in — keep it tight and decision-dense, not a vendor survey.
Reuse, do not re-describe, the existing MCP mechanism: scripts/engine.sh already threads --mcp-config --strict-mcp-config into the deep + rubber-duck tiers via REVIEW_MCP_CONFIG/REVIEW_MCP_ALLOWED_TOOLS, and graceful degradation already emits a ::warning:: on MCP connect/init failure. The SLA auto-skip is an addition layered on that, not a replacement.
Mirror the structure of the enhancement comment's suggested scoping doc (docs/lsp-pilot.md) so reviewers can map ACs to the discussion 1:1.
Testing: docs-only story — verify links resolve and that the success metric / cost cap text is byte-consistent with the epic body; no shell to shellcheck.

Project Structure Notes

New file under the existing docs/ tree alongside docs/initiatives/mcp-powered-review.md; no script or workflow changes.

References

scripts/engine.sh
docs/initiatives/mcp-powered-review.md
.github/review-mcp.json
.github/workflows/pr-review.yml

Likely target surface

docs/lsp-pilot.md (new file)

Story prepared by the BMAD Scrum Master (Bob) for epic #839. Status: ready-for-dev.

Dev-Lead Implementation Plan

Issue: #840 — [Phase 1] Author the LSP pilot scoping doc — language, actions, SLA, metrics, cost cap, candidate shortlist

Scope

Author a single decision-dense scoping doc docs/lsp-pilot.md that fixes the LSP pilot's language/repo/tier, in/out-of-scope pr-review actions, the cold-start SLA + auto-skip rule, the success metric, the run-count cost cap (byte-consistent with epic #839), and the pinned candidate-server shortlist with a "selection decided by data" rule.

Implementation Checklist

Create docs/lsp-pilot.md with sections mapping 1:1 to the five ACs:
- Scope: language=Shell, repo=.github-private, tier=deep/audit + rationale (AC test issue from agent #1)
- In-scope actions (finding-verification via find-references / diagnostics) + explicit out-of-scope (triage, dev-lead code-writing) (AC Go-live improvements for PR review agent #2)
- Cold-start SLA (<=30s P95) + graceful auto-skip rule, layered on existing MCP degradation (AC Add @claude delegation, auto-merge, and rebase handling #3)
- Success metric (navigation-token reduction + no quality regression vs frozen baseline) + run-count cost cap, transcribed byte-for-byte from epic Initiative: Pilot LSP (language-server) code intelligence in the agent harness — pr-review Shell first, measured go/no-go #839 (AC Optimize review: small-PR and incremental fast paths #4)
- Candidate servers (agent-lsp, Serena, lsp-mcp) with version pinning rule + "selection decided by the comparative pilot" (AC feat: add Copilot engine support via REVIEW_ENGINE toggle #5)
- Cross-link existing MCP plumbing: scripts/engine.sh, docs/initiatives/mcp-powered-review.md, .github/review-mcp.json

Tests to Write

Docs-only story — TDD phase skipped per the prompt's documentation exception. Verification instead:
- bash .dev-lead/scripts/dev-lead-lint.sh passes (no shell/agent-frontmatter regressions)
- All intra-repo links in the new doc resolve to real paths
- Success-metric and cost-cap text is byte-consistent with the epic Initiative: Pilot LSP (language-server) code intelligence in the agent harness — pr-review Shell first, measured go/no-go #839 body

Test Command

bash .dev-lead/scripts/dev-lead-lint.sh

Dev-Lead: Implementation Complete

Plan Execution

Created docs/lsp-pilot.md (new file) with sections mapping 1:1 to the five ACs.
AC test issue from agent #1 — §1 fixes target language Shell + pilot repo .github-private + tier deep/audit, with rationale tied to the discussion (agent's own substrate; lightweight bash-language-server; finding-verification is the lowest-risk surface).
AC Go-live improvements for PR review agent #2 — §2 enumerates in-scope actions (finding-verification via find-references / diagnostics in deep/audit) and explicitly marks triage and dev-lead code-writing out of scope.
AC Add @claude delegation, auto-merge, and rebase handling #3 — §3 states the <=30s P95 cold-start SLA and the auto-skip rule (exceeding the SLA skips the LSP step, never fails the workflow), layered on the existing _emit_mcp_failure_warning degradation path.
AC Optimize review: small-PR and incremental fast paths #4 — §4 transcribes the success metric and cost cap verbatim from epic Initiative: Pilot LSP (language-server) code intelligence in the agent harness — pr-review Shell first, measured go/no-go #839 (verified byte-consistent, see below).
AC feat: add Copilot engine support via REVIEW_ENGINE toggle #5 — §5 lists the candidates (agent-lsp, Serena, lsp-mcp) + bash-language-server, with a version-pinning rule and a "selection decided by the comparative pilot ([Phase 3] Run the comparative pilot and render the speed/quality/cost report #844), not pre-chosen" statement.
§6 cross-links the existing MCP plumbing (scripts/engine.sh, docs/initiatives/mcp-powered-review.md, .github/review-mcp.json).

Test Results

Docs-only story — Phase 2 (TDD) skipped per the prompt's documentation exception (no observable behavioral change, no shell to test). Verification performed instead:

[lint] shellcheck on 67 file(s)...
[lint] validating 4 agent profile(s)...
OK: agents/agentic-workflows.md
OK: agents/compliance-auditor.md
OK: agents/feature-ideator.md
OK: agents/pr-reviewer.md
[lint] all checks passed

[links] all 6 intra-repo link targets resolve (CLAUDE.md, AGENTS.md,
        docs/initiatives/mcp-powered-review.md, scripts/engine.sh,
        .github/review-mcp.json, .github/workflows/pr-review.yml)

[byte-consistency vs epic #839]
=== METRIC: BYTE-CONSISTENT ===
=== COSTCAP: BYTE-CONSISTENT ===

Files Changed

docs/lsp-pilot.md: new scoping doc (the pilot contract) — language/repo/tier, in/out-of-scope actions, cold-start SLA + auto-skip, success metric + cost cap (verbatim from epic), candidate-server shortlist + pinning rule, and cross-links to the existing MCP plumbing.

Notes

Candidate version pins are intentionally not invented in this doc. Each candidate (and bash-language-server) is a third-party dependency; the exact pins are looked up from the source of truth and locked when the server is wired (story [Phase 2] Wire candidate LSP-MCP server(s) into the pr-review runtime — config, install, tier gating #842), consistent with the repo rule that pins are never guessed (CLAUDE.md/AGENTS.md) and the epic's own untracked-prerequisite that each must be pinned for a reproducible pilot. §5 records the pinning rule and a table ready to receive the locked versions in [Phase 2] Wire candidate LSP-MCP server(s) into the pr-review runtime — config, install, tier gating #842.
engine.sh threads MCP into the deep/audit (run_agentic) and rubber-duck (run_duck) tiers; the pilot scopes LSP use to the deep/audit finding-verification surface per the epic. §6 states this precisely rather than implying duck is excluded.
No script or workflow changes; no unrelated files touched. No follow-up issues needed — downstream stories [Phase 1] Freeze the comparative pilot PR corpus + immutable LSP-off baseline and build the metric-extraction harness #841–[Phase 2] Cache the LSP index and enforce the 30s cold-start SLA with auto-skip #846 already cover corpus/baseline, wiring, the verification step, the comparison, the go/no-go, and SLA/caching.

feat: implement issue #840 — [Phase 1] Author the LSP pilot scoping d…

Navigation Menu

Repository navigation

[Phase 1] Author the LSP pilot scoping doc — language, actions, SLA, metrics, cost cap, candidate shortlist #840

Story

Acceptance Criteria

Tasks / Subtasks

Dev Notes

Project Structure Notes

References

Likely target surface

Dev-Lead Implementation Plan

Scope

Implementation Checklist

Tests to Write

Test Command

Dev-Lead: Implementation Complete

Plan Execution

Test Results

Files Changed

Notes

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[Phase 1] Author the LSP pilot scoping doc — language, actions, SLA, metrics, cost cap, candidate shortlist #840

Description

Story

Acceptance Criteria

Tasks / Subtasks

Dev Notes

Project Structure Notes

References

Likely target surface

Activity

don-petry commented on Jun 20, 2026

Dev-Lead Implementation Plan

Scope

Implementation Checklist

Tests to Write

Test Command

don-petry commented on Jun 20, 2026

Dev-Lead: Implementation Complete

Plan Execution

Test Results

Files Changed

Notes

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions