T-ZYBI-recipe-warn-moon-cargo-lock-churn

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 rust-app adoption recipe (apps/zoo/MIGRATION.md) does not warn adopters that moon’s first InstallDependencies(rust) action for a newly adopted rust app regenerates the entire root Cargo.lock, so each adopter rediscovers the churn and has to decide ad hoc whether it is safe to discard. Originating from T-B98V-adopt-vimit in sksizer/dev:

moon’s first InstallDependencies(rust) action for a newly adopted rust app regenerates the entire root Cargo.lock to newest-compatible (306-line churn during the vimit adoption, discarded). Every NEW rust project’s first moon run reproduces this. Add a warning to the adoption recipe (apps/zoo/MIGRATION.md) to expect and discard that churn.

— T-B98V-adopt-vimit

Today

Location	Role today
`apps/zoo/MIGRATION.md`	The canonical rust-app adoption recipe. Its “Root cargo workspace membership” bullet documents the fold-in — per-crate `Cargo.lock` dropped, root lock absorbs the tree additively — but never warns that moon’s first `InstallDependencies(rust)` action after adoption regenerates the entire root `Cargo.lock`.
`Cargo.lock`	The root workspace lockfile the churn lands in. The vimit adoption’s first moon run regenerated it to newest-compatible (306-line diff), which was reviewed and discarded by hand.
`.moon/toolchains.yml`	Registers the rust toolchain (`version: 'stable'`); with it enabled, moon schedules an `InstallDependencies(rust)` action ahead of a newly adopted rust project’s first task run.

Proposed

The adoption recipe carries an explicit warning: after a new rust app is folded into the root cargo workspace, moon’s first InstallDependencies(rust) action for that project regenerates the entire root Cargo.lock to newest-compatible versions. Every newly adopted rust project’s first moon run reproduces this. Adopters should expect the churn, review that nothing else rode along, and discard it rather than committing it with the adoption — instead of rediscovering the behavior and deciding ad hoc.

Approach

In apps/zoo/MIGRATION.md, locate the “Root cargo workspace membership” bullet under “What this branch does” — the passage documenting that the per-crate Cargo.lock is dropped and the root lock absorbs the app’s dependency tree.
Add a short warning note adjacent to that guidance: moon’s first InstallDependencies(rust) action for a newly adopted rust app regenerates the entire root Cargo.lock to newest-compatible versions, and every new rust project’s first moon run reproduces this.
State the expected disposition in the same note: the churn is a side effect of lockfile regeneration, not part of the adoption — review the diff for anything unexpected, then discard it (git restore Cargo.lock) rather than committing it with the adoption.
Cite the concrete motivating instance: the vimit adoption’s first moon run produced a 306-line root-lock regeneration that was discarded.
Confirm the edited file passes the repo’s markdown format check.

Files to touch

Location	Kind	Change
`apps/zoo/MIGRATION.md`	modify	Add a warning near the “Root cargo workspace membership” guidance that moon’s first `InstallDependencies(rust)` run regenerates the root `Cargo.lock`; state the expect-and-discard disposition and cite the vimit 306-line churn.

Acceptance criteria

AC-1: apps/zoo/MIGRATION.md warns that moon’s first InstallDependencies(rust) action for a newly adopted rust app regenerates the entire root Cargo.lock to newest-compatible versions.
AC-2: The warning states the expected disposition — review and discard the churn, naming a concrete command such as git restore Cargo.lock — rather than committing it with the adoption.
AC-3: The warning sits with the “Root cargo workspace membership” / lock-absorption guidance, so a reader following the fold-in step encounters it in place.
AC-4: The warning cites the motivating instance: the vimit adoption’s 306-line root-lock churn, discarded.
AC-5: The edited file passes the repo’s markdown format check with no reformatting required.

Out of scope

Changing moon or cargo configuration to prevent the regeneration (e.g. locked installs or pinning) — this task only amends the prose recipe.
Committing any root Cargo.lock changes; no dependency versions change here.
Mirroring the warning into the sibling migration docs (apps/agentpants/MIGRATION.md, apps/ontological-legacy/MIGRATION.md, apps/legacy-polish/MIGRATION.md) — the post-mortem names the zoo recipe as the canonical one.

Dependencies

none

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