Repository navigation
docs(migration): record the client, identity and sync-gate decisions of 2026-10-20 - #15290
marius-kilocode wants to merge 2 commits into
Conversation
|
➖ v2 migration progress: 0.9% → 0.9% (0 done, 0 total, 0 dropped; 87/9829 cells) Placement: 2 new marked lines in shared files (2 patch), 0 new Ratchets: 9 core-internal imports (base 9); shared patches by rung 29 seam, 3 patch (base 29 seam, 3 patch). No change to the progress map.
|
![kilo-code-bot[bot]](https://avatars.githubusercontent.com/in/2193792?s=60&v=4){kind=small}
| - **Running the CLI.** Only through `bun dev` (`script/dev-isolated.ts`, isolated profile; `KILO_V2_PROFILE=$(mktemp -d)` for a fresh one). Never `bun run dev:live`, `opencode` or `bun run --cwd packages/cli`: they use the installed OpenCode data and service. This replaces "Live TUI Testing" below, including `dev:live` for TUI stories. | ||
| - **Placement.** Plugin first, then host. Kilo server plugins go into `KiloPlugins` (`packages/kilo-plugin/src/index.ts`); the host (`packages/kilo-cli`) registers them. An edit in a shared upstream file carries a `kilocode_change(<feature>)` marker and an entry in `script/upstream/shared-patches.json`. Load the `v2-migration` and `v2-feature-placement` skills (`.kilo/skills/`) before any migration change. Source of truth: `migration-tracking/plans/v2-host-strategy.md` section 5. | ||
| - **Identity.** The internal binary and app directories are `kilo2`, separate from v1 data and config. Never read or write v1 directories; the one-shot import happens at the public rename. Config is `kilo.json`, `kilo.jsonc`, `.kilo` and `.kilocode` only, never `opencode.*`. | ||
| - **Clients.** Each client is a new package on `origin/v2` wired natively to `@opencode/client` and the Kilo RPCs; no v1 wire facade, no `@kilocode/sdk`. A Kilo feature is RPC first, then TUI, then VS Code (decisions 14 to 16 in `migration-tracking/plans/migration-context.md`). |
There was a problem hiding this comment.
SUGGESTION: The blanket no @kilocode/sdk contradicts the client these docs plan to publish.
U-E1-10, added in this PR, requires "@kilocode/sdk v2 published as a versioned client", and U-E3-09 (unchanged) publishes @kilocode/sdk and @kilocode/plugin from the BASE packages. Read literally, this new rule forbids the package entirely, so an agent could refuse the fan-out work or an import. Qualify it as the v1 SDK (for example "no v1 wire facade and no v1 @kilocode/sdk") here and in the matching sentence in migration-tracking/technical-notes/v2-fork-conventions.md.
| | Unit | Title | Issue | Gate | Deps | Delta | Stale | Donor | Acceptance | Status | | ||
| |---|---|---|---|---|---|---|---|---|---| | ||
| | U-E3-01 | Opt-in, re-runnable v1 session/data import into the v2 store (read `kilo.db` read-only; upstream pure transforms; legacy JSON storage) | #14413 | G1 | U-E1-02 | needs-port | M | partial M | Fixture stores from each supported v1 release incl. `fb7e96ed`: originals byte-identical, v1 binary still opens them; second run imports only new sessions; schema audit re-run against v1 target and BASE | todo | | ||
| | U-E3-01 | v1 import mechanism into the `kilo2` store: read v1 `kilo.db` and config read-only, upstream `V1Migration` transforms plus Kilo store additions, each store migrate-or-drop (decision 13). Opt-in during the internal line for testing; the public run is the one-shot first start of U-E8-02 | #14413 | G1 | U-E1-02 | needs-port | M | partial M | Fixture stores from each supported v1 release incl. `fb7e96ed`: originals byte-identical, v1 binary still opens them; the one-shot run imports once and a second start is a no-op; the migrate-or-drop decision per Kilo store (board, share rows, editor context, revert status, todo) recorded; schema audit re-run against v1 target and BASE | todo | |
There was a problem hiding this comment.
WARNING: The plan still describes the opt-in, re-runnable import that decision 13/D6 remove.
This row now says the run is one-shot ("a second start is a no-op"), and the D6 row (line 53) says "No opt-in, re-runnable import model". But the same file still states the E3 outcome as "imports v1 data opt-in and re-runnably" (line 157), keeps the exit criterion "a second run imports only new sessions" (line 159), and keeps the split-history risk mitigation "Opt-in, re-runnable import" (line 300). Those rows are what agents read as the current plan, so update them to the one-shot model.
Also, "Opt-in during the internal line for testing" in this row reads against "there is no opt-in ... import model" in decision 13; name the internal test-only exception explicitly so the rule is unambiguous.
Code Review SummaryStatus: 3 Issues Found | Recommendation: Address before merge Overview
Issue Details (click to expand)WARNING
SUGGESTION
Files Reviewed (14 files; incremental diff touched 2)
Checked against current code and PR #15417 (open, targets Fix these issues in Kilo Cloud Previous Review Summary (commit 4eeb781)Current summary above is authoritative. Previous snapshots are kept for context only. Previous review (commit 4eeb781)Status: 2 Issues Found | Recommendation: Address before merge Overview
Issue Details (click to expand)WARNING
SUGGESTION
Files Reviewed (14 files)
Checked and found consistent with the codebase: the v1 Reviewed by deepseek-flash-latest · Input: 83.2K · Output: 22.3K · Cached: 1.3M Review guidance: REVIEW.md from base branch |
| 4. Run the focused branding tests and affected package typechecks. Keep both upstream/hosted controls, OAuth escaping checks, and real TSX rendering coverage in source and compiled modes. Repeat isolated source/compiled smoke checks when their surfaces change. | ||
| 5. Record mapping adaptations, test results and remaining gaps in the sync/feature PR. Keep live CI status and evidence current; source-rendered OAuth screenshots do not prove a live browser sign-in. | ||
|
|
||
| The legacy sync branding passes exist but are disabled by default and process conflicts only. Do not enable them as a substitute for this review: their broad rules and scope differ from the adapter. Moving the same mapping to sync time or generated copies does not remove its path/string dependency. A stable API or a different generation mechanism needs a separate approved design; do not add upstream seams solely to remove Kilo-owned code. |
There was a problem hiding this comment.
WARNING: The new branding decision leaves the rename-script guidance in the other agent docs untouched.
This paragraph and the rewritten item 5 (line 32) make the sync-time transforms.branding passes the disabled legacy path and #15417's source/build adapter the interim mechanism. But the canon still tells agents the opposite:
migration-tracking/technical-notes/v2-fork-conventions.mdline 85: branding "is handled by the rename script"; rung table line 95: "The rename script during each sync"; line 106: "Rung 5 (rename script)".migration-tracking/plans/kilo-v2-migration-plan.mdlines 426 and 432: "5 branding via the rename script" and "then rung 5 branding script"..kilo/skills/kilocode-merge-minimizer/SKILL.mdline 24 and.kilo/agent/upstream-merge.mdline 122 still instruct the sync to run the rename script.
The skill points at v2-fork-conventions.md as the rule source (line 8), so an agent hits both versions at session start. Update those lines to the interim adapter, or mark the rename script as disabled legacy there, in this PR.
What Problem This Solves
The plan still described three things the team has since decided against: a v1 wire facade as an open option (D-5), an opt-in re-runnable import into a customer store distinct from a preview
kilo2identity, and VS Code and JetBrains tracks that start after G1 by re-landing the v1 extension behind v2 adapters (U-E6-01). Agents read these documents at session start, so each stale sentence is a prompt to do the wrong thing. Thevscode-v2-bootworktree (2026-10-20) and the archived port'skilo-vscode/src/backendare two instances of the same wrong thing.Why This Change Was Made
Six decisions are recorded in
migration-context.md(13 to 18), with the evidence in a dated record,v2-plan-delta-2026-10-20.md, so they are not re-argued:kilo2(binary Create install:alpha script #15288, app directories feat(kilo-cli): keep Kilo v2 data in its own kilo2 directories #15270); at public release it becomeskilowith a one-shot import (upstreamV1Migrationplus Kilo additions per store). v1 directories are never written.PATCH /config/overlayin v1 checks precedence and a revision under a lock, then invalidates or disposes the instance; none of that is in the OpenAPI document, and v2 reloads differently), and the state is separate (kilo.dbversuskilo2.db). Measured on both adapters: the archived port maps 88 of the 129 SDK paths the v1 extension uses with the real typecheck failing;vscode-v2-bootmaps 43 of 99 with 8 constant stubs. Upstream never served v1 routes on its v2 server; its only shim went the other direction and was deleted.origin/v2, native@opencode/clientplus Kilo RPCs, port the UI and rewrite the data layer (upstream's own numbers: 74% of TUI paths and 56% of web app files survived as moves). VS Code starts now as a walking skeleton (U-E6-22, session running); JetBrains and cloud consumers start after a measured fan-out gate (U-E1-10)./config/*group and owns reload semantics.mainis rejected:main's server never gains the v2 Kilo RPCs and the state is separate.upstream/dev166 commits past the pin: Kilo packages import 37 upstream files, 11 changed, 10 of them in files a marker-only sync never flags. A report nobody reads is not a detector, so each Kilo package gets anupstream-deps.jsonlock that fails CI until updated (U-L3-02), the mirror drift check is the same gate (U-L3-03), and the shared-patch checker classifies rungs mechanically and rejects forked upstream tests (U-L3-04), which is what let feat(core): discover kilo.json and .kilo config directories #15018 land as a seam.Plan changes: Part A objective, D5 and D6 rows, phase diagram and table (VS Code from Phase 0, fan-out gate before JetBrains and cloud); Part B retires U-E6-01, adds U-E0-06 (the unowned #15244 fix half), U-E1-09, U-E1-10, U-E6-22, U-E6-23 and U-L3-02 to U-L3-05, and rewrites the import rows (U-E3-01, U-E3-03, U-E8-02), the config rows (U-E1-07, U-E1-08), the VS Code rows (U-E6-02, U-E6-05) and the JetBrains and cloud rows to the new gates. The strategy document gains the same in sections 2, 4, 7, 8, 9 and 10, and loses the
facadedisposition. Skills, fork conventions and theAGENTS.mdv2 block carry the one-sentence versions; the three archived plans get banners naming what the foundation replaced; the Gateway plan gets a placement note.User Impact
None at runtime. Documentation, skills and the two
AGENTS.mdbullets only.Evidence
bun script/check-shared-patches.ts --worktree: ok. TheAGENTS.mdblock gains two bullets, somarkedLinesgoes 288 to 290 and the entry text names them.bun script/check-opencode-annotations.ts --worktree: ok (61 shared files against9d90d892dcb).bun script/upstream/progress.ts --check: up to date.origin/kilo-v2:packages/kilo-vscode/src/backend, 25 files;migration-tracking/technical-notes/baseline/existing-vscode-port.mdon that ref), thevscode-v2-bootworktree (commits47b491ef2c2,5aa92629895), upstream history onupstream/dev(8b682c42b66,d03e0c5e547,9314992f985,0fbe489e357,5caf1f9f6f5), and the import list of the Kilo packages diffed775d1d0d713..upstream/dev.Related: #15281 (direction rule), #15282 (config seam), #15288 (
kilo2binary), #15244 (startup, fix half unowned). The breaking-changes note (U-E6-23) is written by the VS Code skeleton session in its own PR.