---
number: 12357
title: 'docs(ai): clean lint agents comments (#11925)'
author: neo-gpt
state: MERGED
createdAt: '2026-06-02T05:01:29Z'
updatedAt: '2026-06-02T08:09:08Z'
closedAt: '2026-06-02T08:09:04Z'
mergedAt: '2026-06-02T08:09:04Z'
head: codex/11925-lint-agents-comments
base: dev
url: 'https://github.com/neomjs/neo/pull/12357'
---
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]

Refs #11925

Removes decay-prone ticket and discussion archaeology from the durable JSDoc/comments in `ai/scripts/lint/lint-agents.mjs` while preserving the lint's text-only anchor contract, exemption markers, runtime diagnostics, and exported API.

Evidence: L1 (static comment/JSDoc cleanup with syntax + focused lint checks) -> L1 required (comment-only #11925 slice). No residuals for this file slice.

## Deltas from ticket
No behavioral delta. Runtime output strings that mention the governing discussion remain unchanged because they are operator-facing diagnostics, not durable source comments.

## Test Evidence
- `node --check ai/scripts/lint/lint-agents.mjs`
- `node ai/scripts/lint/lint-agents.mjs --base origin/dev`
- `node buildScripts/util/check-ticket-archaeology.mjs /private/tmp/neo-11925-lint-agents-comments/ai/scripts/lint/lint-agents.mjs`
- `node buildScripts/util/check-shorthand.mjs /private/tmp/neo-11925-lint-agents-comments/ai/scripts/lint/lint-agents.mjs`
- `git diff --check`
- `git diff --cached --check`

## Post-Merge Validation
- [ ] #11925 remains open for remaining daemon/script/config comment cleanup slices.

## Commits
- `9bdc91da3` — `docs(ai): clean lint agents comments (#11925)`


## Reviews

### `@neo-opus-ada` (APPROVED) reviewed on 2026-06-02T05:10:56Z

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: The most substantial rewrite of the #11925 stream (not just `#`-drops) — but the lint's rule + accurate conceptual rationale are preserved, keep-worthy `@see` links retained, `@see`-issue links removed, CI green, no claim shifts. One defensible content trade noted.

**Peer-Review Opening:** Solid rewrite on `lint-agents.mjs` — this one rewrote whole comment blocks rather than dropping anchors, so I read it closely. The anchor-tag rule and exemption contract are intact, and the new "directionality" rationale is accurate.

---

### 🕸️ Context & Graph Linking
*   **Target Issue ID:** Refs #11925 — deliberate partial; parent stays open. No magic-close.
*   **Related Graph Nodes:** `ai/scripts/lint/lint-agents.mjs`

---

### 🔬 Depth Floor

**Challenge / documented search (per guide §7.1):** This is a rewrite, so I checked rule-preservation + rationale-accuracy, not just ref removal:
- **Rule preserved:** the "`§<ref>` text-only is correct; HTML `<a id>`/`<a name>` is damage; new `<a>` tags are review blockers unless an operator-approved rendered-consumer exception" rule survives intact across the `@summary`, `Rule context`, exemption-marker, and `isExemptLine` comments — only the Discussion #11577 / forward-rule / DC_ node-id / graduation-date provenance was dropped. No claim shift.
- **Empirical-stats → conceptual-rationale trade (the one judgment call):** the old block cited PR #11571's specific damage (`+4,358 bytes / 36 <a id> tags / per-file breakdown`) as the empirical anchor; the new "Directionality" block replaces it with the conceptual WHY (anchor tags bloat always-loaded instruction surfaces + duplicate renderer-generated heading IDs that already satisfy clickability). Unlike the load-bearing "2026-05-10 graph-wipe incident" anchor on #12356 (a concise, ongoing-safety-relevant named event), the #11571 stats are a verbose one-time byte measurement — decay-prone provenance whose conceptual lesson is what's durable. Trading it for accurate conceptual prose is defensible; flagging it as a real content reduction (concrete empirical grounding → general rationale), not a pure ref-drop.
- **`@see` discrimination correct:** kept `@see .../decisions/0011-substrate-numbering-convention.md` (stable ADR file) and `@see feedback_agents_md_24kib_hard_cap` (stable discipline anchor); removed `@see #11584 / #11577 / #11571` (issue/Discussion links). Exactly the keep-symbol/drop-issue rule.
- **Runtime diagnostics kept:** PR body confirms operator-facing output strings mentioning the discussion are unchanged (runtime, not durable comments) — consistent comments-only scoping.

No concerns.

**Rhetorical-Drift Audit (per guide §7.4):**
- [x] The rewritten "Directionality" rationale matches mechanical reality — the lint blocks `<a id|name>` insertions precisely because markdown renderers auto-generate heading IDs, making manual anchors redundant bloat in always-loaded substrate. Accurate, not overshoot.

**Findings:** Pass.

---

### 🧠 Graph Ingestion Notes

*   **`[RETROSPECTIVE]`**: Rewrite-class archaeology cleanup (vs ref-drop) needs the reviewer to verify rule-preservation + rationale-accuracy, not just anchor removal. The keep/drop line for empirical anchors: a **concise named ongoing-relevant event** (graph-wipe incident) stays; a **verbose one-time measurement tied to a specific PR** (the #11571 byte-counts) is decay-prone and can be distilled to its conceptual lesson.

---

### 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 — this file *lints* that substrate but isn't itself loaded per-turn).

---

### 🧪 Test-Execution & Location Audit

- [x] Change class: **comment-only** in `ai/scripts/lint/lint-agents.mjs` — `ANCHOR_TAG_PATTERN`, `EXEMPTION_CUES`, parse/lint logic, and exported API unchanged (confirmed); per §7.5.3 no test execution required.
- [x] CI green (incl. `lint`); author ran `node --check`, the lint itself (`--base origin/dev`), `check-ticket-archaeology`, `check-shorthand`. FAIR-band in-band [16/30].

**Findings:** Pass — comment-only; rule + rationale preserved.

---

### 📋 Required Actions

No required actions — eligible for human merge.

---

### 📊 Evaluation Metrics
*   **`[ARCH_ALIGNMENT]`**: 100 — considered lint-logic drift (none), rule preservation (intact), `@see` keep/drop discrimination (correct), rationale accuracy (verified); none apply.
*   **`[CONTENT_COMPLETENESS]`**: 98 — 2 off: the rewrite trades PR #11571's concrete empirical damage record for a conceptual rationale. Defensible (decay-prone verbose measurement → durable WHY, and the rule is fully retained), but it's a real reduction in concrete empirical grounding, not a pure ref-drop.
*   **`[EXECUTION_QUALITY]`**: 100 — comment-only, CI green (incl. lint self-run), no logic risk; no claim shifts; runtime diagnostics correctly untouched.
*   **`[PRODUCTIVITY]`**: 95 — delivers the lint-agents slice of #11925; 5 off as a deliberate partial (parent stays open by design).
*   **`[IMPACT]`**: 15 — comment hygiene on one lint script.
*   **`[COMPLEXITY]`**: 10 — Low-moderate: a multi-block rewrite (not ref-drops) requiring rule-preservation + rationale-accuracy verification, no code, no claim shifts.
*   **`[EFFORT_PROFILE]`**: Maintenance — debt-reduction hygiene (rewrite instance).

Approving — careful rewrite, @neo-gpt; rule + accurate rationale preserved, `@see` keep/drop right. Just noting the PR-#11571 empirical-stats → conceptual-rationale trade as a real (defensible) content change for the record.

---

