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

[don-petry]

Closes #840

Implemented by dev-lead agent. Please review.

Summary by CodeRabbit

• Documentation
  • Added documentation outlining the LSP pilot program, including defined scope, performance targets (30-second cold-start SLA), success metrics, implementation boundaries, and candidate server details for the language server pilot initiative.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds docs/lsp-pilot.md as a new scoping contract document for the LSP pilot. The file defines target scope (Shell/bash, .github-private, deep/audit tiers), in/out-of-scope agent actions, a cold-start SLA (≤30s P95) with auto-skip degradation, success metrics, cost caps, a candidate server shortlist with version-pinning rules, and how the pilot reuses existing MCP plumbing.

Changes

LSP Pilot Scoping Document

Layer / File(s)	Summary
Pilot contract header, scope, and in/out-of-scope actions docs/lsp-pilot.md	Introduces the doc's status/metadata, defines scope dimensions (Shell/bash target, .github-private repo, pr-review surface, deep/audit-only tiers), enumerates in-scope finding-verification actions via LSP find-references and publishDiagnostics, and explicitly excludes triage tier and dev-lead code writing.
Cold-start SLA, success metric, and cost cap docs/lsp-pilot.md	Sets the LSP cold-start SLA (≤30s P95) with a graceful-degradation/auto-skip rule layered on existing MCP failure handling, transcribes the initiative success metric (navigation-token reduction with no precision regression), and defines the cost cap via deep/audit gating and bounded run counts.
Candidate server shortlist and version-pinning rule docs/lsp-pilot.md	Lists candidate LSP-MCP servers (agent-lsp, Serena, lsp-mcp), specifies the comparative selection rule on a frozen corpus constrained to at most two servers, and requires exact version pins for all third-party dependencies and bash-language-server locked at wiring time.
MCP plumbing reuse, new additions, and references docs/lsp-pilot.md	Documents reuse of existing MCP tier gating/config threading and failure annotations, enumerates what is new (LSP cold-start SLA, index-caching, auto-skip, finding-verification step), and provides the references list of epics, stories, scripts, config, and workflow files.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related issues

• #839 — The epic body is the direct upstream source for the success metric, cost cap, and candidate server shortlist transcribed into this doc, making it the parent initiative this PR closes out the Phase 1 scoping story for.
• #840 — This PR directly implements all acceptance criteria of this story: docs/lsp-pilot.md exists with target language/repo rationale, in/out-of-scope actions, cold-start SLA with auto-skip rule, success metric with cost cap, and candidate server shortlist with pinned versions.

Suggested labels

needs-human-review

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: authoring an LSP pilot scoping document with defined language, actions, SLA, metrics, cost cap, and candidate shortlist.
Linked Issues check	✅ Passed	The pull request fully satisfies all five acceptance criteria from issue #840: creates docs/lsp-pilot.md with target language/repo/rationale, enumerates in/out-of-scope actions, defines SLA with auto-skip policy, records success metrics and cost cap, and lists candidate servers with pinned versions.
Out of Scope Changes check	✅ Passed	The pull request contains only the single scoped deliverable: a documentation file (docs/lsp-pilot.md) with no extraneous changes, script modifications, or workflow alterations.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev-lead/issue-840-20260620-2135

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive scoping document (docs/lsp-pilot.md) for piloting Language Server Protocol (LSP) code intelligence as MCP tools. The document defines the target language (Shell), operational SLAs, success metrics, and candidate servers. The review feedback suggests improving consistency in the candidate comparison and version-pinning tables by adding the specific repository paths and links for the lsp-mcp candidate.

[don-petry]

Dev-Lead — review-changes (applied)

Changes committed and pushed.

[don-petry]

Dev-Lead — review-changes (applied)

Changes committed and pushed.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/lsp-pilot.md`:
- Around line 1-202: The file has three markdownlint compliance issues: First,
remove the trailing closing parenthesis from the section 6 heading "## 6. How
this rides the existing MCP plumbing (reuse, do not rebuild)" to fix the MD026
violation. Second, review all 85 lines that exceed the 80-character limit
(primarily in URL references and table content blocks) and break them into
shorter lines where appropriate, paying special attention to long hyperlinks and
multi-line table entries that can be reformatted for readability. Third, ensure
the file ends with a newline character to complete the formatting requirements.
All cross-file references and content are substantively correct; this is purely
a formatting and line-length compliance fix.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4db2ac77-56cb-404e-9fca-667ada865dc1

📥 Commits

Reviewing files that changed from the base of the PR and between 1ff137e and 38818b8.

📒 Files selected for processing (1)

• docs/lsp-pilot.md

[don-petry]

Dev-Lead — waiting on PR blockers (intent: fix-reviews)

PR: #848
No changes were committed, but the PR still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews). The retry cron will re-attempt automatically. Next attempt after: 2026-06-20T22:22:14Z

[don-petry]

Dev-Lead — review-changes (no-changes)

No changes were needed for this PR.

[donpetry-bot]

Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-06-20T23:20:34Z.

[donpetry-bot]

Automated review — APPROVED ✓

Risk: LOW
Reviewed commit: 46155c7a327743f6a50f1f4715761f0f29e018e9
Review mode: triage-approved (single reviewer)

Summary

Docs-only PR adding docs/lsp-pilot.md (+202, single new file) — a scoping contract for the LSP-as-MCP pilot. No code, config, workflow, or dependency changes; nothing security-relevant. Confirms the triage low-risk assessment.

Linked issue analysis

Closes #840 (Phase 1). All five acceptance criteria are met by docs/lsp-pilot.md: target language/repo/rationale (§1), in/out-of-scope agent actions (§2), cold-start SLA with auto-skip degradation (§3), success metric + cost cap (§4), and candidate-server shortlist with an explicit exact-version-pinning rule (§5). CodeRabbit's Linked Issues check independently confirmed full coverage. Cross-references to scripts/engine.sh, docs/initiatives/mcp-powered-review.md, .github/review-mcp.json, and .github/workflows/pr-review.yml were verified to resolve to existing files.

Findings

No blocking findings.

• Risk: LOW — documentation-only addition, no executable surface.
• Advisory nits (non-blocking): CodeRabbit raised markdownlint formatting items (MD026 trailing punctuation in the §6 heading, lines >80 chars, trailing newline) on an earlier SHA (38818b8); these are advisory only and the CI Lint job passed. Gemini suggested adding a concrete repo path/link for the lsp-mcp candidate (currently the placeholder owner/lsp-mcp) — a minor doc polish item.
• CodeRabbit's final review state on the current head (46155c7) is APPROVED; its earlier CHANGES_REQUESTED was superseded.
• Secret scan: gitleaks CI check passed (SUCCESS). The run_secret_scanning MCP detector was not permitted in this run; not blocking given the docs-only content and green gitleaks check.

CI status

All validation checks green: Lint, ShellCheck, CodeQL (actions/python), SonarCloud (Quality Gate passed, 0 new issues), Secret scan (gitleaks), unit-tests, AgentShield, holdout-guard, Compile agentic workflows, Agent Security Scan, dependency-audit (ecosystem jobs skipped — no matching manifests), CodeRabbit. The only non-SUCCESS entries are 'dev-lead / dispatch' and 'dev-lead / ci-relay' (CANCELLED) — these are the dev-lead agent's own orchestration jobs, not quality gates. mergeStateStatus is BLOCKED solely because the org-leads team review is still required (human gate); reviewDecision REVIEW_REQUIRED.

---

Reviewed automatically by the PR-review agent (single-reviewer mode: fable 5). Reply if you need a human review.