[codex] add phase 5 planning roadmap

[540lyle]

Summary

This change publishes a Phase 5 planning roadmap for the repository-authored Fusion post and threads that plan through the existing contributor documentation. The new roadmap makes the next expansion explicit: finish the remaining baseline 3-axis contract gaps first, lock the embedded machine-profile model, and then grow capability in fixture-backed slices through indexed 3+2, probing, and simultaneous 5-axis support.

Problem

The repository had direction spread across several docs and backlog notes, but it did not have one canonical planning document that described the next capability slices, their sequencing, and the constraints that should continue to govern the adapter. That gap makes it easy for future work to drift into adapter-first behavior, duplicate planning notes, or expand scope without the specs, profiles, and fixtures moving together.

For users and contributors, the effect is ambiguity about what is actually next, which missing 3-axis features are still considered completion work, and how future machine-profile and multi-axis support should be introduced without breaking the current architecture.

Root Cause

The project had already established the architecture and validation model, but the next-phase plan only existed implicitly across README language, testing guidance, and backlog notes. There was no single source of truth tying roadmap sequencing to fixture requirements, profile embedding assumptions, and controller-vs-machine-vs-adapter boundaries.

Fix

This PR adds docs/phase-5-roadmap.md as the canonical planning document and updates the surrounding docs to reference it instead of maintaining separate competing lists. The roadmap keeps the repository fixture-first and profile-driven, defines the embedded profile catalog model for the shipped .cps, and classifies the major delivery slices from 3-axis completion through future 5-axis support.

The supporting doc updates align the rest of the repo with that plan. README.md and adapters/fusion/README.md now point contributors to the roadmap directly. docs/controller-model.md, docs/profiles-and-overrides.md, and docs/testing.md expand the controller, profile, and validation guidance so the next capabilities are described in the right layers. llm/backlog.md and llm/testing.md now defer to the roadmap instead of maintaining a second planning list.

This is a documentation-only change. It does not change post behavior, fixture outputs, or the current shipped adapter surface.

Validation

I ran the repository validation flow after staging and again during push:

• npm run validate
• adapter syntax check passed
• ESLint passed for adapters/fusion/FluidNC.cps
• unit coverage and differential tests passed
• fixture validation passed with 135 checks across 4 fixture families

[540lyle]

Review: Phase 5 Planning Roadmap

Overall: This is a well-structured planning document with clear delivery slices and strong emphasis on the fixture-first philosophy. The surrounding doc updates are consistent and properly defer to the roadmap as the single source of truth. A few observations below.

Strengths

• Single source of truth discipline — the backlog and testing docs now defer to the roadmap instead of maintaining competing lists. This is the right call.
• Slice ordering is sound — closing 3-axis gaps before expanding to multi-axis prevents the "shiny new feature hides missing baseline" failure mode.
• Embedded profile model is well-defined — the 4-step YAML → build → embedded catalog → runtime override chain is clear and avoids runtime file-access assumptions.
• Validation standard is concrete — the 5-point "done" checklist per slice is specific enough to actually enforce.

Suggestions

1. docs/phase-5-roadmap.md — Slice 0 vs. "Immediate priorities" overlap: Lines 34–39 list immediate 3-axis gaps (coolant, retract, drilling), and then Slice 0 (lines 43–64) also references spec expansion for the same topics. The boundary between "immediate priorities" and Slice 0 could be sharper — consider whether the immediate priorities section is actually just the first half of Slice 0, or whether it's a pre-slice gate that should block Slice 0 from starting.

2. docs/phase-5-roadmap.md — Missing success criteria for Slice 0: Slices A–D have clear deliverables (fixtures, callback implementations, etc.), but Slice 0's exit criteria are softer ("publish the capability matrix", "define the embedded profile catalog model"). Consider adding a concrete artifact list — e.g., "Slice 0 is done when specs/capability-matrix.md exists and profiles/machines/ contains at least one validated YAML."

3. docs/phase-5-roadmap.md — Redistribution caveat is vague: Line 24 says "Keep unresolved redistribution questions tracked in upstream/release docs" — but doesn't name which doc tracks this. If it's not tracked yet, this assumption is dangling. Either point to the specific doc or add a TODO.

4. docs/profiles-and-overrides.md — "Embedded profile model" section: The 4-step model described here duplicates what's in the roadmap (lines 56–60). Since both docs now exist, one of them should be the authority and the other should link. Given the roadmap owns the planning narrative, consider making profiles-and-overrides.md link to the roadmap for the model definition rather than restating it.

5. README.md — Duplicate link: The Phase 5 Roadmap link appears twice — once in the new "Next Steps" section (line 158) and again in the "Developer Docs" list (line 171). Having it in both places is fine if intentional (different audiences), but worth confirming that's the intent rather than accidental duplication.

6. llm/backlog.md — Original backlog items dropped: The three original items ("Add the Fusion adapter…", "Add fixture cases…", "Add scripts that validate invariants…") are removed and replaced with roadmap references. If those items are already completed (which the PR body implies), this is correct. But if any are still open, they've been silently dropped rather than marked done. Worth a quick sanity check.

Nits

• docs/phase-5-roadmap.md line 25: "Use a table-table AC machine family as the first validated 5-axis target" — is "table-table" the standard term in this domain, or should it be "table-table (trunnion)" for clarity to contributors unfamiliar with the kinematic classification?
• The community fixture contribution section appears in both docs/phase-5-roadmap.md (lines 162–175) and docs/testing.md. Same duplication concern as the profile model — pick one as canonical.

Verdict

Documentation-only, no behavioral risk. The planning is thorough and the architecture boundaries are well-drawn. The main risk is the duplication between the roadmap and the surrounding docs — if those drift apart later, the "single source of truth" benefit is lost. Consider a pass to convert restated content into links.

Looks good to merge with the duplication tightened up, or as-is if you'd rather address that in a follow-up.

[Copilot]

Pull request overview

Publishes a canonical Phase 5 planning roadmap for the repo-authored Fusion post and aligns existing contributor docs to reference it as the source of truth for next capability slices.

Changes:

• Adds docs/phase-5-roadmap.md describing Phase 5 sequencing, assumptions, slices, and validation standards.
• Updates top-level and adapter docs to point contributors to the roadmap for “what’s next”.
• Expands testing/controller/profile documentation to reflect Phase 5 priorities (fixtures, embedded profile model, controller/profile responsibility boundaries).

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	Adds a “Next Steps” section and links the Phase 5 roadmap from the main contributor doc list.
adapters/fusion/README.md	Adds a “Next phase” section pointing adapter contributors to the roadmap.
docs/phase-5-roadmap.md	New canonical roadmap detailing Phase 5 assumptions, delivery slices, and validation requirements.
docs/testing.md	Adds next-fixture guidance, community fixture contribution guidance, and references the roadmap as canonical.
docs/controller-model.md	Expands the controller vs adapter vs machine/profile concern lists to include Phase 5 concepts (cycles, WCS range, etc.).
docs/profiles-and-overrides.md	Documents the intended embedded profile catalog model and broadens recommended profile fields.
llm/testing.md	Defers next fixture-family listing to the roadmap and adds guidance about fixture evidence requirements.
llm/backlog.md	Reorients backlog bullets around the roadmap and Phase 5 sequencing/constraints.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[540lyle]

I left two substantive review comments on the diff. The main issues are a source-of-truth ambiguity around which layer owns capability limits such as work-offset range and TLC, and the fact that the new canonical Phase 5 plan still is not on the default LLM read path, so future agent-driven planning work can miss it.