[fpliger]

What and why

Implements the stricter version of #15294. The detailed plan (137 units, Part B status cells, many overlapping docs) kept pulling work into doc updates and filled agent context. Planning now happens at epic and feature level only, live state stays in GitHub (#15297, epics, milestones M1 to M4, Project 42), and the repo keeps only stable content. Docs only; no product code changes.

Files

Added

• migration-tracking/principles.md: the one place for the technical rules (direction, placement order, clients, identity and config names, behavioral reference). It overrides any other doc.
• migration-tracking/plan.md: objective, working principles, milestones, epics by milestone with a one-line intent each, out of scope, where things live. No units, no status.
• migration-tracking/technical-notes/v1-v2-client-breaking-changes.md: taken from docs(migration): list v1 to v2 client breaking changes #15291 (without its bun.lock change). Edits: unit IDs replaced by epic links; the plan-foundation decision record replaced by a link to principles.md; "the Kilo RPCs on v2 today are …" replaced by a pointer to packages/schema/src/kilocode/. Checked against the code on e39551c9b0: kilocode.provider-usage (get, refresh) and kilocode.marketplace (list, install, uninstall) now exist, so those five rows and the count table are updated.

Rewritten

• migration-tracking/README.md: what lives where (about 15 lines).

Kept

• migration-tracking/progress/: generator output unchanged except five dropped marketplace notes in dispositions.json (and the README lines generated from them). They cited the removed kilo-v2-migration-plan.md; they now keep U-E2-23 and name e39551c9b0:migration-tracking/plans/kilo-v2-migration-plan.md and epic MCP and marketplace #15307.
• technical-notes/baseline/pinned-v2-baseline.md (three pointers to removed docs dropped) and technical-notes/script/v2-baseline.ts.

Removed

• plans/, discovery/, marker-audit/, test-plans/, github-drafts/, assets/, and everything in technical-notes/ except the three kept files (92 files).

Pointers updated

• AGENTS.md (Kilo block): points to plan.md, principles.md, Kilo v2 migration #15297 and the skills, and adds the line "Before any v2 change, read migration-tracking/principles.md; it overrides any other doc". shared-patches.json: entry text updated, markedLines +1 (466 after merging origin/v2, which added two).
• v2-migration skill: sources of truth now point to plan.md, principles.md, Kilo v2 migration #15297 and the kept references. Removed: the G1/G2/G3 strategy, the restated placement ladder and direction rule, "One plan unit per PR", the facade disposition, the bun run extension note, and Phased Plan - Port Kilo onto OpenCode V2 #13750. ## Progress map is unchanged, along with isolation, self-test, debugging, test policy and evidence.
• v2-feature-placement: principles.md is the source of truth; unit IDs removed and the procedure kept.
• kilocode-merge-minimizer, .kilo/agent/upstream-merge.md, script/upstream/README.md: pointers fixed. Rung 5 (branding) now matches v2-feature-placement: Kilo-owned automated renaming through the fix(kilo-cli): apply Kilo functional branding #15417 adapter, not "the rename script during syncs". The stale "the host does not exist yet" note and unit IDs are removed from the restated order.
• Comment or message pointers in script/check-shared-patches.ts, script/check-opencode-annotations.ts, script/upstream/placement.ts, script/upstream/utils/config.ts; a test fixture path in script/upstream/utils/config.test.ts.

Rule moved from v2-fork-conventions.md

• Markdown tables in Kilo-owned files use the compact form, and prettier --write is not run over Kilo documents. No skill had this rule, so it now sits in v2-migration, "Working rules". The other rules in that file are already in the skills, script/upstream/README.md or the baseline doc, or are dropped (the dev-fix triage lane and the virtua patch note for kilo-vscode).

Where carried content landed

• docs(migration): record the client, identity and sync-gate decisions of 2026-10-20 #15290 rules on direction, placement, clients and identity → principles.md sections 1 to 4 (identity uses the wording of decision 12; its open points are named on the matching epics in plan.md).
• docs(migration): list v1 to v2 client breaking changes #15291 → the breaking-changes reference.
• Decision 7 → plan "Out of scope". Upstream's own .opencode/ contributor config, which decision 7 also lists, is included.
• Deliberately left out: the edits of docs(migration): record the client, identity and sync-gate decisions of 2026-10-20 #15290 decisions 5, 6 and 7, plus 15b, 15c, 16, 17 and 18; the units; sync cadence, gates and detectors; release details (the switch to kilo, the npm dist-tag); package naming (D-1). Each can come back as an issue when needed.

Archive tag

Not created or pushed: the user declined. The old docs remain at e39551c9b0 (named in migration-tracking/README.md). To tag that commit later:

git tag -a migration-docs-2026-10-28 e39551c9b004769e3141228b8421a04546cfa084 -m "Kilo v2 migration docs before the reset (#15294)"
git push origin migration-docs-2026-10-28

Checks

• bun script/check-shared-patches.ts --worktree and without --worktree: ok
• bun script/check-opencode-annotations.ts --worktree and without: ok
• bun script/upstream/progress.ts --check: up to date (no generator output change)
• bun run script/check-workflows.ts: ok
• script/upstream: bun install --frozen-lockfile, bun test (92 pass, 0 fail), bun run typecheck ok
• Pre-push bun run check: 29/29 tasks passed
• Stale-reference sweep (the rg pattern from the task, run with git grep -P): outside progress/, the only hits are the two technical-notes/baseline/logs paths in v2-baseline.ts. They point to the script's own gitignored log directory, not to a removed file.

