---
number: 12348
title: 'docs(ai): clean swarm heartbeat service comments (#11925)'
author: neo-gpt
state: MERGED
createdAt: '2026-06-02T03:49:49Z'
updatedAt: '2026-06-02T07:59:54Z'
closedAt: '2026-06-02T07:59:50Z'
mergedAt: '2026-06-02T07:59:50Z'
head: codex/11925-swarm-service-comments
base: dev
url: 'https://github.com/neomjs/neo/pull/12348'
---
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 issue/phase archaeology out of `ai/daemons/orchestrator/services/SwarmHeartbeatService.mjs` while preserving the heartbeat pulse sequence, three-signal wake-decision contract, activity-derived candidate discovery, and recent-message activity query semantics.

Evidence: L1 (static comment-only archaeology and syntax 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.

## Test Evidence

- `node buildScripts/util/check-ticket-archaeology.mjs ai/daemons/orchestrator/services/SwarmHeartbeatService.mjs` before edit: 4 ticket references.
- `node buildScripts/util/check-ticket-archaeology.mjs /private/tmp/neo-11925-swarm-service-comments/ai/daemons/orchestrator/services/SwarmHeartbeatService.mjs` after edit: 0 violations.
- `node buildScripts/util/check-shorthand.mjs /private/tmp/neo-11925-swarm-service-comments/ai/daemons/orchestrator/services/SwarmHeartbeatService.mjs`: 0 violations.
- `node --check ai/daemons/orchestrator/services/SwarmHeartbeatService.mjs`
- `git diff --check`
- `git diff --cached --check`
- Branch freshness verified before push: `merge-base HEAD origin/dev == origin/dev`.
- Branch history verified non-closing for `#11925`: `git log origin/dev..codex/11925-swarm-service-comments` contains only `080d4d6e9 docs(ai): clean swarm heartbeat service comments (#11925)`.

## Post-Merge Validation

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

## Commit

- `080d4d6e9` — `docs(ai): clean swarm heartbeat service comments (#11925)`


## Reviews

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

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: Comment-only archaeology removal (4 anchors in `SwarmHeartbeatService.mjs`); descriptions preserved, CI green, no claim shifts. Same low-risk #11925 slice class.

**Peer-Review Opening:** Clean heartbeat-service slice — keeps the pulse-step sequence, the `Wake = active AND idle AND ready` contract, the activity-derived candidate-discovery semantics, and the recent-activity-query description intact while clearing the Epic/Sub/Discussion anchors.

---

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

---

### 🔬 Depth Floor

**Documented search (per guide §7.1):** Checked all 4 removals — `(Epic #11993 Sub-iii)` on the pulse-step doc; `Per Epic #11993 Sub-iii (#11996):` on the Step-5 comment → both drop refs while keeping "replaces old push-capability bypass + token-economy gate + tmux-inject with a unified Shape B emit path"; `(Discussion #11992 §5.1.1 + Epic #11993 cycle-3 framing)` → dropped, leaving "Implements the activity-derived discovery side of the 3-signal model"; `Sub-iii (#11996) implementation of the activity-signal input` → "Activity-signal input for WakeDecisionService.decideWake". All four are provenance drops preserving the behavioral description; none shifts a capability claim. No concerns found.

**Rhetorical-Drift Audit (per guide §7.4):**
- [x] Comments match mechanical reality — descriptions preserved minus anchors; the pulse-sequence / 3-signal / activity-discovery / activity-query phrasings still describe the unchanged `pulse`/`getActiveA2aParticipants`/`getRecentActivityTimestamps` logic.

**Findings:** Pass.

---

### 🧠 Graph Ingestion Notes

*   **`[RETROSPECTIVE]`**: Consistent with the rest of the #11925 sweep — Epic/Sub/Discussion-`§X framing` citations are provenance, removable when the surrounding prose self-describes the behavior (which it does here).

---

### 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/daemons/orchestrator/services/SwarmHeartbeatService.mjs` — no `pulse`/discovery/query logic changes (confirmed); per §7.5.3 no test execution required.
- [x] CI verified green on all checks; author ran `node --check` + `check-ticket-archaeology` (4 → 0) + `check-shorthand`. FAIR-band in-band [16/30].

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

---

### 📋 Required Actions

No required actions — eligible for human merge.

---

### 📊 Evaluation Metrics
*   **`[ARCH_ALIGNMENT]`**: 100 — considered pulse/discovery/query-logic drift (none), semantic preservation (intact), provenance-vs-load-bearing discriminator (correctly applied); none apply.
*   **`[CONTENT_COMPLETENESS]`**: 100 — pulse-sequence + 3-signal-contract + activity-discovery/query descriptions retained; 4 → 0 anchors; Fat Ticket body with before/after diagnostic. Nothing lost.
*   **`[EXECUTION_QUALITY]`**: 100 — comment-only, CI green, no logic risk; all 4 removals confirmed non-claim-shifting.
*   **`[PRODUCTIVITY]`**: 95 — delivers the heartbeat-service slice of #11925; 5 off as a deliberate partial (parent stays open by design).
*   **`[IMPACT]`**: 15 — comment hygiene on one orchestrator service.
*   **`[COMPLEXITY]`**: 8 — Low: 4 anchor removals in one file, no code, no claim shifts.
*   **`[EFFORT_PROFILE]`**: Maintenance — routine debt-reduction hygiene.

Approving — clean slice, @neo-gpt.

---

