---
id: 11925
title: Clean daemon script and config source comments
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - refactoring
  - architecture
  - model-experience
assignees:
  - neo-gpt
createdAt: '2026-05-24T20:49:10Z'
updatedAt: '2026-06-07T17:15:24Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11925'
author: neo-gpt
commentsCount: 1
parentIssue: 11912
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-06-02T08:16:29Z'
---
# Clean daemon script and config source comments

Parent epic: #11912

## Context

#11912 is being reshaped into an epic with grouped cleanup subissues. This subissue owns daemon, lifecycle-script, maintenance-script, config-template, and residual `ai/` source-comment surfaces not covered by the service-group subissues.

Current grouped baseline on `origin/dev`:

- `ai/scripts/**/*.mjs`: 96 diagnostic matches.
- `ai/daemons/**/*.mjs`: 50 diagnostic matches.
- `ai/config*.mjs`, MCP config templates outside the service-owned groups, and residual `ai/**/*.mjs` surfaces: remaining high-noise matches after the Memory Core, KB/Graph, and GitHub/shared groups are accounted for.

## The Problem

Daemon and script comments often preserve incident history, PR lanes, or AC references directly in executable source. Config templates also accumulate release-era rationale that should be expressed as stable operator-facing contracts.

## The Architectural Reality

This group covers long-running process entry points, bridge/wake/KB daemons, migration and maintenance scripts, lint/diagnostic utilities, and residual config templates. These surfaces are operationally sensitive: comments should tell agents and operators what the script/daemon/config owns now, not which historical lane produced it.

## The Fix

Clean daemon, script, config-template, and residual `ai/` source comments in grouped batches:

1. Rewrite incident/PR/AC/lane references into stable operational contracts.
2. Keep exact command names, env vars, config keys, log-message payloads, and public paths when those are current API.
3. Document false positives and residual runtime strings.
4. If a residual file belongs more naturally to another subissue during cleanup, move it by comment on #11912 rather than creating a per-file ticket.

## Contract Ledger Matrix

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| `ai/daemons/**/*.mjs` comments/JSDoc | #11912 source-comment cleanup epic | Comments explain daemon ownership, lifecycle, and failure modes in stable terms | Preserve operator-visible runtime strings | PR bodies | Before/after focused diagnostics |
| `ai/scripts/**/*.mjs` comments/JSDoc | #11912 source-comment cleanup epic | Comments explain script contracts, inputs, and safety gates without lane archaeology | File separate bug ticket for executable issues found during cleanup | PR bodies | Before/after focused diagnostics |
| Config/residual `.mjs` comments/JSDoc | #11912 source-comment cleanup epic | Comments explain stable config/operator contracts | Reassign to a sibling subissue if a residual file belongs there | PR bodies | Before/after focused diagnostics |

## Decision Record Impact

Aligned with ADR 0005 and ADR 0008. No ADR amendment expected.

## Acceptance Criteria

- [ ] Clean daemon `.mjs` comments/JSDoc to durable operational intent.
- [ ] Clean script `.mjs` comments/JSDoc to durable operational intent.
- [ ] Clean config-template and residual `.mjs` comments/JSDoc not covered by other subissues.
- [ ] Preserve runtime behavior, command names, env vars, config keys, and public paths.
- [ ] PR evidence includes before/after focused counts and `git diff --check`.
- [ ] Parent #11912 remains open until all grouped subissues are complete.

## Out of Scope

- Service groups covered by the Memory Core, KB/Graph, and GitHub/shared subissues.
- Runtime behavior changes.
- Generated mirrors and historical docs outside source `.mjs` comments.

## Related

- Parent epic: #11912

Origin Session ID: 019e5bac-15f3-7830-a59c-72772c757f9a

Handoff Retrieval Hint: `query_raw_memories("11912 daemons scripts config source-comment archaeology")`

## Timeline

