T-08HW-recipe-note-repin-floated-deps

Status: open/ready · Impact: medium · Complexity: small

AUTO-DEFINED: this spec was best-effort machine-authored by /sdlc:task-auto-define on 2026-07-31 because the task is autonomy: autonomous/pr. Review the Goal, Approach, Today, Files-to-touch, and Acceptance-criteria carefully before trusting it.

Goal

The adoption recipe in apps/zoo/MIGRATION.md tells adopters to drop all lockfiles, but says nothing about the dependency-resolution float that step causes — a gap surfaced by T-B98V-adopt-vimit in sksizer/dev that this task closes by amending the recipe’s lockfile-drop step to cover diagnosing and exact-pinning floated dependencies.

The adoption recipe’s ‘drop all lockfiles’ step silently floats dependency resolutions: during the vimit adoption it floated ts-fsrs 5.2.3 -> 5.4.1, whose FSRS state changes broke 3/77 tests until the dep was exact-pinned back to the upstream resolution. Amend the recipe (apps/zoo/MIGRATION.md) so the lockfile-drop step calls out diagnosing floated majors/minors and exact-pinning them when tests break.

— T-B98V-adopt-vimit

Today

Location	Role today
apps/zoo/MIGRATION.md	The canonical adoption recipe (cited as such by T-LQB3-adoption-recipe-enumerates-links-crates, T-JV2A-adopt-augmented-books-desktop, and T-B98V-adopt-vimit). Its “Frontend converted from pnpm to Bun” step under “What this branch does” tells adopters to drop pnpm-lock.yaml + package-lock.json and generate a fresh bun.lock, with no warning that the fresh resolution floats every semver-ranged dependency; the float fallout is narrated only after the fact, in its “Typecheck fixes” (nuxt/vue-tsc float) and “Pre-layer UI restore + dependency pins” (@nuxt/ui float) sections.
docs/planning/tasks/T-B98V-adopt-vimit.md	The adoption run that surfaced the gap: following the recipe’s lockfile drop floated ts-fsrs 5.2.3 -> 5.4.1, whose FSRS state changes broke 3/77 tests until the dep was exact-pinned back to the upstream resolution.

Proposed

The recipe’s lockfile-drop step carries the float warning and remedy inline: dropping upstream lockfiles silently re-resolves every semver-ranged dependency to current versions, so right after generating the fresh bun.lock the adopter diffs the direct deps’ fresh resolutions against the upstream lockfile and notes floated majors/minors — and when the adopted app’s tests or behavior break, suspects floated deps first and exact-pins the responsible dep back to the upstream-resolved version. The next adoption hits the breakage with a documented diagnosis path instead of rediscovering it.

Approach

1. In apps/zoo/MIGRATION.md, locate the “Frontend converted from pnpm to Bun” bullet under “What this branch does” — the recipe’s lockfile-drop step (drop pnpm-lock.yaml + package-lock.json, generate bun.lock).
2. Amend that step to state that dropping upstream lockfiles silently re-resolves (“floats”) every semver-ranged dependency to current versions, and to require diffing the fresh bun.lock resolutions of the app’s direct deps against the upstream lockfile, noting floated majors/minors.
3. Add the remedy: when the adopted app’s tests or behavior break after adoption, suspect floated deps first — identify the responsible float, exact-pin the dep in the app’s package.json to the upstream-resolved version (drop the ^/~ range), and regenerate bun.lock.
4. Cite the motivating failure as rationale: the vimit adoption (T-B98V-adopt-vimit) floated ts-fsrs 5.2.3 -> 5.4.1, whose FSRS state changes broke 3/77 tests until the dep was exact-pinned back — and point at the recipe’s own earlier float incidents (the “Typecheck fixes” and “Pre-layer UI restore” sections) as prior evidence.
5. Verify the edited file passes the repo’s pinned markdown formatter: bunx rumdl@0.2.9 check apps/zoo/MIGRATION.md exits 0.

Files to touch

Location	Kind	Change
apps/zoo/MIGRATION.md	modify	Amend the pnpm-to-Bun lockfile-drop step: warn that dropping lockfiles floats semver-ranged deps, require a floated-majors/minors diff against the upstream lockfile, prescribe exact-pinning back to the upstream resolution when tests break, and cite the vimit ts-fsrs 5.2.3 -> 5.4.1 incident.

Acceptance criteria

• AC-1: The lockfile-drop step in apps/zoo/MIGRATION.md (the pnpm-to-Bun conversion bullet) states that dropping upstream lockfiles re-resolves semver-ranged dependencies to newer (“floated”) versions.
• AC-2: The amended step names a concrete diagnosis method — diffing the fresh bun.lock resolutions of the app’s direct deps against the upstream lockfile — rather than leaving the method unstated.
• AC-3: The amended step instructs exact-pinning a floated dep back to the upstream-resolved version in the app’s package.json when the adopted app’s tests break.
• AC-4: The guidance cites the motivating failure: ts-fsrs 5.2.3 -> 5.4.1 breaking 3/77 tests in the vimit adoption (T-B98V-adopt-vimit).
• AC-5: bunx rumdl@0.2.9 check apps/zoo/MIGRATION.md exits 0 on the edited file.

Out of scope

• Mirroring the note into apps/agentpants/MIGRATION.md or other per-app MIGRATION docs — the friction bullet names the canonical zoo recipe only; a mirror can ride a follow-up if wanted (the T-LQB3-adoption-recipe-enumerates-links-crates precedent).
• Automating the float diff as a CI / lefthook gate or an sdlc op — this task amends prose only.
• Re-pinning any actual dependency in this repo — no package.json or bun.lock changes here; the vimit ts-fsrs pin landed with T-B98V-adopt-vimit.

Dependencies

• none — the friction evidence is already quoted in this spec, so the amendment does not depend on T-B98V-adopt-vimit’s PR merging.

Discovery context

Spawned by /sdlc:spawn-task-pr on 2026-07-31 UTC from T-B98V-adopt-vimit in https://github.com/sksizer/dev.

---

← Back to Tasks