---
id: 11924
title: Clean GitHub Workflow and shared MCP source comments
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - refactoring
  - architecture
  - model-experience
assignees:
  - neo-gpt
createdAt: '2026-05-24T20:48:58Z'
updatedAt: '2026-05-28T05:54:58Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11924'
author: neo-gpt
commentsCount: 2
parentIssue: 11912
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-28T05:54:58Z'
---
# Clean GitHub Workflow and shared MCP source comments

Parent epic: #11912

## Context

#11912 is being reshaped into an epic with grouped cleanup subissues. This subissue owns GitHub Workflow services and shared MCP runtime surfaces.

Current grouped baseline on `origin/dev`:

- `ai/services/github-workflow/**/*.mjs` plus `ai/mcp/server/github-workflow/**/*.mjs`: 93 diagnostic matches.
- `ai/mcp/server/shared/**/*.mjs`: 37 diagnostic matches.
- Top files include `PullRequestService.mjs`, `IssueSyncer.mjs`, `IssueService.mjs`, `toolService.mjs`, `RequestContextService.mjs`, and shared auth/transport helpers.

## The Problem

GitHub Workflow and shared MCP comments often cite specific PR cycles, ACs, and historical incidents. These comments should instead describe durable API, sync, auth, transport, and graph-ingestion contracts.

## The Architectural Reality

This group mediates GitHub issue/PR/discussion sync, review and relationship tooling, shared request context, auth, and transport behavior. Comments in this layer are read by agents during live workflow execution, so stale archaeology can distort current operational decisions.

## The Fix

Clean GitHub Workflow and shared MCP source comments in grouped batches:

1. Rewrite ticket/PR/AC/cycle references into stable API and service-boundary contracts.
2. Preserve references to public GitHub semantics or schema names when those are the stable authority.
3. Document false positives and runtime strings that are intentionally left unchanged.
4. Keep generated OpenAPI/YAML or resource mirrors out of scope unless a `.mjs` source comment points to them incorrectly.

## Contract Ledger Matrix

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| GitHub Workflow service comments/JSDoc | #11912 source-comment cleanup epic | Comments explain sync/review/relationship contracts without PR-cycle archaeology | File separate runtime/schema ticket if cleanup finds drift | PR bodies | Before/after focused diagnostics |
| Shared MCP runtime comments/JSDoc | #11912 source-comment cleanup epic | Comments explain auth/request/transport boundaries in stable terms | Preserve public API names and exact header names | PR bodies | Before/after focused diagnostics |

## Decision Record Impact

Aligned with ADR 0005 and ADR 0008. No ADR amendment expected.

## Acceptance Criteria

- [ ] Clean GitHub Workflow service `.mjs` comments/JSDoc to durable intent phrasing.
- [ ] Clean shared MCP `.mjs` comments/JSDoc to durable intent phrasing.
- [ ] Preserve runtime behavior and public API/schema names.
- [ ] PR evidence includes before/after focused counts and `git diff --check`.
- [ ] Parent #11912 remains open until all grouped subissues are complete.

## Out of Scope

- Memory Core, Knowledge Base/Graph, daemon/script, and residual config groups.
- Runtime behavior changes.
- Generated issue/PR/discussion mirrors.

## Related

- Parent epic: #11912

Origin Session ID: 019e5bac-15f3-7830-a59c-72772c757f9a

Handoff Retrieval Hint: `query_raw_memories("11912 github-workflow shared MCP RequestContext source-comment archaeology")`


## Timeline

- 2026-05-24T20:48:59Z @neo-gpt added the `documentation` label
- 2026-05-24T20:48:59Z @neo-gpt added the `enhancement` label
- 2026-05-24T20:48:59Z @neo-gpt added the `ai` label
- 2026-05-24T20:48:59Z @neo-gpt added the `refactoring` label
- 2026-05-24T20:49:00Z @neo-gpt added the `architecture` label
- 2026-05-24T20:49:00Z @neo-gpt added the `model-experience` label
- 2026-05-24T20:49:52Z @neo-gpt added parent issue #11912
- 2026-05-24T21:08:30Z @neo-gpt cross-referenced by #11912
- 2026-05-25T02:02:49Z @neo-gpt assigned to @neo-gpt
### @neo-gpt - 2026-05-25T02:03:18Z

## Ticket Intake Classification — @neo-gpt

Verdict: `valid-as-written`; ROI positive.

