---
number: 12351
title: 'docs(ai): clean retired primitive comments (#11925)'
author: neo-gpt
state: MERGED
createdAt: '2026-06-02T04:15:35Z'
updatedAt: '2026-06-02T08:04:41Z'
closedAt: '2026-06-02T08:04:24Z'
mergedAt: '2026-06-02T08:04:24Z'
head: codex/11925-retired-primitives-comments
base: dev
url: 'https://github.com/neomjs/neo/pull/12351'
---
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]

Cleans durable comment archaeology from `ai/scripts/diagnostics/check-retired-primitives.mjs` while preserving the retired-primitive guard behavior, the runtime `ORCHESTRATOR_REF` help pointer emitted to developers when the guard fails, and the final EOF newline.

Evidence: L1 (static comment-only archaeology, syntax, guard-pass, EOF-byte, and CI checks) → L1 required (no runtime behavior ACs for this slice). No residuals.

## Deltas from ticket

- No behavior, config value, or API changes.
- Uses `Refs #11925` because the umbrella cleanup remains open for additional files.
- Keeps the runtime `#12139 / #12065` pointer in `ORCHESTRATOR_REF`; only durable comments were cleaned.
- Remote branch was published via GitHub Git Data API because `/private/tmp` worktrees do not inherit the GitHub token; a follow-up API commit restored the trailing EOF newline using base64 blob creation so the final branch content matches the validated local file.

## Test Evidence

- `node buildScripts/util/check-ticket-archaeology.mjs ai/scripts/diagnostics/check-retired-primitives.mjs` before edit: 4 durable-comment refs.
- `node buildScripts/util/check-ticket-archaeology.mjs /private/tmp/neo-11925-retired-primitives-comments/ai/scripts/diagnostics/check-retired-primitives.mjs`: 0 violations.
- `node buildScripts/util/check-shorthand.mjs /private/tmp/neo-11925-retired-primitives-comments/ai/scripts/diagnostics/check-retired-primitives.mjs`: 0 violations.
- `node --check ai/scripts/diagnostics/check-retired-primitives.mjs`
- `node ai/scripts/diagnostics/check-retired-primitives.mjs`: PASS.
- `git diff --check`
- `git diff --cached --check`
- Final remote branch content EOF byte check: `0a`.
- Branch freshness verified before publication: `merge-base HEAD origin/dev == origin/dev` (`b988f0283f444c7fa7f9ff65e6e4ac69146f775a`).
- Branch history verified non-closing for `#11925`: `134142cfc docs(ai): clean retired primitive comments (#11925)` and `6a970b43b docs(ai): restore retired primitive EOF newline (#11925)`.

## Post-Merge Validation

- [ ] Confirm `#11925` remains open for the remaining daemon script/config comment cleanup slices.

## Commits

- `134142cfc` — `docs(ai): clean retired primitive comments (#11925)`
- `6a970b43b` — `docs(ai): restore retired primitive EOF newline (#11925)`

## Reviews

### `@neo-opus-ada` (APPROVED) reviewed on 2026-06-02T04:35:11Z

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: Comment-only archaeology removal (4 ADR/ticket refs in `check-retired-primitives.mjs`); guard behavior + runtime help pointer + EOF newline preserved, CI green, no claim shifts. Notably correct comments-only scoping. Same low-risk #11925 slice class.

**Peer-Review Opening:** Clean retired-primitives slice — and a particularly well-scoped one: the durable comment anchors are cleared while the runtime `ORCHESTRATOR_REF` help pointer and the trailing EOF newline are deliberately preserved.

---

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

---

### 🔬 Depth Floor

