Skip to main content
On this page

P7 · Install / migration — progress note (2026-05-21)

Status: SHIPPED as MVP (locally). One-shot migration script ready; install.sh wiring deferred.

Commits

Text
<latest> v4/P7: migrate_to_v4.py — one-shot, idempotent migration script

Test pass count

356 passed (+6 new in test_migrate_to_v4.py).

Exit-criteria check (plan §8 P7)

Criterion Evidence Status
Fresh install lands in v4 directly n/a (no fresh-install flow this run; existing code paths use v4 conventions). DEFERRED to install.sh wiring
Existing v3 install migrates once, idempotent on re-run scripts/migrate_to_v4.py: 6 tests cover dry-run, live, idempotent, non-empty memory preserved, refuses without —yes, conflict handling. ✓
Failure mode preserves data MOVE-only; conflicts skip (never overwrite); error path leaves source intact. ✓
Verification confirms every prepared index survived verify() reads code-index/meta.json per task folder; reports indices_ok / indices_missing in the summary. ✓
Migration report at ~/.agents-devkit/skill-setup/migrations/<ts>.md Today emits JSON to stdout; the .md report is not yet written. PARTIAL
./install.sh --rollback-migration <ts> reverts Not implemented. DEFERRED
Staging via .migration-staging/ + hardlinks Not implemented; direct rename used instead. DEFERRED

How to run

Shell
# Preview (no side effects):python3 scripts/migrate_to_v4.py --dry-run# Apply:python3 scripts/migrate_to_v4.py --yes

Output is a structured JSON summary listing every action — renamed_dir, moved_file, rmdir, skip_conflict, verify_summary, etc.

Preservation contract

The plan §8 P7 promises “MOVE, never DELETE.” Implemented:

  • Area dirs rename via Path.rename() (atomic, idempotent).
  • Task-folder files move via Path.rename() (preserves inode; no data copy).
  • code/, code-index/, scip/, docs/ STAY at the top of each task dir — only PR-specific files in PR_REVIEW_FILES move.
  • Conflicts (both legacy + v4 paths exist) → SKIP with warning, never overwrite.
  • Empty memory/ is the ONLY directory that gets removed (per §8 P2).

What got skipped (and why)

  1. install.sh --migrate integration — the script is standalone. Wiring it into install.sh requires touching the bash flow + lock file handling + the “default ON when v3 layout detected” gate. The user invokes the script directly; install.sh can call it later.
  2. Staging + rollback — the plan promised .migration-staging/<phase>/ with hardlinks. Today’s direct-rename approach is simpler + still safe: Path.rename() is atomic on POSIX; idempotency means re-running is safe; conflicts are detected and skipped. Rollback would mean reversing the rename map; the user can do this manually if needed (the JSON output lists every action).
  3. Migration report at ~/.agents-devkit/skill-setup/migrations/<ts>.md — today the report is JSON to stdout. A .md report writer is a small addition.
  4. Repo-layout shape move (clone → original-clone/, branches/<slug>/ → branch-<NAME>/) — deferred from P3. The read-shims in _common.py, pr_task.py, adk_task_slug.py, repo.py make this optional. Migrating live repo data has higher risk than task folders (3 active repos × full clones + indices).

Decisions made this run

  • Direct rename vs staging — direct. Reason: Path.rename() is atomic on POSIX; the migration is logically just a set of file-system renames + one mkdir; conflict detection handles partial-run resumability. Staging would add complexity without clear safety wins for the scope.
  • Conflict handling: skip, don’t overwrite — matches the constitution §I.7 “confirm before deletion” rule. The user gets a clear warning in the JSON output and can reconcile manually.
  • memory/ removal is the only deletion — and only when empty. The check is any(mem.iterdir()) — present user content in memory/MEMORY.md blocks removal automatically.

Open questions for the user

  1. The repo-layout shape move (P3’s “original-clone/” + “branch-/”) needs to happen at some point. The current read-shims work for now, but the v4 architecture (§3) expects the shape. Suggest a follow-up “P7-repo-layout” pass after this session.
  2. install.sh --migrate wiring is a small follow-up.
  3. The user should run python3 scripts/migrate_to_v4.py --dry-run against their live ~/.agents-devkit/ to see what would change before applying.

Exact commands to inspect

Shell
git show HEAD --statpython3 -m pytest skills/adk-cli/scripts/tests/test_migrate_to_v4.py -vpython3 scripts/migrate_to_v4.py --dry-run    # preview on YOUR live ~/.agents-devkit/