Authored by Claude Opus 4.7 (Claude Code). Session 5572d9a5-558d-4bea-b416-e31496c289c4.

FAIR-band: in-band [verify @ merge-gate]

Resolves #11848

Summary

Sub 12 (final) of Epic #11831 — collapses buildScripts/ai/ (19 files) into ai/scripts/<cat>/ mirroring Sub 11's thematic structure. The "build vs ai" split was historical-random; neither folder mapped to genuine build-pipeline boundaries. After this Sub, buildScripts/ai/ directory deleted entirely; buildScripts/ reverts to apps/release/util only.

Evidence: L1 (moved-spec subsuites 220/220 pass; 1995 pass / 21 pre-existing flakes on full unit; zero refs to moved files in failures) → L1 required for substrate refactor.

Source moves (19)

• maintenance/ (12): backup, buildKbAgentFaqs, defragChromaDB, defragSQLiteDB, downloadKnowledgeBase, ingestTenant, kbPushClient, recreateGraphDb, restore, syncGithubWorkflow, syncKnowledgeBase, uploadKnowledgeBase
• migrations/ (1): migrateMemoryCore
• diagnostics/ (1): mcpHealthcheck
• runners/ (4): roadmapPlanner, runAgent, runGoldenPath, runSandman
• setup/ (1): initServerConfigs

buildScripts/ai/ directory removed.

Test moves (12)

Mirror source by category. One pre-existing spec util/check-chore-sync.spec.mjs tests buildScripts/util/check-chore-sync.mjs (non-AI) — left in place as out-of-scope for Sub 12.

External consumer rewrites (34 files)

Substring sweep buildScripts/ai/X.mjs → ai/scripts/<cat>/X.mjs applied to:

• package.json: 16 npm script paths (ticket listed 11; actual count 16 including prepare hook + ai:sync-github-workflow + ai:sync-kb)
• ai/deploy/docker-compose.yml: 2 paths
• 2 integration specs (BackupRestoreWipe, KBBackupRestoreWipe)
• ai/daemons/orchestrator/{Orchestrator,TaskDefinitions}.mjs
• ai/services/knowledge-base/DatabaseService + memory-core variant
• Multiple unit specs

Manual V-B-A fixes (sweep-missed patterns)

Composite of lessons from Subs 9/10/11:

• TaskDefinitions.mjs kbSync + backup args: refactored awkward path.resolve(scriptDir, '../../ai/scripts/maintenance/X') → path.join(scriptDir, 'maintenance', 'X') for consistency with Sub-11's summary pattern. Matching daemon.spec.mjs assertions updated.
• laneCManualScriptLeaseAdoption.spec: refactored single scriptDir variable (was 'buildScripts/ai' literal) into per-file path map because tests span maintenance/ + runners/ categories. Updated HML import regex + substring assertions for new '../../daemons/orchestrator/services/...' source path. Added explicit Neo + core imports (latent cross-spec coupling exposed by isolated-worker location, like sweepExpiredTasks in Sub 11).
• peer-architecture.spec: REPO_ROOT depth +1; regex updated from ai\/services\.mjs → \/services\.mjs (source now uses '../../services.mjs' not '.../ai/services.mjs').
• restore-hardening.spec: repoRoot path.resolve depth +1.
• Doc-string updates: 19 @module buildScripts/ai/X annotations + 3 test.describe('buildScripts/ai/...') strings rewritten for new paths.

V-B-A composite lesson (logged through Subs 9/10/11/12)

Cross-cutting folder moves need ALL of:

1. Substring sweep for explicit path strings in imports / regex literals
2. Relative-path proximity grep for paths missing the literal source-folder segment
3. path.join(scriptDir, X) audit for filename-as-arg patterns that bypass substring sweeps
4. Isolated-worker Neo-import check for cross-spec coupling (specs that relied on sibling-spec transitive Neo loading)
5. Doc-string + describe-name cleanup for non-code references that won't break runtime but indicate stale shape-of-mind

Test Evidence

• Moved-spec subsuites (maintenance/ + runners/ + diagnostics/ + setup/ + orchestrator/): 220/220 pass
• Full unit suite: 1995 pass / 21 fail / 2 skip / 24 did-not-run. All 21 failures verified pre-existing flakes (Authorization, checkAllAgentIdle×2, checkSunsetted×5, resumeHarness, trioWakeCooldown, QueryReRanker, SessionSummarization, TextEmbeddingService.retry, WriteSideInvariant, grid×7, Teleportation×2); zero references to moved files in any failure.

Post-Merge Validation

• Operator runs npm run ai:backup / ai:restore / ai:sync-kb etc. (16 npm scripts touched) — verify entry paths resolve
• Orchestrator restart — kbSync + backup task spawns via new ai/scripts/maintenance/ paths
• Integration tests pass on dev
• Docker compose still boots with new ai/scripts/maintenance/initServerConfigs.mjs path

Deltas from ticket

• npm scripts: ticket listed 11; actual update was 16 (also includes prepare, ai:sync-github-workflow, ai:sync-kb)
• Doc-string updates: ticket didn't enumerate @module annotations or test.describe strings — both updated for substrate hygiene
• TaskDefinitions cleanup: ticket didn't mandate the path.join(scriptDir, 'maintenance', X) refactor but I applied it for consistency with Sub-11's summary pattern. Functionally equivalent to the awkward path.resolve(scriptDir, '../../ai/scripts/maintenance/X') form, cleaner to read.

Depends on

• Sub 8 #11844 ✓ merged
• Sub 9 #11845 ✓ merged
• Sub 10 #11846 ✓ merged
• Sub 11 #11847 ✓ merged

Closes Epic

After this Sub merges, Epic #11831 is complete. Folder structure:

• ai/daemons/orchestrator/ — masterclass refactor + cluster co-location (Subs 1/8)
• ai/daemons/{bridge,kb-alerting,kb-gc,kb-reconciliation}/ — per-daemon co-location (Sub 9)
• ai/services/{graph,ingestion}/ — cross-daemon services bucket (Sub 10)
• ai/scripts/{lifecycle,migrations,diagnostics,setup,lint,maintenance,runners}/ — thematic split (Subs 11/12)
• buildScripts/ — genuine build-pipeline only

Per @tobiu's "you and me" instruction: no peer-review broadcast on this lane.