Skip to main content
On this page

P3 · Repo layout overhaul — progress note (2026-05-21)

Status: SHIPPED as MVP (locally). Layout-shape work deferred to P7.

Commits

Text
4219122 v4/P3: branch-meta v4 fields + rebuild-index verb + --auto flag (MVP)

Test pass count

325 passed (+4 new in test_repo_v4_fields.py).

Exit-criteria check (plan §8 P3)

Criterion Evidence Status
Every repo has repo-meta.json already true in-tree (P0 baseline) ✓ (pre-existing)
Every repo has original-clone/ live filesystem still has clone at the top level DEFERRED to P7 — code paths don’t need it; P7 owns the live-data move.
Every repo has branch-<DEFAULT>/ live filesystem still has branches/<slug>/ DEFERRED to P7 — same.
Every branch dir has code/, code-index/, branch-meta.json code-index/ + branch-meta.json already exist. code/ (the per-branch worktree) is a P7-time creation. PARTIAL — schema fields landed; per-branch worktree not yet provisioned.
adk repo rebuild-index works when a folder was deleted by hand cmd_rebuild_index registered + repo rebuild-index USAGE. ✓

Why MVP

The user’s machine has 3 active repos with full git clones + indices under ~/.agents-devkit/repos/<name>/. Restructuring those mid-session without P7’s preservation contract (staging + rollback + verification) carries real data-loss risk. The plan §12 build order explicitly says “P7 accumulates step coverage as P1-P5 land” — so P3 ships the code paths that P7 will then exercise on the live filesystem.

What P3 needs to deliver for P5 to build on top:

  1. ✓ branch-meta.json carries created_by / created_at / auto_reason / last_used_at (§5.4 auto-base lifecycle).
  2. ✓ adk repo branch add --auto records auto-created branches.
  3. ✓ adk repo rebuild-index exists.
  4. ✓ Terminology: head_sha (was head_oid), last_indexed_sha (alias of legacy last_indexed_oid for back-compat).

P5 + P7 can take it from here.

What got skipped (and why)

  • Live data restructure (clone → original-clone/; branches/<slug>/ → branch-<NAME>/) — P7’s preservation-contract migration is the right place. Doing it now without staging/rollback would risk the user’s indices.
  • cmd_auto_bases_list / cmd_auto_bases_clean — P5 owns these (§5.4 lifecycle).
  • repo-meta.json platform field — additive; defer until P6’s GitHub-first defaults work needs it.
  • code/ per-branch worktree — the v4 design has branch-<NAME>/code/ as a git worktree at branch HEAD. Adding this requires git worktree add in cmd_branch_add + lifecycle on remove. Defer to P5 or P7 (whichever needs it first).

Decisions made this run

  • Scope-narrow P3 vs heavyweight P3 — picked narrow. Reason: 3 active repos with substantial indices; mid-session restructure has data-loss risk. Trade-off: P7 carries more weight; build order in §12 supports this.
  • last_indexed_sha as an alias of last_indexed_oid — both fields emitted in _write_branch_meta. New readers (P5) use last_indexed_sha; existing readers keep working.
  • created_by defaults to “user” for any new branch added via cmd_branch_add without --auto. Auto-defaulted; matches plan §8 P7’s “everything in-tree today was user-driven” rule.

Open questions for the user

  1. The plan §8 P7 says “verification: post-migration, the install runs a quick sanity check — for each preserved task folder, confirm code-index/meta.json exists, has a valid embed model, and chunks.lance/ is readable.” That assertion logic isn’t here yet. It belongs in P7’s migrator. Flagging.
  2. The plan §3 architecture shows branch-<NAME>/code/ as a worktree. Today’s _index_one_branch indexes from the CLONE’s working tree (single checkout), not a per-branch worktree. P5/P7 may want to wire git worktree add per branch — out of P3’s scope but worth deciding before P5 lands.

Exact commands to inspect

Shell
git show 4219122 --stat                                          # P3 diffgit show 4219122 -- skills/adk-cli/scripts/repo.py | head -100   # the meaty changepython3 -m pytest skills/adk-cli/scripts/tests/test_repo_v4_fields.py -v