- 2026-05-24T20:49:11Z @neo-gpt added the `documentation` label
- 2026-05-24T20:49:11Z @neo-gpt added the `enhancement` label
- 2026-05-24T20:49:11Z @neo-gpt added the `ai` label
- 2026-05-24T20:49:11Z @neo-gpt added the `refactoring` label
- 2026-05-24T20:49:11Z @neo-gpt added the `architecture` label
- 2026-05-24T20:49:11Z @neo-gpt added the `model-experience` label
- 2026-05-24T20:49:57Z @neo-gpt added parent issue #11912
- 2026-05-24T21:08:30Z @neo-gpt cross-referenced by #11912
- 2026-05-25T01:23:44Z @neo-gpt assigned to @neo-gpt
- 2026-05-25T01:26:43Z @neo-gpt cross-referenced by PR #11947
- 2026-05-25T02:03:19Z @neo-gpt cross-referenced by #11924
- 2026-05-25T02:11:32Z @neo-opus-ada cross-referenced by PR #11949
- 2026-05-25T05:24:46Z @tobiu referenced in commit `baa9bc3` - "chore(ai): clean diagnostic script comments (#11925) (#11947)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-25T12:05:21Z @neo-gpt cross-referenced by PR #11971
- 2026-05-25T14:31:14Z @tobiu referenced in commit `bbae867` - "chore(ai): clean tenant repo sync comments (#11925) (#11971)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-26T23:33:36Z @neo-gpt cross-referenced by PR #12056
- 2026-05-26T23:56:56Z @neo-opus-ada cross-referenced by PR #12057
- 2026-05-27T00:11:46Z @tobiu referenced in commit `c6dd0e3` - "chore(ai): clean bridge daemon comments (#11925) (#12056)"
### @neo-gpt - 2026-05-28T06:19:11Z

**Input from GPT-5 (Codex Desktop):**

