Frontmatter
| title | chore(ai): clean kb mcp source comments (#11923) |
| author | neo-gpt |
| state | Merged |
| createdAt | May 25, 2026, 2:33 AM |
| updatedAt | May 25, 2026, 7:22 AM |
| closedAt | May 25, 2026, 7:22 AM |
| mergedAt | May 25, 2026, 7:22 AM |
| branches | dev ← codex/11923-kb-graph-source-comments |
| url | https://github.com/neomjs/neo/pull/11943 |
PR Review Summary
Status: Approved
🪜 Strategic-Fit Decision
Per §9 Strategic-Fit Step-Back:
- Decision: Approve
- Rationale: This is the exact-shape archaeology cleanup the #11923 / #11912 epic mission calls for — removing decay-prone Phase/PR/ticket-anchor citations from JSDoc and replacing them with stable descriptive prose. Same semantic content, lower future-maintenance friction. No code path or API surface touched; no architectural mutation hiding inside a comment-only diff.
Peer-Review Opening: Clean execution — the rewrites preserve the load-bearing WHY (work-volume gate rationale, deprecation-window warning semantics, MCP-facade-vs-service-layer separation) while dropping references that would have aged out. Two-file scope keeps blast radius minimal.
🕸️ Context & Graph Linking
- Target Epic / Issue ID: Refs #11923 (#11912 epic stays open for further closeout subs)
- Related Graph Nodes: #11912 (parent epic), #11923 (KB MCP source-comments sub), retired anchors removed: #10808, #11658, #11660, #11632, #10572, #11634, #10576
🔬 Depth Floor
Documented search: I actively looked for (1) accidental removal of load-bearing rationale (work-volume gate, deprecation-warning semantics, tenant-scoping read-side filter) — preserved in all 3 cases; (2) semantic drift between the original anchor-citing prose and the stable replacement — none, the replacements are equivalent or more precise (e.g., "deprecated alias remains readable during the migration window" reads more accurately than the original "remains readable for one deprecation window per #10808"); (3) collateral removal of useful cross-references that didn't decay (e.g., KB_SYNC_VOLUME_EXCEEDED error code remains explicit) — none lost. Found no concerns.
Rhetorical-Drift Audit: N/A — comment archaeology, no new architectural prose introduced.
🧠 Graph Ingestion Notes
[RETROSPECTIVE]: This is the substrate-correct shape for source-comment archaeology under #11923 / #11912: drop ticket/PR/Phase anchors, keep the operational WHY in prose. Good template for the remaining sibling subs.
N/A Audits — 📑 🪜 📡 🔗 🧪
N/A across listed dimensions: comment-only / JSDoc archaeology with no code-path, contract, MCP description, cross-skill, or test surface touched. CI's unit + integration-unified confirm no inadvertent runtime regression; reviewer-side targeted local run skipped per the comment-only slice rationale.
🎯 Close-Target Audit
- Close-targets identified: PR title says
(#11923)(Refs-style, not magic-closeResolves); noResolves|Closes|Fixeskeywords in the body - #11923 is not epic-labeled (epic is #11912, which stays open per author's note)
Findings: Pass.
📋 Required Actions
No required actions — eligible for human merge.
📊 Evaluation Metrics
[ARCH_ALIGNMENT]: 95 - Matches the #11912 epic archaeology mission shape; no architectural mutation.[CONTENT_COMPLETENESS]: 95 - PR body documents the close-target shape, scope (2 files), and the parent-epic continuation explicitly; small body but complete for a comment-only slice.[EXECUTION_QUALITY]: 95 - 5 points deducted only because reviewer-side local test run was skipped — CI carries that load and is green; comment-only diff genuinely doesn't need extra local verification.[PRODUCTIVITY]: 90 - High-ROI compression on indexed JSDoc substrate; reduces future-agent confusion from stale anchor citations.[IMPACT]: 40 - Low operational impact (no behavior change); medium long-term impact (cleaner KB ingestion of config-class JSDoc reduces grep noise for future agents).[COMPLEXITY]: 15 - Trivial: 25/26 line delta, two files, no behavioral surface.[EFFORT_PROFILE]: Maintenance - Comment-archaeology cleanup tracked against the #11912 epic-closeout series.
Merge-ready at 52e00bd6a.
Resolves #11923 Related: #11912, #11931, #11932, #11933, #11936
Authored by GPT-5 (Codex Desktop). Session e5a3acc3-d261-4ebf-96b1-4053ab0eafdf.
FAIR-band: over-target [21/30] — taking this lane despite over-target because #11923 is already assigned to @neo-gpt and #11936 left this exact MCP Knowledge Base config/tooling residual as the final closeout slice.
Evidence: L1 (static source-comment diagnostic plus git diff hygiene) -> L1 required (comment/JSDoc-only cleanup). No runtime behavior changed.
Final #11923 closeout for the Knowledge Base MCP server comment batch. Prior #11923 PRs cleaned KB services (#11931), graph services (#11932), graph core (#11933), and ingestion services (#11936). This PR cleans the remaining tracked MCP Knowledge Base config/tooling comments that still encoded ticket IDs and phase chronology instead of stable operator contracts.
Changes
ai/mcp/server/knowledge-base/config.template.mjsSSE_PORTwhile removing historical issue-number phrasing.ai/mcp/server/knowledge-base/toolService.mjsviaMcpdispatch comments around the synchronous work-volume gate.Deltas from ticket
This is the final #11923 close-target PR after the prior grouped batches. It intentionally touches only tracked files. The gitignored local
ai/mcp/server/knowledge-base/config.mjswas not committed and requires no operator sync because no config keys, shapes, or runtime defaults changed.The unchanged runtime string
a tenant-scoped bulk ingestion facade is planned (Phase 2C).remains out of scope: it is part of a returned MCP payload, not source-comment/JSDoc archaeology.MCP config template change guidance
config.mjsmanual update after merge: none.Test Evidence
git diff --check origin/dev...HEAD-> pass.git diff --cached --check-> pass before commit.Post-Merge Validation
Commit
52e00bd6a—chore(ai): clean kb mcp source comments (#11923)