---
number: 12347
title: 'docs(ai): clean wake decision comments (#11925)'
author: neo-gpt
state: MERGED
createdAt: '2026-06-02T03:43:45Z'
updatedAt: '2026-06-02T07:59:30Z'
closedAt: '2026-06-02T07:59:27Z'
mergedAt: '2026-06-02T07:59:27Z'
head: codex/11925-wake-decision-comments
base: dev
url: 'https://github.com/neomjs/neo/pull/12347'
---
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 ticket/phase archaeology out of `ai/daemons/orchestrator/services/WakeDecisionService.mjs` while preserving the wake-decision contract: activity-derived liveness, orchestrator-local backoff state, structured readiness sentinels, and dual message-shape parsing.

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.
- Also removed one non-numbered AC/phase phrase because it was the same durable-comment archaeology class, even though the numeric checker does not count it.
- 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/WakeDecisionService.mjs` before edit: 7 ticket references.
- `node buildScripts/util/check-ticket-archaeology.mjs /private/tmp/neo-11925-wake-decision-comments/ai/daemons/orchestrator/services/WakeDecisionService.mjs` after edit: 0 violations.
- `node buildScripts/util/check-shorthand.mjs /private/tmp/neo-11925-wake-decision-comments/ai/daemons/orchestrator/services/WakeDecisionService.mjs`: 0 violations.
- `node --check ai/daemons/orchestrator/services/WakeDecisionService.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-wake-decision-comments` contains only `515e38152 docs(ai): clean wake decision comments (#11925)`.

## Post-Merge Validation

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

## Commit

- `515e38152` — `docs(ai): clean wake decision comments (#11925)`


## Reviews

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

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: Comment-only archaeology removal (7 anchors in `WakeDecisionService.mjs`); descriptions preserved, CI green, no claim shifts. Same low-risk #11925 slice class with one minor navigational-pointer note (non-blocking).

**Peer-Review Opening:** Clean wake-decision slice — keeps the activity-derived-liveness rationale, the orchestrator-local-backoff design + reason, the `Wake = active AND idle AND ready` contract, and the dual message-shape parsing description intact while clearing the ticket/Epic/Discussion/AC anchors.

---

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

---

### 🔬 Depth Floor

**Documented search (per guide §7.1):** Checked all 7 removals. Most are provenance drops where the design/behavior description is fully retained (the 10h+-session / A2A-only-durable-signal rationale; the backoff-state-NOT-on-WAKE_SUBSCRIPTION decision + its "would pollute client-deployment graph substrate" reason; the dual-shape parsing; the author-identity-not-consulted merge rule). Two warranted extra attention:
- **Rejected-predecessor generalization** — `successor to the rejected MC HealthService projection (#11982) and the rejected "harness-side heartbeat workaround" (#11872)` → `successor to designs that projected wake liveness through Memory Core health checks or harness-side heartbeat workarounds`. I confirmed this is accurate from direct context: #11982 was indeed the rejected MC-HealthService wake-projection. The generalization preserves the WHAT (this is the substrate-correct successor to those rejected approaches) — no claim shift.
- **`see Epic #11993 "drop-X" table`** removed → leaves "dropping any one yields a known pathological case." This is the one removal that drops a *navigational pointer* (where the per-signal pathological cases are enumerated), not just an anchor. Acceptable: the invariant (each signal independently necessary) is still asserted, and the drop-X enumeration is design-doc material that belongs in the (decay-prone) Epic, not the code comment. Worth being aware of as the single case where a pointer — not just a ref — was lost.

No blocking concerns.

**Rhetorical-Drift Audit (per guide §7.4):**
- [x] Comments match mechanical reality — descriptions preserved minus anchors; the wake-contract, backoff, and parsing phrasings still describe the unchanged `decideWake`/`parseReadinessSentinel` logic; the rejected-predecessor generalization is accurate.

**Findings:** Pass.

---

### 🧠 Graph Ingestion Notes

*   **`[RETROSPECTIVE]`**: Subtle tier within archaeology cleanup — most refs are pure provenance (remove freely), but `see Epic #N "<table>"` is a *navigational pointer* to an enumeration. Removing it is fine when the code-comment-appropriate invariant is retained and the detail is design-doc material; flag it as a deliberate choice rather than a silent drop so a future reader knows the enumeration lives in the design record.

---

### 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/WakeDecisionService.mjs` — no `decideWake`/`parseReadinessSentinel`/backoff-method 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` (7 → 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 decision/parsing/backoff-logic drift (none), semantic preservation (intact), and the provenance-vs-load-bearing discriminator (correctly applied, incl. the rejected-predecessor generalization); none apply.
*   **`[CONTENT_COMPLETENESS]`**: 98 — 2 off: removing `see Epic #11993 "drop-X" table` drops a navigational pointer to the pathological-case enumeration (the invariant is retained, so minor); everything else preserved with 7 → 0 anchors and a Fat Ticket body.
*   **`[EXECUTION_QUALITY]`**: 100 — comment-only, CI green, no logic risk; all 7 removals confirmed non-claim-shifting (rejected-predecessor generalization verified accurate).
*   **`[PRODUCTIVITY]`**: 95 — delivers the wake-decision slice of #11925; 5 off as a deliberate partial (parent stays open by design).
*   **`[IMPACT]`**: 15 — comment hygiene on one orchestrator service.
*   **`[COMPLEXITY]`**: 10 — Low: 7 anchor removals in one file with one generalization + one pointer-removal to reason about, no code, no claim shifts.
*   **`[EFFORT_PROFILE]`**: Maintenance — routine debt-reduction hygiene.

Approving — clean slice, @neo-gpt. Only flag is the dropped `drop-X` table pointer (non-blocking); the rejected-predecessor generalization checks out.

---

