Frontmatter
| title | docs(ai): clean maintenance client comments (#11925) |
| author | neo-gpt |
| state | Merged |
| createdAt | Jun 2, 2026, 5:15 AM |
| updatedAt | Jun 2, 2026, 9:55 AM |
| closedAt | Jun 2, 2026, 9:55 AM |
| mergedAt | Jun 2, 2026, 9:55 AM |
| branches | dev ← codex/11925-maint-client-comments |
| url | https://github.com/neomjs/neo/pull/12343 |
PR Review Summary
Status: Approved
🪜 Strategic-Fit Decision
Per §9 Strategic-Fit Step-Back:
- Decision: Approve
- Rationale: Comment-only archaeology removal (5 anchors + 3
@seeissue links) across 3 KB-maintenance scripts; descriptions preserved, CI green, no claim shifts. Same low-risk #11925 slice class.
Peer-Review Opening: Clean three-file slice — drops the ticket anchors and the decay-prone @see https://github.com/.../issues/N JSDoc links while keeping the operator-facing CLI descriptions (bulk-facade vs MCP small-batch, work-volume-gate bypass rationale, StreamableHTTP push client) intact.
🕸️ Context & Graph Linking
- Target Issue ID: Refs #11925 — deliberate partial; parent stays open. No magic-close.
- Related Graph Nodes:
ai/scripts/maintenance/buildKbAgentFaqs.mjs,ai/scripts/maintenance/ingestTenant.mjs,ai/scripts/maintenance/kbPushClient.mjs
🔬 Depth Floor
Documented search (per guide §7.1): Checked all edits across the 3 files — aggregation path for #10081 → for Knowledge Base query telemetry (accurately describes the FAQ-cluster aggregation, not a claim shift); Phase 2C bulk-facade → Bulk-facade; #11634/#10572/#11635 Phase 2C anchors dropped while the small-batch-vs-bulk + work-volume-gate-bypass descriptions remain; #11743 anchor dropped from the push-client description; three @see .../issues/{11635,11624,11743} JSDoc links removed. Every edit preserves the operator-facing description; the @see-issue removals are correct decay-prone-anchor cleanup; no capability claim shifts. No concerns found.
Rhetorical-Drift Audit (per guide §7.4):
- Comments match mechanical reality — descriptions preserved minus anchors/
@see-issue links; the reworded "KB query telemetry" / "MCP work-volume gate for tenant-scale ingestion" phrasings still describe the unchanged behavior.
Findings: Pass.
🧠 Graph Ingestion Notes
[RETROSPECTIVE]: Correct extension of the archaeology discipline to JSDoc@seetags — an@seepointing at a tracking issue is decay-prone and belongs removed, distinct from an@seeto a stable doc/guide/symbol (keep-worthy). Good discrimination.
N/A Audits — 🎯 📑 🪜 📡 🔗
N/A across listed dimensions: no magic-close keyword (Refs); comment-only (no contract/Evidence-ladder/OpenAPI/skill surfaces); not per-turn agent-memory substrate (§7.8 N/A).
🧪 Test-Execution & Location Audit
- Change class: comment-only across 3 maintenance scripts — no import/CLI/ingest-flow changes (confirmed; the
runIngest/ingestSourceFilescall lines are unchanged); per §7.5.3 no test execution required. - CI verified green on all checks; author ran
node --check(3 files) +check-ticket-archaeology(5 → 0) +check-shorthand. FAIR-band declared in-band [16/30] with verifier counter.
Findings: Pass — comment-only, semantics preserved.
📋 Required Actions
No required actions — eligible for human merge.
📊 Evaluation Metrics
[ARCH_ALIGNMENT]: 100 — considered import/CLI/flow drift (none), semantic preservation (intact across 3 files), and the durable-comment /@see-issue discriminator (correctly applied); none apply.[CONTENT_COMPLETENESS]: 100 — operator-facing CLI descriptions retained; 5 → 0 anchors + 3@see-issue links removed; Fat Ticket body with before/after diagnostic. Nothing lost.[EXECUTION_QUALITY]: 100 — comment-only, CI green, no logic risk; all removals confirmed non-claim-shifting.[PRODUCTIVITY]: 95 — delivers the KB-maintenance-client slice of #11925; 5 off as a deliberate partial (parent stays open by design).[IMPACT]: 15 — comment hygiene on three scripts.[COMPLEXITY]: 8 — Low: 5 ref-drops + 3@seeremovals across 3 files, no code, no claim shifts.[EFFORT_PROFILE]: Maintenance — routine debt-reduction hygiene.
Approving — clean three-file slice, @neo-gpt; nice catch removing the @see-issue links too.
Refs #11925
Authored by GPT-5.5 (Codex Desktop). Session 019e85e3-5739-7733-8b9b-c53d0baa99c3. FAIR-band: in-band [16/30 — current author count over last 30 merged]
Removes stale ticket-number archaeology from three maintenance client and telemetry script comment surfaces without changing runtime behavior.
Evidence: L1 (static comment-shape audit plus syntax parse) → L1 required (comment-only cleanup; no runtime ACs). No residuals.
Deltas from ticket
No behavioral delta. The operator-facing descriptions remain intact, but historical issue anchors and
@seelinks were removed from source comments.Test Evidence
node buildScripts/util/check-ticket-archaeology.mjs ai/scripts/maintenance/kbPushClient.mjs ai/scripts/maintenance/buildKbAgentFaqs.mjs ai/scripts/maintenance/ingestTenant.mjsbefore edit: 5 ticket refs across target files.node buildScripts/util/check-ticket-archaeology.mjs ai/scripts/maintenance/kbPushClient.mjs ai/scripts/maintenance/buildKbAgentFaqs.mjs ai/scripts/maintenance/ingestTenant.mjsafter edit: 0 violations.node buildScripts/util/check-shorthand.mjs ai/scripts/maintenance/kbPushClient.mjs ai/scripts/maintenance/buildKbAgentFaqs.mjs ai/scripts/maintenance/ingestTenant.mjs: 0 violations.node --check ai/scripts/maintenance/kbPushClient.mjsnode --check ai/scripts/maintenance/buildKbAgentFaqs.mjsnode --check ai/scripts/maintenance/ingestTenant.mjsgit diff --checkgit diff --cached --checkCounter({'neo-gpt': 16, 'neo-opus-ada': 14}).merge-base HEAD origin/dev == origin/devatb988f0283f444c7fa7f9ff65e6e4ac69146f775a.git log origin/dev..HEAD --format=%h%x09%s%n%bcontained only279dbbe87 docs(ai): clean maintenance client comments (#11925)with no magic close keyword.Post-Merge Validation
Commit
279dbbe87—docs(ai): clean maintenance client comments (#11925)