Clean ai source-comment archaeology

Context

Operator feedback on 2026-05-24 surfaced a direct regression after the why-first documentation contract landed: PR #11901 still introduced source comments that foregrounded ticket #11862 AC5 / AC4 instead of durable intent.

This is not a new documentation theory. #11890 / PR #11897 codified the forward rule, and learn/agentos/AGENTS_ATLAS.md now says living source comments should default away from ticket, PR, lane, AC, cycle, and line-number anchors. The gap is that ai/ already carries substantial documentation archaeology, and new reviews can still miss it.

Duplicate / adjacency sweep:

• ask_knowledge_base(query='ai folder source comments ticket AC archaeology cleanup why-first documentation contract', type='ticket') failed with Internal error: Error finding id; exact sweeps below were used as fallback evidence.
• Local rg across resources/content/issues, resources/content/discussions, .agents/skills, and learn/agentos surfaced #11890 as the forward contract, #11605 as skill-baggage compression, and #10341 as MCP OpenAPI description budget. None owns active ai/ source cleanup.
• Current-tree diagnostic: rg -n "ticket #|#[0-9]{4,}|\bAC[0-9]+\b|\bAC [0-9]+\b|Lane [A-Z]|cycle-[0-9]|PR #[0-9]+|:[0-9]+-[0-9]+" ai --glob '*.mjs' returns 911 candidate lines.
• File inventory for the same diagnostic spans over 100 ai/**/*.mjs files, including Memory Core, GitHub Workflow sync, lifecycle scripts, Orchestrator services, and MCP server configs.

The Problem

The forward rule exists, but the living ai/ source still contains a large amount of ticket/PR/AC/cycle/line-number archaeology. That creates two costs:

1. Source comments become stale narrative instead of durable maintenance guidance.
2. Reviewers can accept new examples of the same pattern because the surrounding code normalizes it.

The desired direction remains one-way: tickets, PRs, commits, and Discussions may mention code because they are snapshot artifacts; source comments should explain durable intent, invariant, local boundary, or stable symbol.

src/core/Base.mjs is a useful style reference: its comments explain framework concepts and invariants in stable terms without pointing readers through closed ticket history.

The Architectural Reality

• #11890 / PR #11897 added the source-comment intent filter and diagnostic-first posture.
• learn/agentos/AGENTS_ATLAS.md carries the compact authority: comments explain durable intent and default away from ticket/PR/lane/AC/cycle/line-number anchors.
• This ticket is the active cleanup that #11890 deliberately kept out of scope.
• The scope is ai/**/*.mjs source comments and JSDoc first. Test titles, ticket bodies, PR bodies, generated resource mirrors, and historical ADR/discussion artifacts keep their existing archaeology rules.

The Fix

Perform a measured cleanup of ai/ source-comment archaeology.

1. Build an inventory from the diagnostic command and classify candidates by marker type and false-positive class.
2. Rewrite comments/JSDoc from ticket/AC/history phrasing into durable intent, stable symbols, and local ownership boundaries.
3. Start with the PR #11901 scheduling/collector surface, then proceed by high-noise ai/ subfolder batches.
4. Move genuinely durable historical rationale to ADR / Atlas / learn / owning primitive docs only when it is still load-bearing; otherwise delete stale history rather than re-homing it.
5. Keep the cleanup behavior-only: no runtime changes beyond comments unless a comment exposes a real code bug that needs a separate ticket.

Contract Ledger Matrix

Decision Record Impact

Aligned with ADR 0005's separation of executable authority from archaeology trails and with ADR 0008 / Progressive Disclosure. No ADR amendment expected; this is cleanup under the already-graduated #11890 contract.

Acceptance Criteria

• Inventory ai/**/*.mjs source-comment candidates with before counts, marker classes, and known false-positive classes.
• Clean the PR #11901 scheduling/collector comments that cite ticket #11862 AC* or equivalent snapshot anchors on current dev.
• Rewrite changed comments to durable intent, stable symbols, and local boundaries; do not replace ticket archaeology with another ticket reference.
• Remove line-number references from changed source comments; use stable symbols such as Base#ready() or owning files/classes where useful.
• Avoid re-explaining generic Neo primitives in every consumer; point to owning primitive docs only when a pointer is needed.
• Provide before/after diagnostic counts for the cleaned batch and list any explicit false positives left untouched.
• If the full ai/ sweep is too large for one PR, file child cleanup tickets by subfolder before closing this ticket.
• Validation includes git diff --check and any relevant lint/test command for touched files; no runtime behavior changes are bundled.

Out of Scope

• Hard CI enforcement for this pattern.
• Whole-repo cleanup outside ai/.
• Rewriting tickets, PR bodies, Discussions, ADR archaeology, generated sync mirrors, or test titles covered by #11890's carve-out.
• Changing runtime behavior while editing comments.

Avoided Traps

Related

• #11890 — forward why-first source-code documentation contract.
• PR #11897 — implementation of #11890.
• PR #11901 — immediate regression example cited by the operator.
• #11605 — adjacent skill-baggage compression program, not a duplicate.
• #10341 — adjacent MCP OpenAPI description budget, not a duplicate.

Origin Session ID: 967e325b-d90a-43f4-9e91-c212e9bda746

Handoff Retrieval Hint: query_raw_memories("ai source comments ticket AC archaeology cleanup why-first source-code documentation contract PR 11901")