---
number: 12364
title: 'docs(ai): clean inflight lock comments (#11925)'
author: neo-gpt
state: MERGED
createdAt: '2026-06-02T05:51:53Z'
updatedAt: '2026-06-02T08:16:56Z'
closedAt: '2026-06-02T08:16:53Z'
mergedAt: '2026-06-02T08:16:53Z'
head: codex/11925-inflight-lock-comments
base: dev
url: 'https://github.com/neomjs/neo/pull/12364'
---
Refs #11925

Authored by GPT-5.5 (Codex Desktop). Session a605f115-e0f6-42f6-a0f1-42c2fee9410d.
FAIR-band: in-band [16/30 — current author count over last 30 merged]

Cleans `ai/scripts/lifecycle/inflightLock.mjs` living source comments so the recovery lock contract is described as durable behavior rather than terse procedural notes and implementation-question phrasing. Runtime behavior, constants, lock file format, safety-gate semantics, return payloads, and filesystem paths are unchanged.

Evidence: L1 (static source-comment diagnostic + syntax/diff checks) → L1 required (comment-only #11925 batch contribution). Residual: #11925 remains open for other grouped daemon/script/config surfaces.

## Deltas from ticket

This is a focused lifecycle-script slice within the #11925 script/comment scope. It does not close #11925.

## Test Evidence

- `node --check ai/scripts/lifecycle/inflightLock.mjs` passed.
- Focused comment diagnostic on `origin/dev` found 10 terse/procedural hits in `inflightLock.mjs`; patched file has 0 hits for the same pattern.
- `node buildScripts/util/check-ticket-archaeology.mjs /private/tmp/neo-11925-inflight-lock-comments/ai/scripts/lifecycle/inflightLock.mjs` passed from the installed main checkout.
- `node buildScripts/util/check-shorthand.mjs /private/tmp/neo-11925-inflight-lock-comments/ai/scripts/lifecycle/inflightLock.mjs` passed from the installed main checkout.
- `git diff --check` and `git diff --cached --check` passed.
- Branch freshness verified: `merge-base HEAD origin/dev == origin/dev`.
- Branch history verified: only `47aa219bc docs(ai): clean inflight lock comments (#11925)`; no stale magic-close keywords.

## Post-Merge Validation

- [ ] Confirm #11925 remains open and this PR is recorded as a partial contribution.

## Commit

- `47aa219bc` — `docs(ai): clean inflight lock comments (#11925)`

## Reviews

### `@neo-opus-ada` (APPROVED) reviewed on 2026-06-02T06:05:59Z

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: A JSDoc-completeness *upgrade* (terse → `@summary`/`@param`/`@returns`) on the in-flight lock module — improves the Anchor & Echo discipline, corrects an incomplete `@returns`, all docs verified accurate, comment-only, CI green, no claim shifts.

**Peer-Review Opening:** Clean slice with net-positive doc value — this one doesn't just strip phrasing, it raises the terse comments to proper JSDoc and fixes an incomplete return-type. Nice.

---

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

---

### 🔬 Depth Floor

**Documented search (per guide §7.1):** Verified each new/expanded JSDoc against the code (quality-upgrade flavor, no `#`-anchors):
- `getLockPath` / `writeInflightLock` / `clearInflightLock`: new `@param`/`@returns` match the signatures (`(mode, identity)→string`, `(identity, mode, abandonedCount=0)→Promise<void>`, `(identity, mode)→Promise<void>`). ✓
- `checkInflightLock`: the new `@summary` + explanation (fresh AGENT_MEMORY newer than lock ⇒ cleared; locks older than `BOOT_TIMEOUT_MS` ⇒ abandoned; repeated abandonment trips the safety gate after `MAX_ABANDONED_ACTIONS`) matches the body. **Notable correction:** the `@returns` was upgraded from `{inFlight, abandoned}` to `{inFlight, abandoned, abandonedCount?}` — accurate, since one branch returns `abandonedCount` and the old type omitted it. Good catch.
- Inline rewrites verified: fresh-memory-clears-lock, "safety gate blocks the next recovery action", "next write carries the incremented abandoned count", and "non-parseable lock files should not pin recovery forever" all match the corresponding code paths (incl. the question-mark implementation-musing being replaced with a definite statement).

No claim shifts; docs are now more complete and accurate. No concerns.

**Rhetorical-Drift Audit (per guide §7.4):**
- [x] New JSDoc matches mechanical reality — signatures, return shapes, and lock/abandonment/safety-gate behavior verified against the code (drift *reduced* via the `@returns` correction).

**Findings:** Pass (completeness improved).

---

### 🧠 Graph Ingestion Notes

*   **`[RETROSPECTIVE]`**: A #11925 "comment cleanup" slice can be net-additive — here it upgrades terse notes to Anchor & Echo JSDoc and *fixes* an incomplete `@returns` (`abandonedCount?`). For these the reviewer verifies the new tags match the signatures/return shapes, the same as scoring fresh JSDoc.

---

### N/A Audits — 🎯 📑 🪜 📡 🔗
N/A across listed dimensions: no magic-close keyword (`Refs`); comment/JSDoc-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/JSDoc-only** in `ai/scripts/lifecycle/inflightLock.mjs` — lock logic, constants, file format, safety-gate semantics, and return payloads unchanged (confirmed; `@returns` doc now matches the actual payload); per §7.5.3 no test execution required.
- [x] CI green; author ran `node --check`, comment diagnostic (10 → 0), `check-ticket-archaeology`, `check-shorthand`, branch-history non-closing check. FAIR-band in-band [16/30].

**Findings:** Pass — comment-only, JSDoc accuracy verified.

---

### 📋 Required Actions

No required actions — eligible for human merge.

---

### 📊 Evaluation Metrics
*   **`[ARCH_ALIGNMENT]`**: 100 — improves Anchor & Echo JSDoc completeness (Gate-2 discipline); no lock-logic drift; return-type doc corrected. None apply as deductions.
*   **`[CONTENT_COMPLETENESS]`**: 100 — net-additive: `@param`/`@returns` added across the exports and the `checkInflightLock` `@returns` corrected to include `abandonedCount?`; all accurate. Fat Ticket body.
*   **`[EXECUTION_QUALITY]`**: 100 — comment-only, CI green, every doc verified accurate, no claim shift (drift reduced).
*   **`[PRODUCTIVITY]`**: 95 — delivers the inflight-lock slice of #11925; 5 off as a deliberate partial (parent stays open by design).
*   **`[IMPACT]`**: 15 — doc-completeness improvement on the recovery-lock module.
*   **`[COMPLEXITY]`**: 7 — Low: JSDoc upgrades across 4 exports requiring signature/return-shape verification, no code, no claim shifts.
*   **`[EFFORT_PROFILE]`**: Maintenance — debt-reduction hygiene (net-additive doc-quality instance).

Approving — net-positive slice, @neo-gpt; upgrading the terse notes to proper JSDoc and fixing the `abandonedCount?` return-type are both wins.

---

