ADR-021: Bilko Blueprint Section 15 Realignment

# ADR-021: Bilko Blueprint Section 15 Realignment

Status: Accepted
Date: 2026-04-29
Authors: ALAI (CEO Alem Basic, AI Director John)
Context: MC #10034 Phases 6-7

## Context

Bilko had drifted from ALAI Universal Blueprint Section 15. Audit revealed: 384 dirty WT entries
(now archived), 29 unmerged branches (now archive tags), 3 sibling worktree clones, backend at
`backend/` (blueprint expects `apps/api/`), country packages named `country-*` (blueprint expects
`domain-*`), root contained ~33 entries (blueprint allows ~10).

CEO approved scorched-earth-lite cleanup 2026-04-28. PR #1 + PR #2 fixed CI prerequisite.
FlowForge executed Phases 0-5.

## Decision

Full Section 15 realignment in Phases 6-7:

- DELETE: `apps/api-kotlin-abandoned/`, `scratch-api/` (untracked build artifacts)
- MOVE: `backend/` → `apps/api/` (Kotlin/Ktor canonical backend)
- RENAME: `apps/api/` (Express) → `apps/api-express/` (Express active, migration pending)
- ARCHIVE: `apps/api-legacy/` → `.archive/api-legacy/`
- SKIP: `landing/` → `apps/landing/` — no git-tracked files in landing/ (only node_modules, out)
- MOVE: `cloudbuild.yaml` → `infrastructure/gcp/cloudbuild.yaml`
- MOVE: `docker-compose.test.yml` → `infrastructure/docker/docker-compose.test.yml`
- MOVE: `.ci/config.yml` → `scripts/ci/alai-ci-config.yml`
- MOVE: `ci/stubs/` → `tools/ci-stubs/`
- MOVE: `audit-2026-04-28/` → `docs/audits/2026-04-28/`
- MOVE: `COMPLAINT-REPORT-2026-02-20.md` → `docs/audits/`
- MOVE: `DEPLOY-MAP.md` → `docs/DEPLOY-MAP.md`
- MOVE: `figma-plugin/` → `tools/figma-plugin/`
- MOVE: `design/` → `docs/design/design/` (double-nested by git mv into existing docs/design/)
- MOVE: `branding/` → `docs/branding/branding/` (double-nested similarly)
- RENAME: `packages/country-{ba,ba-fed,ba-rs,hr,rs}` → `packages/domain-{ba,ba-fed,ba-rs,hr,rs}`

## Path Reference Updates (Phase 7)

All active code paths updated:

- `infrastructure/docker/Dockerfile.api` — updated `apps/api` → `apps/api-express`, `country-*` → `domain-*`
- `infrastructure/docker/Dockerfile.api-legacy` — updated `apps/api-legacy` → `.archive/api-legacy`, `country-*` → `domain-*`
- `apps/web/Dockerfile` — updated `apps/api-legacy` → `apps/api-express`, `packages/country-*` → `packages/domain-*`
- `apps/api-express/package.json` — renamed to `@bilko/api-express`, deps `@bilko/country-*` → `@bilko/domain-*`
- `apps/api-express/vitest.config*.ts` — all path aliases updated to `domain-*`
- `apps/api-express/src/**/*.ts` — all `@bilko/country-*` imports → `@bilko/domain-*`
- `apps/api-express/tests/**/*.ts` — all `@bilko/country-*` imports → `@bilko/domain-*`
- `packages/domain-*/src/index.ts`, `README.md` — all self-references updated
- `packages/README.md` — updated `country-*` → `domain-*`
- `src/shared/ubl/*.ts` — comment references updated
- `.github/workflows/gcp-deploy.yml.disabled` — path filter `backend/**` → `apps/api/**`
- `BUILD-BLUEPRINT.md` — Section 2 (tech stack), Section 3 (project structure), Section 8 (rules)
- `CLAUDE.md` (root) — project structure and backend status sections
- `.gitleaks.toml` — updated `apps/api-legacy` → `.archive/api-legacy`
- `package-lock.json` — deleted and regenerated clean (no stale `packages/country-*` entries)
- `package.json` (root) — workspaces updated, lint-staged scoped to `apps/web` and `apps/e2e` only

## Consequences

- 17 unmerged branches archived as tags; require cherry-pick MC if reactivated
- All path refs updated atomic with their respective move commits
- `package-lock.json` regenerated clean (lockfile portability ZAKON compliant)
- `gcp-deploy.yml` workflow disabled (`.disabled` suffix); re-enable deferred to Phase 8 validation
- Git history preserved via `git mv` throughout
- `lint-staged` scoped to `apps/web/**` + `apps/e2e/**` only (ESLint configs in `packages/domain-*`
  reference a root `tsconfig.json` that does not exist; scoping prevents false failures)

## Acceptable Remaining Refs

The following historical/comment references were intentionally left as-is:

- `docs/evidence/*/verification.json` — immutable point-in-time MC evidence records
- `apps/api/src/.../CountryService.kt:11` — Kotlin comment documenting what was replaced

## Recovery

- `git checkout archive/bilko-2026-04-28-pre-cleanup` for full pre-cleanup state
- `git stash apply stash@{0}` for the 688 dirty entries (sha 8f18dc36)
- Individual branch restoration: `git checkout archive/2026-04-28/<branch>`

## Deviations from Blueprint

- `RUNBOOK.md` kept in root (mandatory per Section 15 line 1074)
- `BUILD-BLUEPRINT.md`, `CLAUDE.md`, `CHANGELOG.md`, `PIPELINE.md`, `package.json`, `turbo.json`,
  `settings.gradle.kts`, `.env.example*` also kept in root per Section 15
- `packages/database` (current) maps to blueprint `packages/database`
- `packages/core` (Bilko-specific shared code, no direct blueprint analog) kept as-is
- `design/` and `branding/` ended up double-nested (`docs/design/design/`, `docs/branding/branding/`)
  due to `git mv` into pre-existing `docs/design/` and `docs/branding/` subdirectories
- `apps/api-express/` is a deviation from blueprint (which expects only `apps/api/` Kotlin) — this
  is the active Express migration target, kept alive until MC #5125 migration completes

## References

- ALAI-UNIVERSAL-BLUEPRINT.md Section 15
- MC #10027 (closed, superseded by #10034)
- MC #10034 (this work)
- MC #10044 (coverage glob fix, bundled into Phase 5d)
- ADR-020: `docs/architecture/ADR-020-BACKEND-CANONICAL-DEPRECATE-API-KOTLIN.md`