> ● ## Ticket Intake Classification — migration-script residual batch
> 
> Verdict: `valid-as-written`; ROI positive for a focused residual cleanup batch.
> 
> Evidence before branch/code work:
> - Live issue metadata: OPEN, assigned to `neo-gpt`, created `2026-05-24T20:49:10Z`, updated `2026-05-25T01:23:44Z`; no `stale` / `no auto close` labels. Age state: `pre-stale` under `.github/workflows/close-inactive-issues.yml` (`90d` stale + `14d` close).
> - Parent epic #11912 has prior @neo-gpt epic-review: https://github.com/neomjs/neo/issues/11912#issuecomment-4529966118.
> - Prior #11925 contributions are merged (#11947, #11971, #12056), but current `dev` still has residual script/comment archaeology candidates.
> - KB ticket query still fails with `Internal error: Error finding id`; fallback evidence used live GitHub search, current source diagnostics, Memory Core, and the local issue corpus.
> - Duplicate / close-link sweep: live search found no newer replacement issue; existing merged PRs are partial grouped contributions, not full closeout.
> - Current focused diagnostic over `ai/scripts/{migrations,maintenance,setup,lifecycle}` finds residual ticket/phase anchors. This batch will target migration-script comments where the anchors are historical rather than current user-facing contract.
> 
> Boundary: comment/JSDoc-only cleanup; preserve runtime behavior, command names, env vars, config keys, log-message payloads, public paths, and intentional runtime strings.
> 
> Branch: `codex/11925-migration-script-comments`.
> 
> lane-state: next-lane (working #11925 migration-script residual comments).

- 2026-05-28T06:23:02Z @neo-gpt cross-referenced by PR #12128
- 2026-05-28T07:36:16Z @tobiu referenced in commit `8b12fcb` - "chore(ai): clean migration script comments (#11925) (#12128)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-01T01:05:12Z @neo-gpt cross-referenced by PR #12282
- 2026-06-01T06:52:44Z @tobiu referenced in commit `a3820db` - "chore(ai): clean KB daemon comments (#11925) (#12282)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T02:29:15Z @neo-gpt cross-referenced by PR #12339
- 2026-06-02T02:43:46Z @neo-gpt cross-referenced by PR #12340
- 2026-06-02T02:49:33Z @neo-gpt cross-referenced by PR #12341
- 2026-06-02T03:00:27Z @neo-gpt cross-referenced by PR #12342
- 2026-06-02T03:15:07Z @neo-gpt cross-referenced by PR #12343
- 2026-06-02T03:20:52Z @neo-gpt cross-referenced by PR #12344
- 2026-06-02T03:31:24Z @neo-gpt cross-referenced by PR #12345
- 2026-06-02T03:38:17Z @neo-gpt cross-referenced by PR #12346
- 2026-06-02T03:43:46Z @neo-gpt cross-referenced by PR #12347
- 2026-06-02T03:49:50Z @neo-gpt cross-referenced by PR #12348
- 2026-06-02T03:58:17Z @neo-gpt cross-referenced by PR #12349
- 2026-06-02T04:12:00Z @neo-gpt cross-referenced by PR #12350
- 2026-06-02T04:15:36Z @neo-gpt cross-referenced by PR #12351
- 2026-06-02T04:24:36Z @neo-gpt referenced in commit `05c5ff4` - "docs(ai): restore rebucket archive EOF newline (#11925)"
- 2026-06-02T04:24:41Z @neo-gpt referenced in commit `6a970b4` - "docs(ai): restore retired primitive EOF newline (#11925)"
- 2026-06-02T04:24:47Z @neo-gpt referenced in commit `d667f19` - "docs(ai): restore chroma backfill EOF newline (#11925)"
- 2026-06-02T04:26:25Z @neo-gpt cross-referenced by PR #12352
- 2026-06-02T04:31:15Z @neo-gpt cross-referenced by PR #12353
- 2026-06-02T04:40:15Z @neo-gpt cross-referenced by PR #12354
- 2026-06-02T04:42:50Z @neo-gpt cross-referenced by PR #12355
- 2026-06-02T04:48:44Z @neo-gpt cross-referenced by PR #12356
- 2026-06-02T04:52:38Z @neo-gpt referenced in commit `2e54c11` - "docs(ai): clean benchmark provenance comments (#11925)"
- 2026-06-02T05:01:30Z @neo-gpt cross-referenced by PR #12357
- 2026-06-02T05:06:25Z @neo-gpt cross-referenced by PR #12358
- 2026-06-02T05:15:16Z @neo-gpt cross-referenced by PR #12359
- 2026-06-02T05:19:38Z @neo-gpt cross-referenced by PR #12360
- 2026-06-02T05:27:17Z @neo-gpt cross-referenced by PR #12361
- 2026-06-02T05:39:32Z @neo-gpt cross-referenced by PR #12362
- 2026-06-02T05:44:49Z @neo-gpt cross-referenced by PR #12363
- 2026-06-02T05:51:54Z @neo-gpt cross-referenced by PR #12364
- 2026-06-02T06:27:44Z @neo-gpt cross-referenced by PR #12365
- 2026-06-02T06:53:13Z @neo-gpt cross-referenced by PR #12366
- 2026-06-02T07:44:06Z @tobiu referenced in commit `643746b` - "docs(ai): clean seed identity comments (#11925) (#12341)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T07:52:17Z @tobiu referenced in commit `8c76d5d` - "docs(ai): clean config template comments (#11925) (#12339)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T07:52:57Z @tobiu referenced in commit `dc6b7e1` - "docs(ai): clean defrag script comments (#11925) (#12340)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T07:55:23Z @tobiu referenced in commit `de10fd5` - "docs(ai): clean setup maintenance comments (#11925) (#12342)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T07:55:46Z @tobiu referenced in commit `6cf55d0` - "docs(ai): clean maintenance client comments (#11925) (#12343)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T07:56:22Z @tobiu referenced in commit `8033870` - "docs(ai): clean orchestrator recycle comments (#11925) (#12344)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T07:57:07Z @tobiu referenced in commit `c549bfa` - "docs(ai): clean orchestrator bootstrap comments (#11925) (#12345)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T07:57:34Z @tobiu referenced in commit `e18e5b2` - "docs(ai): clean swarm heartbeat comments (#11925) (#12346)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T07:59:28Z @tobiu referenced in commit `c184f51` - "docs(ai): clean wake decision comments (#11925) (#12347)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T07:59:51Z @tobiu referenced in commit `880eed9` - "docs(ai): clean swarm heartbeat service comments (#11925) (#12348)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T08:02:19Z @tobiu referenced in commit `d7d27f4` - "docs(ai): clean idle nudge comments (#11925) (#12349)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T08:02:43Z @tobiu referenced in commit `86c9c25` - "docs(ai): clean rebucket archive comments (#11925) (#12350)

* docs(ai): clean rebucket archive comments (#11925)

* docs(ai): restore rebucket archive EOF newline (#11925)"
- 2026-06-02T08:04:17Z @neo-opus-ada cross-referenced by #12367
- 2026-06-02T08:04:26Z @tobiu referenced in commit `960739f` - "docs(ai): clean retired primitive comments (#11925) (#12351)

* docs(ai): clean retired primitive comments (#11925)

* docs(ai): restore retired primitive EOF newline (#11925)"
- 2026-06-02T08:05:04Z @tobiu referenced in commit `5a4be7f` - "docs(ai): clean chroma backfill comments (#11925) (#12352)

* docs(ai): clean chroma backfill comments (#11925)

* docs(ai): restore chroma backfill EOF newline (#11925)"
- 2026-06-02T08:05:30Z @tobiu referenced in commit `3146dae` - "docs(ai): clean sync workflow comments (#11925) (#12353)"
- 2026-06-02T08:05:59Z @tobiu referenced in commit `0505292` - "docs(ai): clean benchmark comments (#11925) (#12354)

* docs(ai): clean benchmark comments (#11925)

* docs(ai): clean benchmark provenance comments (#11925)

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T08:07:51Z @tobiu referenced in commit `80c298e` - "docs(ai): clean lint manifest comments (#11925) (#12355)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T08:08:33Z @tobiu referenced in commit `5dbee8d` - "docs(ai): clean restore comments (#11925) (#12356)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T08:09:06Z @tobiu referenced in commit `7f95a18` - "docs(ai): clean lint agents comments (#11925) (#12357)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T08:09:38Z @tobiu referenced in commit `b4d4a77` - "docs(ai): clean bootstrap comments (#11925) (#12358)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T08:13:43Z @tobiu referenced in commit `f43876a` - "docs(ai): clean mcp config comments (#11925) (#12359)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T08:14:25Z @tobiu referenced in commit `e0a03da` - "docs(ai): clean runner comments (#11925) (#12360)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T08:14:30Z @neo-opus-ada cross-referenced by PR #12368
- 2026-06-02T08:16:01Z @tobiu referenced in commit `54165b1` - "docs(ai): clean backup comments (#11925) (#12361)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T08:16:29Z @tobiu closed this issue
- 2026-06-02T08:16:29Z @tobiu referenced in commit `b3265cb` - "docs(ai): clean resume harness comments (#11925) (#12362)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T08:16:55Z @tobiu referenced in commit `4221f9d` - "docs(ai): clean inflight lock comments (#11925) (#12364)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T08:17:27Z @tobiu referenced in commit `b610d30` - "docs(ai): clean sunset detector comments (#11925) (#12363)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T08:17:51Z @tobiu referenced in commit `5bbbf80` - "docs(ai): consolidate remaining comment cleanup (#11925) (#12366)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T08:21:42Z @neo-opus-ada referenced in commit `6027de4` - "feat(ci): require a Resolves #N in agent PR bodies; forbid Closes/Fixes (#12367)

agent-pr-body-lint.yml previously accepted any of Resolves|Closes|Fixes|Related:|Refs
#N as the ticket reference. That let a single ticket be fragmented across many PRs
(each `Refs #N`, none resolving it) — the gap that produced ~27 PRs for the one
ticket #11925.

Strengthen the check so every agent/`ai` PR body MUST contain at least one
`Resolves #N` — the only sanctioned closing keyword (= delivered work). This
mechanically enforces the 1-PR-per-ticket model: a ticket that needs N PRs cannot
have N valid `Resolves`, so it must become an epic + subs or be split.

- `Closes #N` is now forbidden: Closes = closed-without-delivery (not-planned /
  superseded / dropped) -> that outcome needs no PR.
- `Fixes #N` is now forbidden: ambiguous; use `Resolves`.
- `Refs #N` / `Related: #N` remain allowed as additional references, and multiple
  `Resolves` lines are fine — but they no longer satisfy the requirement alone.

Also syncs pull-request-workflow.md §3.3 (close-keyword policy) + the Epic
Close-Target Ban + the branch-history hygiene note to match the enforced rule.

Co-Authored-By: neo-opus-4-7 <neo-opus-4-7@neomjs.com>"
- 2026-06-02T16:01:54Z @tobiu referenced in commit `9e309e7` - "feat(ci): require a Resolves #N in agent PR bodies; forbid Closes/Fixes (#12367) (#12368)

* feat(ci): require a Resolves #N in agent PR bodies; forbid Closes/Fixes (#12367)

agent-pr-body-lint.yml previously accepted any of Resolves|Closes|Fixes|Related:|Refs
#N as the ticket reference. That let a single ticket be fragmented across many PRs
(each `Refs #N`, none resolving it) — the gap that produced ~27 PRs for the one
ticket #11925.

Strengthen the check so every agent/`ai` PR body MUST contain at least one
`Resolves #N` — the only sanctioned closing keyword (= delivered work). This
mechanically enforces the 1-PR-per-ticket model: a ticket that needs N PRs cannot
have N valid `Resolves`, so it must become an epic + subs or be split.

- `Closes #N` is now forbidden: Closes = closed-without-delivery (not-planned /
  superseded / dropped) -> that outcome needs no PR.
- `Fixes #N` is now forbidden: ambiguous; use `Resolves`.
- `Refs #N` / `Related: #N` remain allowed as additional references, and multiple
  `Resolves` lines are fine — but they no longer satisfy the requirement alone.

Also syncs pull-request-workflow.md §3.3 (close-keyword policy) + the Epic
Close-Target Ban + the branch-history hygiene note to match the enforced rule.

Co-Authored-By: neo-opus-4-7 <neo-opus-4-7@neomjs.com>

* docs(pr-review): sync Resolves-only close-target audit (#12367)

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"

