LearnNewsExamplesServices
Frontmatter
id11925
titleClean daemon script and config source comments
stateClosed
labels
documentationenhancementairefactoringarchitecturemodel-experience
assigneesneo-gpt
createdAtMay 24, 2026, 10:49 PM
updatedAtJun 7, 2026, 7:15 PM
githubUrlhttps://github.com/neomjs/neo/issues/11925
authorneo-gpt
commentsCount1
parentIssue11912
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtJun 2, 2026, 10:16 AM

Clean daemon script and config source comments

Closed v13.0.0/archive-v13-0-0-chunk-13 documentationenhancementairefactoringarchitecturemodel-experience
neo-gpt
neo-gpt commented on May 24, 2026, 10:49 PM

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

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

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

tobiu referenced in commit baa9bc3 - "chore(ai): clean diagnostic script comments (#11925) (#11947) on May 25, 2026, 7:24 AM
tobiu referenced in commit bbae867 - "chore(ai): clean tenant repo sync comments (#11925) (#11971) on May 25, 2026, 4:31 PM
tobiu referenced in commit c6dd0e3 - "chore(ai): clean bridge daemon comments (#11925) (#12056)" on May 27, 2026, 2:11 AM
tobiu referenced in commit 8b12fcb - "chore(ai): clean migration script comments (#11925) (#12128) on May 28, 2026, 9:36 AM
tobiu referenced in commit a3820db - "chore(ai): clean KB daemon comments (#11925) (#12282) on Jun 1, 2026, 8:52 AM
tobiu referenced in commit 643746b - "docs(ai): clean seed identity comments (#11925) (#12341) on Jun 2, 2026, 9:44 AM
tobiu referenced in commit 8c76d5d - "docs(ai): clean config template comments (#11925) (#12339) on Jun 2, 2026, 9:52 AM
tobiu referenced in commit dc6b7e1 - "docs(ai): clean defrag script comments (#11925) (#12340) on Jun 2, 2026, 9:52 AM
tobiu referenced in commit de10fd5 - "docs(ai): clean setup maintenance comments (#11925) (#12342) on Jun 2, 2026, 9:55 AM
tobiu referenced in commit 6cf55d0 - "docs(ai): clean maintenance client comments (#11925) (#12343) on Jun 2, 2026, 9:55 AM
tobiu referenced in commit 8033870 - "docs(ai): clean orchestrator recycle comments (#11925) (#12344) on Jun 2, 2026, 9:56 AM
tobiu referenced in commit c549bfa - "docs(ai): clean orchestrator bootstrap comments (#11925) (#12345) on Jun 2, 2026, 9:57 AM
tobiu referenced in commit e18e5b2 - "docs(ai): clean swarm heartbeat comments (#11925) (#12346) on Jun 2, 2026, 9:57 AM
tobiu referenced in commit c184f51 - "docs(ai): clean wake decision comments (#11925) (#12347) on Jun 2, 2026, 9:59 AM
tobiu referenced in commit 880eed9 - "docs(ai): clean swarm heartbeat service comments (#11925) (#12348) on Jun 2, 2026, 9:59 AM
tobiu referenced in commit d7d27f4 - "docs(ai): clean idle nudge comments (#11925) (#12349) on Jun 2, 2026, 10:02 AM
tobiu referenced in commit 86c9c25 - "docs(ai): clean rebucket archive comments (#11925) (#12350) on Jun 2, 2026, 10:02 AM
tobiu referenced in commit 960739f - "docs(ai): clean retired primitive comments (#11925) (#12351) on Jun 2, 2026, 10:04 AM
tobiu referenced in commit 5a4be7f - "docs(ai): clean chroma backfill comments (#11925) (#12352) on Jun 2, 2026, 10:05 AM
tobiu referenced in commit 3146dae - "docs(ai): clean sync workflow comments (#11925) (#12353)" on Jun 2, 2026, 10:05 AM
tobiu referenced in commit 0505292 - "docs(ai): clean benchmark comments (#11925) (#12354) on Jun 2, 2026, 10:05 AM
tobiu referenced in commit 80c298e - "docs(ai): clean lint manifest comments (#11925) (#12355) on Jun 2, 2026, 10:07 AM
tobiu referenced in commit 5dbee8d - "docs(ai): clean restore comments (#11925) (#12356) on Jun 2, 2026, 10:08 AM
tobiu referenced in commit 7f95a18 - "docs(ai): clean lint agents comments (#11925) (#12357) on Jun 2, 2026, 10:09 AM
tobiu referenced in commit b4d4a77 - "docs(ai): clean bootstrap comments (#11925) (#12358) on Jun 2, 2026, 10:09 AM
tobiu referenced in commit f43876a - "docs(ai): clean mcp config comments (#11925) (#12359) on Jun 2, 2026, 10:13 AM
tobiu referenced in commit e0a03da - "docs(ai): clean runner comments (#11925) (#12360) on Jun 2, 2026, 10:14 AM
tobiu referenced in commit 54165b1 - "docs(ai): clean backup comments (#11925) (#12361) on Jun 2, 2026, 10:16 AM
tobiu closed this issue on Jun 2, 2026, 10:16 AM
tobiu referenced in commit b3265cb - "docs(ai): clean resume harness comments (#11925) (#12362) on Jun 2, 2026, 10:16 AM
tobiu referenced in commit 4221f9d - "docs(ai): clean inflight lock comments (#11925) (#12364) on Jun 2, 2026, 10:16 AM
tobiu referenced in commit b610d30 - "docs(ai): clean sunset detector comments (#11925) (#12363) on Jun 2, 2026, 10:17 AM
tobiu referenced in commit 5bbbf80 - "docs(ai): consolidate remaining comment cleanup (#11925) (#12366) on Jun 2, 2026, 10:17 AM
tobiu referenced in commit 9e309e7 - "feat(ci): require a Resolves #N in agent PR bodies; forbid Closes/Fixes (#12367) (#12368) on Jun 2, 2026, 6:01 PM