Follow-ups (not in this PR)

• The epic bodies (Identity, branding and store #15298 to Uncategorized #15323) still reference removed docs and unit IDs and need regenerating from plan.md (Anil offered on chore(migration): plan by feature, decide now, prioritize code #15294).
• Leaf issues created from old units need a second look when their epic starts.
• Restore offline network-wait and reconnect policy (runtime parity) #14371 (offline wait) stays open under Session policy and snapshots #15300. The issue closures proposed in docs(migration): drop the v1 fixtures and session-policy units #15286 are not applied.
• Removing the facade disposition from the progress generator is a small tooling issue.
• VS Code continues with feat(vscode): reuse the v1 extension UI on v2 data #15349.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

The incremental change since the last review is the fix commit dfd7fc09f6. The five dropped marketplace notes in migration-tracking/progress/dispositions.json now read "Decision recorded under U-E2-23 in the former plan (e39551c9b0:migration-tracking/plans/kilo-v2-migration-plan.md); marketplace epic #15307", and I confirmed that path exists at e39551c9b0 and contains U-E2-23. The corresponding lines in the generated migration-tracking/progress/README.md match the dispositions text, so no generator drift is visible. All other files in the 6c9379c..HEAD range (packages/kilo-vscode, packages/core, packages/kilo-cli, .github/workflows/kilo-v2.yml, the watcher shared-patches.json entry, progress SVGs) are upstream origin/v2 content brought in by the merge and are not part of this PR's diff against v2.

No images were added by this change, and no product code is touched, so there is no memory-leak surface to check.

Files Reviewed (2 files)

• migration-tracking/progress/dispositions.json - archive-qualified U-E2-23 notes verified against surviving plan at e39551c9b0; no issues
• migration-tracking/progress/README.md - generated lines match the updated dispositions; no issues

Previous Review Summary (commit 6c9379c)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 6c9379c)

Status: 1 Issue Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	1

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
migration-tracking/progress/dispositions.json	481-511	Notes still cite the deleted kilo-v2-migration-plan.md (U-E2-23); the generated progress/README.md repeats them.

This PR deletes migration-tracking/plans/kilo-v2-migration-plan.md, but five dropped dispositions in migration-tracking/progress/dispositions.json (lines 481, 486, 491, 496, 511) still say "Decision recorded in kilo-v2-migration-plan.md U-E2-23". The generator copies those notes into migration-tracking/progress/README.md (lines 323-328), so the public progress map will point readers at a file that no longer exists.

The PR body's stale-reference sweep says the only remaining hits are the two technical-notes/baseline/logs paths in v2-baseline.ts, so this was missed. Update the notes in dispositions.json to the surviving record (or the epic), then regenerate with bun script/upstream/progress.ts. Kept summary-only because the affected lines are not part of this diff.

Files Reviewed (109 files)

• .kilo/agent/upstream-merge.md, .kilo/skills/{kilocode-merge-minimizer,v2-feature-placement,v2-migration}/SKILL.md - pointer updates verified against the surviving docs; no stale links found
• AGENTS.md - new Principles bullet; markedLines 463 to 464 matches the one added marked line and the shared-patches.json entry
• migration-tracking/README.md, migration-tracking/plan.md, migration-tracking/principles.md - links resolve; kilo2/kilo2.json/kilo2.jsonc/.kilo2 wording matches packages/util/src/kilocode/config/files.ts and packages/kilo-cli/src/env.ts
• migration-tracking/technical-notes/v1-v2-client-breaking-changes.md - spot-checked RPC and route claims against packages/schema/src/kilocode/{provider-usage,marketplace}.ts, packages/protocol/src/groups/rpc.ts, packages/server/src/auth.ts, packages/cli/src/server-process.ts; count table is internally consistent
• migration-tracking/technical-notes/baseline/pinned-v2-baseline.md - removed pointers only
• script/check-{opencode-annotations,shared-patches}.ts, script/upstream/{README.md,placement.ts,shared-patches.json,utils/config.ts,utils/config.test.ts} - message/comment/limit/fixture changes; no logic change; step 6 pointer matches v2-feature-placement "6. Imports"
• 92 deleted docs/assets under migration-tracking/ (plans, discovery, marker-audit, test-plans, github-drafts, assets, most technical-notes) - no surviving references outside progress/; one dangling reference reported above

Fix these issues in Kilo Cloud

---

_{Reviewed by deepseek-flash-latest · Input: 36.8K · Output: 5.6K · Cached: 472.8K}

_{Review guidance: REVIEW.md from base branch v2}

[github-actions]

➖ v2 migration progress: 6% → 6% (0 done, 0 total, 0 dropped; 594/9819 cells)

Placement: 5 new marked lines in shared files (5 patch), 0 new kilo_port annotations, 0 new core-internal imports.

Ratchets: 27 core-internal imports (base 27); shared patches by rung 35 seam, 25 patch (base 35 seam, 25 patch).

No change to the progress map.

Full map · how cells close