T-LQB3-adoption-recipe-enumerates-links-crates

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

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

Goal

When adopting an external app into the monorepo, the dependency-reconciliation step of the adoption recipe reasons about links-bearing crates (which cause links = "..." collisions in a single cargo workspace) only from the top-level app crate. Vendored sub-crates — runners, builders, and other nested workspace members — can carry their own links-bearing dependencies whose collision surfaces only at cargo check, after the spec has already ruled it out. This task closes that gap in the adoption/cargo-migration guidance so the reconciliation enumerates transitive links-bearing crates across all vendored sub-crates, not just the app crate.

Spawned from the post-mortem of T-JV2A-adopt-augmented-books-desktop in git@github.com:sksizer/dev.git:

The task spec assumed “no rusqlite → no links = sqlite3 conflict,” but the vendored runner’s builder sub-crate carried rusqlite and the links collision only surfaced at cargo check. The app-adoption / cargo-migration recipe (apps/zoo/MIGRATION.md) should require enumerating transitive links-bearing crates across all vendored sub-crates, not just the top-level app crate, when reconciling dependencies.

Today

Location	Role today
`apps/zoo/MIGRATION.md`	The canonical adoption recipe. Its “Root cargo workspace membership” guidance reasons about `links = "sqlite3"` collisions from the top-level app crate only, so a `links`-bearing dependency inside a vendored sub-crate is never enumerated during reconciliation.
`apps/agentpants/MIGRATION.md`	Its workspace fold-in row records the same single-`libsqlite3-sys` reconciliation, again with no step that sweeps vendored sub-crates for other `links`-bearing crates.

Proposed

The recipe’s dependency-reconciliation step requires enumerating every transitive links-bearing crate across ALL vendored crates — the top-level app crate plus every nested workspace member (runners, builders, crates/*) — before the app is folded into the root workspace. A collision (two packages declaring the same links = "...") is then caught while reading the vendored manifests, not deferred to the first cargo check after the fold-in.

Approach

In apps/zoo/MIGRATION.md, find the “Root cargo workspace membership” bullet under “What this branch does” — the passage that reasons about the links = "sqlite3" collision.
Amend that guidance to require, before folding a vendored app into the root workspace, enumerating every links = "..."-bearing crate across ALL vendored crates: the top-level app crate AND every nested workspace member / sub-crate (runners, builders, crates/*). Name a concrete mechanism — grepping ^links = across every vendored Cargo.toml, or cargo metadata over the vendored tree — so a collision surfaces from the manifests rather than from a later cargo check.
Cite the concrete failure as the rationale: the vendored runner’s builder sub-crate carried rusqlite (which declares links = "sqlite3" via libsqlite3-sys), a collision the app-crate-only scan missed until cargo check.
Mirror the same enumeration note in apps/agentpants/MIGRATION.md’s workspace fold-in guidance so the sibling recipe records the same discipline.
Confirm both edited files still pass the repo’s markdown format check.

Files to touch

Location	Kind	Change
`apps/zoo/MIGRATION.md`	modify	Amend the dependency-reconciliation guidance to require enumerating transitive `links`-bearing crates across all vendored sub-crates, not just the top-level app crate; cite the rusqlite-in-a-sub-crate collision.
`apps/agentpants/MIGRATION.md`	modify	Mirror the enumeration note in the workspace fold-in guidance.

Acceptance criteria

AC-1: apps/zoo/MIGRATION.md states that dependency reconciliation must enumerate links-bearing crates across ALL vendored crates (nested workspace members / sub-crates), not only the top-level app crate.
AC-2: That guidance names a concrete enumeration mechanism — a Cargo.toml sweep for links = or cargo metadata over the vendored tree — rather than leaving the method unstated.
AC-3: The amended guidance cites the rusqlite sub-crate links = "sqlite3" collision as the motivating failure.
AC-4: apps/agentpants/MIGRATION.md’s workspace fold-in guidance carries the same enumeration note.
AC-5: Both edited files pass the repo’s markdown format check with no reformatting required.

Out of scope

Automating the sub-crate links sweep as a CI / lefthook gate — this task only amends the prose recipe.
Editing any Cargo.toml or Cargo.lock; no dependency versions change here.
apps/ontological-legacy/MIGRATION.md, which records a multi-crate vendored workspace but not the links-reconciliation guidance being amended.

Dependencies

none

Discovery context

Spawned by /sdlc:spawn-task-pr on 2026-07-19 UTC from T-JV2A-adopt-augmented-books-desktop in git@github.com:sksizer/dev.git.

← Back to Tasks