Seamless armonia migration — expand bootstrap + migration scripts, add retirement script

[jeonghun-jj-lee]

Seamless armonia migration — expand bootstrap + migration scripts, add retirement script

Important

Problem: The migration script (tools/migrate-to-armonia.sh) only moves 4 of ~15 ~/.amico/ paths into armonia. Users who migrate find their Developer Tools settings pointing at dead paths, credentials orphaned under ~/.amico/, and amicode.skillRoots resolving against a directory that was just emptied. The bootstrap script has the same gap — it creates an incomplete skeleton.

Approach: Expand both scripts to handle the full ~/.amico/ state surface, ship a retirement script gated on ArmoniaService, and hard-switch the skillRoots code default to the armonia path. The symlink farm at ~/.amico/ ensures zero code breakage today (ADR 0008); the retirement script ships now but is safe to run only after ArmoniaService lands (#326).

Approaches Considered:

• (A) Symlink farm + gated retirement (chosen) — zero code changes to ~30 callers, zero breakage, user-paced cleanup. Trade-off: ~/.amico/ persists as an indirection layer until phase C.
• (B) Immediate code refactor — rewrite all callers to resolve from armonia directly. Rejected: blocks migration on Armonia as default workspace — sidebar tree, session cwd, cleanup #326 (ArmoniaService), ~30-site refactor across two packages, users cannot benefit until both land.
• (C) Leave ~/.amico as canonical, armonia is browse-only — rejected: perpetuates two roots, sidebar is a projection rather than reality.

Scope: The three shell scripts + one code-default change. Does NOT touch ArmoniaService (#326), does NOT rewrite callers (phase C follow-up), does NOT touch opencode XDG paths.

Assumptions: PR #308 (this PR) is the vehicle. The canonical layout in CONTEXT.md is stable. ~/armonia/.armonia-active is the marker ArmoniaService will write (defined here, implemented in #326).

Acceptance Criteria

• tools/bootstrap-armonia.sh creates the full skeleton: data/{config,env/julia,problems,runs,vaults,library,fleet,ledger,devices,authoring,amicode}
• tools/bootstrap-armonia.sh wires all directory symlinks from ~/.amico/ (10 symlinks: julia→data/env/julia, problems, runs, vaults, library, ops/fleet→data/fleet, ledger, devices, authoring, amicode)
• tools/migrate-to-armonia.sh moves all ~/.amico/ directories to their armonia locations and replaces with symlinks
• tools/migrate-to-armonia.sh copies config files (profile.json, cloud.json, pasqal.json, connections.json, lab.toml, mounts.toml) to data/config/ without removing originals
• tools/migrate-to-armonia.sh scans global VS Code settings.json for paths pointing at moved source directories, prints the stale→new mapping, and prompts for confirmation before rewriting
• tools/migrate-to-armonia.sh final diagnostic pass warns about any non-symlink entries under ~/.amico/ not in the known list
• tools/retire-amico-symlinks.sh exists, checks for ~/armonia/.armonia-active marker, refuses to run if absent
• tools/retire-amico-symlinks.sh when gate passes: removes all symlinks under ~/.amico/, moves config files from ~/.amico/ to data/config/ (making it authoritative), removes ~/.amico/ if empty
• Code: amicode.skillRoots default hard-switched from ~/harmoniqs/packages to ~/armonia/repos/packages/
• All three scripts are idempotent (safe to re-run)
• CONTEXT.md updated: Armonia definition reflects full state ownership + ~/.amico as symlink farm
• ADR 0008 committed: records the decision and exit condition

Key Decisions

Decision	Rationale
Armonia subsumes all of ~/.amico/	One tree, one backup target, one mental model; sidebar can show the full picture
Symlink farm (not code refactor) for backward compat	~30 call sites resolve transparently; no code changes needed today
Config files stay as real files at ~/.amico/	File-level symlinks break on atomic delete+rename (credential write pattern)
Retirement gated on ~/armonia/.armonia-active marker	Direct proof that ArmoniaService is live and resolving paths; version checks are fragile
skillRoots hard-switches (no cascading fallback)	Forcing function — users who haven't migrated hit a clear error and know to act
Opencode XDG paths untouched	Engine lifecycle is independent of workspace; amicode.configDir/amicode.sessionDatabase settings already let users opt in
VS Code settings rewrite is prompted, not silent	Respects user agency; global settings.json only (workspace settings not enumerable)
data/config/ as the armonia-side bucket for credentials	Groups 6 config files logically; not surfaced in sidebar as browsable content
data/env/julia/ (not data/env/ flat)	Future-proofs for multiple runtime environments (Pasqal venv, etc.)
Bootstrap creates directories only, no pre-created files	Extension handles first-run creation; empty files confuse onboarding gate checks

Data Contracts

Symlink farm (~/.amico/ after migration):

~/.amico/
  julia/          → ~/armonia/data/env/julia/
  problems/       → ~/armonia/data/problems/
  runs/           → ~/armonia/data/runs/
  vaults/         → ~/armonia/data/vaults/
  library/        → ~/armonia/data/library/
  ops/fleet/      → ~/armonia/data/fleet/
  ledger/         → ~/armonia/data/ledger/
  devices/        → ~/armonia/data/devices/
  authoring/      → ~/armonia/data/authoring/
  amicode/        → ~/armonia/data/amicode/
  profile.json      (real file, copied to data/config/)
  cloud.json        (real file, copied to data/config/)
  pasqal.json       (real file, copied to data/config/)
  connections.json  (real file, copied to data/config/)
  lab.toml          (real file, copied to data/config/)
  mounts.toml       (real file, copied to data/config/)

Retirement marker: ~/armonia/.armonia-active — written by ArmoniaService on boot, existence is the gate condition.

Constraints & Invariants

• The agent is NOT jailed to armonia — tools can reach any absolute path (unchanged from Armonia as default workspace — sidebar tree, session cwd, cleanup #326)
• Every homedir() + ".amico" + X path must continue to resolve correctly after migration (symlinks are transparent)
• Config files are NEVER symlinked (atomic write pattern breaks file-level symlinks)
• The retirement script MUST refuse to run without the marker (safety net against premature cleanup)
• Opencode XDG paths are never touched by any script
• Idempotency: all three scripts are safe to re-run at any point

Prior Art

• #307 / #308 — original bootstrap + migration scripts (this PR)
• #326 — Armonia as default workspace (ArmoniaService, sidebar tree, session cwd)
• ADR 0001 — credentials at rest under ~/.amico/ at 0600
• ADR 0008 — this decision (armonia subsumes ~/.amico)
• CONTEXT.md Armonia definition — updated to reflect full state ownership

Source

Brainstorming + grill-with-docs session 2026-08-14. Decision tree resolved: armonia subsumes everything, symlink farm is phase B, ArmoniaService retirement is phase C.

Notes

• Phase C (retire the symlink farm in code) is a separate issue, hitl-labeled, gated on Armonia as default workspace — sidebar tree, session cwd, cleanup #326
• The ~/armonia/.armonia-active marker contract is defined here but implemented in Armonia as default workspace — sidebar tree, session cwd, cleanup #326
• The VS Code settings scan handles: amicode.opencodeBinary, amicode.devAssetRoot, amicode.skillRoots, and any other amicode.* setting whose value contains a path under a moved source directory
• The catch-all diagnostic at the end of migration is informational only — it never moves unrecognized entries

[aarontrowbridge]

Hygiene note 2026-08-27: Armonia workspace cluster — this issue (#386 seamless migration) overlaps #307 (bootstrap + migration scripts), #312 (vault auto-setup on activate), and #326 (sidebar tree + session cwd). They form a single epic: canonical ~/armonia/ layout.

Proposal: keep #386 as the current canonical tracker (it expands bootstrap + adds retirement script and notes the credential/path orphaning problem). Mark #307 and #312 as superseded/completed-in-part — their acceptance criteria are subsumed by #386's broader scope — or explicitly keep them as slices blocked by #386. #326 is the UI surface slice of the same epic.

Not auto-closing; tagging for owner triage — @aarontrowbridge