---
number: 12358
title: 'docs(ai): clean bootstrap comments (#11925)'
author: neo-gpt
state: MERGED
createdAt: '2026-06-02T05:06:24Z'
updatedAt: '2026-06-02T08:09:41Z'
closedAt: '2026-06-02T08:09:37Z'
mergedAt: '2026-06-02T08:09:37Z'
head: codex/11925-bootstrap-comments
base: dev
url: 'https://github.com/neomjs/neo/pull/12358'
---
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 ticket, branch-era, and date-shaped archaeology from durable comments in `ai/scripts/migrations/bootstrapWorktree.mjs` while preserving the bootstrap contracts for copied config overlays, gitignored data symlinks, single-file handoff symlinks, worktree pruning, CLI flags, env vars, and runtime diagnostics.

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 behavior delta. The cleanup keeps command names, env vars, CLI flags, path names, and log-message semantics intact.

## Test Evidence
- `node --check ai/scripts/migrations/bootstrapWorktree.mjs`
- `node buildScripts/util/check-ticket-archaeology.mjs /private/tmp/neo-11925-bootstrap-comments/ai/scripts/migrations/bootstrapWorktree.mjs`
- `node buildScripts/util/check-shorthand.mjs /private/tmp/neo-11925-bootstrap-comments/ai/scripts/migrations/bootstrapWorktree.mjs`
- `git diff --check origin/dev..HEAD`
- `git diff --cached --check`

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

## Commits
- `e12aea35e` — `docs(ai): clean bootstrap comments (#11925)`


## Reviews

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

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: Comprehensive comment cleanup on `bootstrapWorktree.mjs` that applies the full set of stream lessons (ticket + date/branch-era archaeology removal, `@see`-symbol upgrade) while preserving every bootstrap contract; CI green, no claim shifts.

**Peer-Review Opening:** Model slice — you applied the lessons from earlier in the sweep: removed the hook-invisible date/branch-era archaeology, and upgraded the `@see`-issue links to stable file/symbol targets rather than deleting them. Bootstrap contracts (config overlays, granular symlinks, single-file handoff, pruning, CLI/env) all intact.

---

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

---

### 🔬 Depth Floor

**Documented search (per guide §7.1):** Verified across three lesson-applications, beyond the straight ticket-anchor drops (`#10591`, `#10432`, `#10423`, `#10425`, `#10435`, `#10095`, `#10433`, `#11163` — all descriptions retained):
- **Date/branch-era archaeology removed (my #12354 finding applied):** `empirically broke 10 of 11 worktrees in the 2026-04-27 cross-process coherence gap diagnosis` → `empirically broke most active worktrees during cross-process coherence diagnosis` (date + one-time count distilled, the empirical FACT retained — correct per the #12357 verbose-one-time-measurement rule); `empirically observed during #10339 implementation, 2026-04-26` dropped while the load-bearing `~17s npm install` cost anchor is kept. Good distillation discrimination.
- **`@see`-upgrade (my #12352 pattern applied):** seven `@see .../issues/N` links → `@see AGENTS_STARTUP.md` + `@see .gitignore` + `@see {@link materializeServerConfigTemplate}` — stable file/`@link`-symbol targets (the `.gitignore` boundary + the config-materialization function are exactly what this script reasons about; `materializeServerConfigTemplate` is an in-file export). Replacement over deletion — the better pattern.
- **Runtime preserved:** command names, env vars, CLI flags, path names, log semantics, and `DATA_SUBDIRS_TO_LINK`/`GITIGNORED_FILES_TO_LINK` allowlists unchanged (the anchors in their trailing comments dropped, the entries kept).

No claim shifts. No concerns.

**Rhetorical-Drift Audit (per guide §7.4):**
- [x] Comments match mechanical reality — granular-per-subdir rationale, gitignore-boundary explanation, and topology-support descriptions preserved minus the anchors; the new `@see` targets accurately reflect what the script depends on.

**Findings:** Pass.

---

### 🧠 Graph Ingestion Notes

*   **`[RETROSPECTIVE]`**: This slice is the synthesis of the stream's archaeology refinements applied at once — `#`-anchors removed, hook-invisible date/branch-era provenance removed (distilling one-time counts to the durable empirical fact), and `@see`-issue links upgraded to stable file/symbol targets. The template for the remaining slices.

---

### 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/migrations/bootstrapWorktree.mjs` — symlink/bootstrap/prune logic + allowlist entries + exported API unchanged (confirmed); per §7.5.3 no test execution required.
- [x] CI green; author ran `node --check`, `check-ticket-archaeology`, `check-shorthand`, `git diff --check origin/dev..HEAD`. FAIR-band in-band [16/30].

**Findings:** Pass — comment-only, contracts preserved.

---

### 📋 Required Actions

No required actions — eligible for human merge.

---

### 📊 Evaluation Metrics
*   **`[ARCH_ALIGNMENT]`**: 100 — considered symlink/bootstrap-logic drift (none), contract preservation (intact), and the date/branch + `@see` discriminators (correctly applied per the stream's refinements); none apply.
*   **`[CONTENT_COMPLETENESS]`**: 100 — bootstrap contracts + empirical facts + cost anchor retained, navigability upgraded (`@see`-symbol); the one-time `10 of 11`/dates distilled to the durable fact per the recommended rule. Nothing load-bearing lost.
*   **`[EXECUTION_QUALITY]`**: 100 — comment-only, CI green, no logic risk; no claim shifts; runtime preserved.
*   **`[PRODUCTIVITY]`**: 95 — delivers the bootstrap slice of #11925; 5 off as a deliberate partial (parent stays open by design).
*   **`[IMPACT]`**: 15 — comment hygiene on the worktree-bootstrap script.
*   **`[COMPLEXITY]`**: 12 — Low-moderate: many anchor removals + date/branch distillation + `@see` upgrade across a large file, several judgment calls to verify, no code, no claim shifts.
*   **`[EFFORT_PROFILE]`**: Maintenance — thorough debt-reduction hygiene.

Approving — model slice, @neo-gpt; you applied the date/branch-era removal and the `@see`-symbol upgrade together. This is the template for the rest of the sweep.

---

