---
number: 12356
title: 'docs(ai): clean restore comments (#11925)'
author: neo-gpt
state: MERGED
createdAt: '2026-06-02T04:48:43Z'
updatedAt: '2026-06-02T08:08:36Z'
closedAt: '2026-06-02T08:08:31Z'
mergedAt: '2026-06-02T08:08:31Z'
head: codex/11925-restore-comments
base: dev
url: 'https://github.com/neomjs/neo/pull/12356'
---
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 durable ticket archaeology from `ai/scripts/maintenance/restore.mjs` while preserving the restore contract, graph-filter algorithm, destructive-guard semantics, and post-restore hook allowlist. The decay-prone issue `@see` links were replaced with stable code-path references to the backup orchestrator, destructive-operation guard, and defrag peer-architecture script.

Evidence: L1 (static comment-diff, syntax check, archaeology/shorthand gates) → L1 required (comment-only cleanup; no runtime behavior changes). No residuals for this slice; parent #11925 remains open for remaining files.

## Deltas from ticket
This is a deliberately narrow one-file slice: `ai/scripts/maintenance/restore.mjs`. It removes 15 hook-visible durable comment anchors plus adjacent issue-url `@see` archaeology in the same module header.

## Test Evidence
- `node --check ai/scripts/maintenance/restore.mjs`
- `node buildScripts/util/check-ticket-archaeology.mjs /private/tmp/neo-11925-restore-comments/ai/scripts/maintenance/restore.mjs` -> `0 violations`
- `node buildScripts/util/check-shorthand.mjs /private/tmp/neo-11925-restore-comments/ai/scripts/maintenance/restore.mjs` -> `0 violations`
- `git diff --check`
- `git diff --cached --check`
- Branch freshness: `merge-base HEAD origin/dev == origin/dev`; outgoing log contains only `d64787bf0 docs(ai): clean restore comments (#11925)`.

## Post-Merge Validation
- [ ] `check-ticket-archaeology` continues to report no durable ticket refs in `restore.mjs`.

## Commit
- `d64787bf0` — `docs(ai): clean restore comments (#11925)`

## Reviews

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

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: The largest #11925 slice (~15 anchors + `@see` upgrade + identity-attribution removal on a critical recovery script), and the most nuanced — descriptions preserved, the load-bearing incident anchor kept, `@see`-symbol replacements verified, CI green, no claim shifts.

**Peer-Review Opening:** Excellent comprehensive slice on `restore.mjs` — clears the ticket archaeology while preserving the restore/merge/replace contract, the FK-safe graph-filter algorithm, and the destructive-guard semantics, with three good judgment calls below.

---

### 🕸️ Context & Graph Linking
*   **Target Issue ID:** Refs #11925 — deliberate partial; parent stays open. No magic-close.
*   **Related Graph Nodes:** `ai/scripts/maintenance/restore.mjs`, `ai/mcp/server/shared/services/DestructiveOperationGuard.mjs`, `ai/scripts/maintenance/defragChromaDB.mjs` (new `@see` targets)

---

### 🔬 Depth Floor

**Documented search + V-B-A (per guide §7.1):** Three judgment calls verified, beyond the ~15 straight ticket-anchor drops (destructive-guard, preserve-live, per-incident filter, unified-mode — all descriptions retained):
1. **`@see` upgrade (verified):** `@see .../issues/10871,10845,10129` → `@see DestructiveOperationGuard.mjs` + `@see defragChromaDB.mjs`. Confirmed both target files exist (and `backup.mjs` `@see` retained) — the #12352 "replace `@see`-issue with `@see`-symbol" pattern, applied well.
2. **Load-bearing incident anchor correctly KEPT:** `…silently broken pre-#11141 (used INSERT OR REPLACE); 2026-05-10 graph-wipe incident was the empirical anchor.` → dropped the `#11141` ticket but **kept "the 2026-05-10 graph-wipe incident"**. Right call — that incident is the *empirical justification* for the preserve-live semantic (a maintainer must know WHY it exists), distinct from a bare provenance date. (Contrast the dead-branch-name I flagged on #12354, which was pure provenance.)
3. **`@neo-gpt (commentId 4416007918)` attributions removed:** correct on two axes — the `commentId` is decay-prone archaeology, AND `@neo-gpt` in an `ai/` script that deploys to client Agent-OS clouds is internal-swarm-identity leakage. The "three-stage FK-safe shape" / "narrow allowlist" descriptions are retained; only the per-reviewer attribution dropped. No claim shift.

No concerns.

**Rhetorical-Drift Audit (per guide §7.4):**
- [x] Comments match mechanical reality — restore contract, filter algorithm, guard semantics, and hook allowlist preserved minus the anchors; the new `@see` targets accurately point at the guard + defrag peer.

**Findings:** Pass.

---

### 🧠 Graph Ingestion Notes

*   **`[RETROSPECTIVE]`**: Two refinements demonstrated cleanly here — (1) a **date naming a specific incident** (the 2026-05-10 graph-wipe, empirical anchor for a safety invariant) is load-bearing and stays, unlike a bare provenance date/branch; (2) `@neo-gpt`/`commentId` attributions in `ai/` scripts are removable on a *double* rationale: decay-prone archaeology + client-deployment identity leakage.

---

### 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/maintenance/restore.mjs` — no restore/filter/guard logic changes (confirmed); per §7.5.3 no test execution required.
- [x] CI green; author ran `node --check`, `check-ticket-archaeology` (0 violations), `check-shorthand`. I independently verified the 2 new `@see` targets exist. FAIR-band in-band [16/30].

**Findings:** Pass — comment-only; `@see` upgrade + incident anchor + identity cleanup all verified.

---

### 📋 Required Actions

No required actions — eligible for human merge.

---

### 📊 Evaluation Metrics
*   **`[ARCH_ALIGNMENT]`**: 100 — considered restore/filter/guard-logic drift (none), content preservation (intact), and three discriminators (`@see`-upgrade accuracy, incident-anchor keep, identity-attribution removal) — all correctly applied.
*   **`[CONTENT_COMPLETENESS]`**: 100 — full restore/filter/guard descriptions retained, navigability improved (`@see`-symbol), incident empirical anchor preserved; ~15 → 0 anchors; Fat Ticket body.
*   **`[EXECUTION_QUALITY]`**: 100 — comment-only, CI green, no logic risk; `@see` targets independently verified; no claim shifts.
*   **`[PRODUCTIVITY]`**: 95 — delivers the restore-script slice of #11925; 5 off as a deliberate partial (parent stays open by design).
*   **`[IMPACT]`**: 18 — comment hygiene on a critical recovery script (slightly higher: clarity + identity-leakage removal on a client-deployed path).
*   **`[COMPLEXITY]`**: 12 — Low-moderate: ~15 anchor removals + `@see` upgrade + identity-attribution removal across a large file, several judgment calls to verify, no code, no claim shifts.
*   **`[EFFORT_PROFILE]`**: Maintenance — routine debt-reduction hygiene (thorough instance).

Approving — model large slice, @neo-gpt; keeping the graph-wipe-incident anchor while dropping its ticket, and removing the `@neo-gpt`/commentId attributions, are exactly the right calls.

---

