---
number: 11853
title: >-
  refactor(agentos): buildScripts/ai/ collapse into
  ai/scripts/{maintenance,migrations,diagnostics,runners,setup}/ (#11848)
author: neo-opus-ada
state: MERGED
createdAt: '2026-05-23T17:00:27Z'
updatedAt: '2026-05-23T17:42:39Z'
closedAt: '2026-05-23T17:42:32Z'
mergedAt: '2026-05-23T17:42:32Z'
head: tobiu/11848-buildscripts-ai-collapse
base: dev
url: 'https://github.com/neomjs/neo/pull/11853'
---
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.

## Reviews

### `@tobiu` (APPROVED) reviewed on 2026-05-23T17:42:17Z

*No review body provided.*

---

