five-phase-pass

name	five-phase-pass
description	Use for any rs-dean stack, gate, template, docs, or shared-pattern change. Runs the Rust five-phase pass: app/crate, template, generated proof, docs/skill, and stale-reference sweep.
argument-hint	[change description]

Objective

Keep rs-dean coherent when a change affects more than one surface. A change is not complete until the source, template, generated proof app, durable docs, and local skills all agree.

Phases

P1 — App Or Crate

Implement the change in the owning app or crate:

• apps/marketing for the required Leptos marketing app.
• apps/game for the required Bevy-only game app.
• apps/stories for isolated Leptos UI or scene proofs.
• apps/ui-bevy-stories for isolated Bevy UI primitive proofs.
• crates/* for reusable Rust logic.
• xtask for commands, gates, generated templates, and artifact checks.

Leptos app and template styling uses Tailwind through Trunk's rel="tailwind-css" asset type. Keep that link and the Tailwind import in every Leptos scaffold; xtask owns the policy check and standalone CLI installer.

Shared app theme work belongs in crates/ui: keep the Rust token/theme model, the Tailwind token stylesheet, Leptos components, and any Bevy-facing feature usage in sync. Bevy consumers must enable rs-dean-ui with default-features = false and features = ["bevy"] so the game tree stays Leptos-free.

Shared Leptos UI examples must use the rs-dean-ui Tailwind token vocabulary for design scales: text-0, gap-m, p-s, rounded-box, font-7, leading-0, shadow-2, and similar tokens. Do not mix stock Tailwind design-scale utilities such as text-sm, px-6, gap-4, rounded-lg, or font-bold into reusable UI examples; xtask enforces this on the app, story, template, and shared component surfaces.

The shadcn-inspired catalog lives in crates/ui. Keep its Rust definitions, implementation recipes, literal widget constructors, named token-only Leptos components, Bevy primitive adapters, apps/stories gallery, _issues/ui/ component task files, generated docs/crates/ui mdBook pages, apps/ui-bevy-stories primitive routes, and sweep log in sync. Run cargo xtask gen-ui-book after catalog or story fixture changes.

The composed block registry lives in crates/blocks. Keep its one-to-one Rust catalog, serde plus garde schema, renderer-neutral BlockPlan, constrained rs-dean-ui layout specs, dynamic Leptos/Bevy story routes, _issues/blocks, and generated docs/crates/blocks mdBook in sync. Blocks may only consume existing UI components and design tokens. Run cargo xtask gen-block-issues and cargo xtask gen-block-book after catalog, fixture, layout, or route changes.

Shared crate-book page structure belongs in docs/crates/templates as strict Handlebars Markdown templates. Generated UI and block pages must remain one-line {{#rs-dean-template ...}} directives. The Rust cargo xtask mdbook-template preprocessor resolves chapter paths against the typed catalogs and expands templates during mdBook builds; do not copy the expanded scaffolding back into individual source pages.

Use the local Bevy and modern-Rust skills before changing their owned surfaces.

P2 — Template

Mirror any scaffold-impacting change into templates/app. New apps must be born with the same gate and browser assumptions as the shipped app.

P3 — Generated Proof And Gate

For a stale local checkout or a new machine, run the fast preflight first:

cargo xtask doctor

Run:

cargo xtask five-phase-pass

This regenerates ignored apps/test-project, runs the one-pass Rust gate, and sweeps docs. The one-pass gate includes the focused static-analysis lane: format check, repo policy checks, native and wasm clippy, strict rustdoc, cargo deny check, cargo-machete, and the docs sweep. For gate or tooling changes, run cargo xtask static-analysis directly before the full pass to fail fast. The full gate still runs its final docs sweep after tests and artifact builds. apps/test-project is proof output only; never commit it.

For shared Leptos/Bevy UI or block renderer changes, run cargo xtask story-parity ui and cargo xtask story-parity blocks before the full pass. The parity command checks each paired route at 1000x700 desktop and 390x844 mobile viewports, including readiness, nonblank output, theme, spatial occupancy, edge distribution, and color complexity.

P4 — Docs And Owning Skill

Update AGENTS.md, README.md, and the owning skill under .agents/skills/. Docs should describe the current Rust/WASM stack directly. Remove references to retired tools instead of keeping historical explanations.

P5 — Stale-Reference Sweep

Run:

cargo xtask docs-sweep

The sweep fails if docs or local skills mention retired non-Rust stack terms. If a new stack retirement happens, add the term to the sweep in xtask and remove the old wording from docs/skills.

Acceptance Criteria

• cargo xtask gate passes.
• cargo xtask static-analysis passes when the task changes gate, static-analysis, or local tooling behavior.
• cargo xtask doctor passes when the task changes local tooling or gate prerequisites.
• cargo xtask docs-sweep passes.
• Template regeneration succeeds and apps/test-project remains untracked.
• apps/marketing, apps/game, apps/stories, and apps/ui-bevy-stories produce Trunk .wasm, glue, and CSS artifacts; Leptos CSS artifacts are compiled through Tailwind.
• Leptos app, story, template, and shared component examples use rs-dean-ui token utilities for design scales instead of stock Tailwind scale classes.
• The shadcn-inspired catalog has one _issues/ui/ task file per component, and every catalog component can build a shared implementation recipe, literal widget constructor, named Leptos component, and Bevy primitive spec.
• Shared component stories take copy, ordering, state, validation, and nested themes from crates/ui/src/story_fixtures.rs; the Leptos and Bevy harnesses render that same registry instead of maintaining parallel fixtures.
• Shared UI and block renderer work passes cargo xtask story-parity for the affected first-to-current sweep and the final full UI and block catalogs at desktop and mobile viewports.
• docs/crates/ui has one generated mdBook page per catalog component, and each page embeds the matching /stories/?story=ui-{component} isolated live Leptos fixture beside /ui-bevy-stories/?story=ui-{component} so the page shows only that component's DOM variants and Bevy primitive adapter output.
• Every generated UI/block catalog page contains one mdBook template directive, every shared template renders with strict typed data, and built HTML contains the expected isolated Leptos and Bevy story routes with no unresolved rs-dean-template directive.
• crates/blocks has one _issues/blocks task and one generated docs/crates/blocks page per registry entry; each page embeds the matching block-{slug} fixture in both story harnesses from one validated plan.
• Shared UI themes switch through Tailwind tokens in Leptos and through the same Rust palette in Bevy without adding Leptos to rs-dean-game or rs-dean-ui-bevy-stories.
• Required app packages keep persistent-state wiring through rs-dean-state.
• Generated apps/test-project/cube-smoke verifies the WebGPU smoke surface.
• The Bevy wasm feature tree contains WebGPU and no WebGL.