Evidence gathered before branch/code work:
- Live issue metadata: created `2026-05-24T20:48:58Z`, updated `2026-05-24T20:48:58Z`, no stale/no-auto-close labels, no assignee before claim. Age state: `pre-stale` under `.github/workflows/close-inactive-issues.yml` (`days-before-issue-stale=90`, `days-before-issue-close=14`).
- Parent epic #11912 has prior @neo-gpt epic-review: https://github.com/neomjs/neo/issues/11912#issuecomment-4529966118.
- Duplicate / close-link sweep: no existing PR found for `11924`; sibling #11922/#11923/#11925 are separate source-ownership groups.
- KB note: `ask_knowledge_base(... type=ticket)` still failed with `Internal error: Error finding id`; fallback evidence used live issue text, exact local search, current source diagnostics, and Memory Core.
- Current diagnostic scope: 21 `.mjs` files with candidate archaeology across `ai/services/github-workflow`, `ai/mcp/server/github-workflow`, and `ai/mcp/server/shared`; baseline candidate total from `rg --count-matches` is 151.
- ADR successor-risk: `adr-aligned` — ticket cites ADR 0005 / ADR 0008 as cleanup authority and does not amend or challenge either.

Implementation boundary: comments/JSDoc only; preserve runtime behavior, public API/schema names, exact env vars, GraphQL/GitHub semantics, and runtime strings.

Branch: `codex/11924-github-workflow-shared-comments`.

lane-state: next-lane (working #11924).


- 2026-05-25T02:07:34Z @neo-gpt cross-referenced by PR #11949
- 2026-05-25T05:25:22Z @tobiu referenced in commit `17861d4` - "chore(ai): clean github-workflow source comments (#11924) (#11949)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-25T13:08:00Z @neo-gpt cross-referenced by PR #11972
- 2026-05-25T14:31:51Z @tobiu referenced in commit `58cf942` - "chore(ai): clean github workflow sync comments (#11924) (#11972)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-26T12:14:23Z @neo-gpt cross-referenced by PR #12021
- 2026-05-26T13:06:22Z @neo-gpt referenced in commit `7790074` - "chore(ci): retrigger checks (#11924)"
- 2026-05-26T16:18:39Z @neo-gpt referenced in commit `4ad1e64` - "chore(ai): clean residual github workflow comments (#11924)"
- 2026-05-26T16:18:39Z @neo-gpt referenced in commit `814947c` - "chore(ci): retrigger checks (#11924)"
- 2026-05-26T16:48:18Z @neo-gpt referenced in commit `b18043b` - "chore(ai): clean residual github workflow comments (#11924)"
- 2026-05-26T16:48:18Z @neo-gpt referenced in commit `d2f41d3` - "chore(ci): retrigger checks (#11924)"
- 2026-05-26T17:06:17Z @tobiu referenced in commit `88df18d` - "chore(ai): clean residual github workflow comments (#11924) (#12021)

* chore(ai): clean residual github workflow comments (#11924)

* chore(ci): retrigger checks (#11924)

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-26T23:39:39Z @neo-gpt cross-referenced by PR #12057
- 2026-05-27T00:13:51Z @tobiu referenced in commit `3c0888a` - "chore(ai): clean shared mcp comments (#11924) (#12057)"
### @neo-gpt - 2026-05-28T05:54:53Z

**Input from GPT-5 (Codex Desktop):**

> ● ## Completion Closeout
> 
> I re-verified #11924 from current `dev` before closing.
> 
> Evidence:
> - Four #11924 PRs are merged: #11949, #11972, #12021, #12057.
> - Live focused archaeology sweep over `ai/services/github-workflow`, `ai/mcp/server/github-workflow`, and `ai/mcp/server/shared` now reports only 13 candidate matches across 3 files:
>   - `DiscussionSyncer.mjs`: runtime integrity error string naming `ADR 0011 / #11573`; preserved as operator-visible contract text, not comment archaeology.
>   - `PullRequestService.mjs`: cycle-1 / cycle-N template taxonomy in validator JSDoc and diagnostic copy; current stable contract for PR review template validation.
>   - `IssueService.mjs`: assignee-conflict / audit-trail runtime strings naming #11537 / Discussion #11536; preserved as user-facing contract evidence for the reassignment guard.
> - Remaining matches are stable runtime/validator contract anchors or intentional runtime strings, not stale PR-cycle/source-comment archaeology.
> 
> Acceptance criteria are satisfied for the GitHub Workflow + shared MCP group. Parent #11912 stays open for sibling groups.
> 
> lane-state: completed (#11924 closeout verified).

- 2026-05-28T05:54:58Z @neo-gpt closed this issue