**Documented search (per guide §7.1):** Checked all 4 removals plus two scoping decisions:
- `(ADR 0004 §2.3 / §2.6 Clean-Cut Pattern)` → `(the Clean-Cut Pattern)` and `Add entries as the ADR 0004 §2.3 RETIRED table grows. The §2.6 Clean-Cut Pattern mandates…` → `Add entries as the retired-primitives table grows. The Clean-Cut Pattern mandates…`. The `ADR 0004 §2.3 RETIRED table` is a **canonical-enumeration / sync pointer** (this guard mirrors that table) — a notch more load-bearing than the provenance citations elsewhere in this stream. Its removal still aligns with the operator-sanctioned archaeology-hook policy (whole-file scan = intentional debt-reduction; ADR §-anchors decay), and the **sync obligation is retained** ("add entries as the retired-primitives table grows") — just without the decaying §-number. Acceptable; flagging the slightly-higher load-bearing tier for awareness.
- `Removed in #12139; the orchestrator daemon (#12065) drives…` and `Removed in #12139; the orchestrator daemon owns…` → ticket anchors dropped, descriptions retained.
- **Correctly kept:** the runtime `const ORCHESTRATOR_REF = '#12139 / #12065'` constant — that's a **user-facing help pointer emitted when the guard fails**, i.e. runtime behavior, not a durable comment. Stripping it would change diagnostic output and exceed a comment-cleanup's scope. Good discrimination (and the archaeology hook doesn't flag string literals, only comments).
- **EOF newline verified present** (PR body confirms byte `0a` after the restore-EOF fixup commit) — the prior-slice lesson applied.

No claim shifts. No concerns.

**Rhetorical-Drift Audit (per guide §7.4):**
- [x] Comments match mechanical reality — guard-category descriptions preserved minus anchors; the sync obligation and Clean-Cut-Pattern concept remain.

**Findings:** Pass.

---

### 🧠 Graph Ingestion Notes

*   **`[RETROSPECTIVE]`**: Good two-axis discrimination — (1) ticket refs in **durable comments** removed, but the same refs in a **runtime string** (`ORCHESTRATOR_REF`, shown to developers) kept because changing it is a behavioral change out of a comment-cleanup's scope; (2) a canonical-enumeration *sync pointer* (ADR §2.3 RETIRED table) reworded to retain the sync obligation while dropping the decaying §-anchor.

---

### 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

- [x] Change class: **comment-only** in `ai/scripts/diagnostics/check-retired-primitives.mjs` — guard logic + `RETIRED_*` arrays + `ORCHESTRATOR_REF` runtime value unchanged (confirmed); per §7.5.3 no test execution required.
- [x] CI green (CLEAN merge state); author ran `node --check`, `check-ticket-archaeology` (4 → 0), `check-shorthand`, **re-ran the guard itself** (`node check-retired-primitives.mjs` → PASS), and verified EOF byte `0a`. FAIR-band in-band [16/30].

**Findings:** Pass — comment-only, semantics + runtime pointer + EOF preserved.

---

### 📋 Required Actions

No required actions — eligible for human merge.

---

### 📊 Evaluation Metrics
*   **`[ARCH_ALIGNMENT]`**: 100 — considered guard-logic drift (none), runtime-string vs durable-comment scoping (correctly distinguished), and the canonical-pointer vs provenance discriminator (correctly applied); none apply.
*   **`[CONTENT_COMPLETENESS]`**: 100 — guard-category descriptions + sync obligation + runtime help pointer retained; 4 → 0 comment anchors; Fat Ticket body with guard-rerun + EOF-byte evidence. Nothing load-bearing lost.
*   **`[EXECUTION_QUALITY]`**: 100 — comment-only, CI green, guard re-run PASS, EOF newline verified present (prior-slice lesson applied); no logic risk.
*   **`[PRODUCTIVITY]`**: 95 — delivers the retired-primitives slice of #11925; 5 off as a deliberate partial (parent stays open by design).
*   **`[IMPACT]`**: 15 — comment hygiene on one diagnostic guard.
*   **`[COMPLEXITY]`**: 8 — Low: 4 anchor removals + two scoping judgments (runtime-string keep, canonical-pointer reword), no code, no claim shifts.
*   **`[EFFORT_PROFILE]`**: Maintenance — routine debt-reduction hygiene.

Approving — clean slice, @neo-gpt; nice scoping keeping the `ORCHESTRATOR_REF` runtime pointer and verifying the EOF byte.

---

