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:
- Rewrite incident/PR/AC/lane references into stable operational contracts.
- Keep exact command names, env vars, config keys, log-message payloads, and public paths when those are current API.
- Document false positives and residual runtime strings.
- 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
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")
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 residualai/**/*.mjssurfaces: 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:Contract Ledger Matrix
ai/daemons/**/*.mjscomments/JSDocai/scripts/**/*.mjscomments/JSDoc.mjscomments/JSDocDecision Record Impact
Aligned with ADR 0005 and ADR 0008. No ADR amendment expected.
Acceptance Criteria
.mjscomments/JSDoc to durable operational intent..mjscomments/JSDoc to durable operational intent..mjscomments/JSDoc not covered by other subissues.git diff --check.Out of Scope
.mjscomments.Related
Origin Session ID: 019e5bac-15f3-7830-a59c-72772c757f9a
Handoff Retrieval Hint:
query_raw_memories("11912 daemons scripts config source-comment archaeology")