Align topology-planner planning docs with current contract boundaries and checklist conventions

[Copilot]

This PR resolves documentation drift in topology-planner by removing stale contract framing and reconciling planning artifacts with repository checklist/design conventions. It also updates references so readers land on current boundaries (not superseded topology assumptions).

• Planning tracker consistency

  • Added crates/topology-planner/PLANS.md (component-local tracker).
  • Registered it in root PLANS.md so component lifecycle tracking is discoverable from the workspace index.
  • Clarified component-local status wording to reflect active planning work while implementation milestones remain parked.

• Checklist state and archival hygiene

  • Corrected M1 summary state in crates/topology-planner/CHECKLIST.md to match actual item completion.
  • Moved EP-1.1 long-form completed content into crates/topology-planner/COMPLETED-CHECKLIST.md.
  • Left an in-place EP-1.1 stub link in CHECKLIST.md per move-with-link convention.

• Stale topology-contract references removed

  • Rewrote EP-1.3 checklist/design wording to align with windows-topology-sys D-20: residency-cost input is no longer framed as an unpopulated MachineMemoryTopology::distances path.
  • Canonical wording now points to abstract-model + adapter/synthesizer ownership, while preserving explicit directed-cost + measurement-context requirements.

• Canonical vs historical design split

  • Added crates/topology-planner/DESIGN-RATIONALE.md for historical exploration/context.
  • Trimmed crates/topology-planner/DESIGN-NOTES.md to current canonical decisions and linked rationale sections where historical analysis is still relevant.

• Dependency-direction wording fix

  • Updated crates/topology-planner/COMPONENT.md to remove the ambiguous “nothing depends on this crate” phrasing and make planner-consumer dependency direction explicit.

- [x] **EP-1.1** -- ... -> [completed 2026-09-18 18:50:30 +00:00](COMPLETED-CHECKLIST.md#ep-11)

• Fixes ### 🟡 Changes recommended #99

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

SH-16.11 is still referenced as active after D-20 discharged it, and measurement ownership is claimed as tracked without a corresponding checklist item.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 3
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

The documents reuse the discharged SH-16.11 ID and claim all historical follow-ups are tracked despite missing checklist work.

Review details

Suppressed comments (4)

Previously missed (1) — in code that hasn't changed since the last review.

crates/topology-planner/DESIGN-NOTES.md:263

• The canonical note says the detailed trigger analysis is recorded in this rationale section, but the new section only retains a high-level summary: it omits the D-9 'demonstrably mismodels a machine' trigger, the single-node/vacuous measurement result, and why reopening that decision is still deferred. Restore those historical details here or change this pointer so the split does not claim rationale that was dropped.

crates/topology-planner/CHECKLIST.md:76

• SH-16.11 is already discharged and superseded by windows-topology-sys D-20; it specifically tracked filling the deleted distances field. Reusing that archived ID for the new directed-cost contract makes the open work look closed and conflicts with the owning checklist. Allocate a new component-owned work ID and update the active tracker instead.

  remains tracked as `SH-16.11`.

crates/topology-planner/DESIGN-NOTES.md:258

• This repeats SH-16.11 as the open tracking ID, but that ID was discharged and superseded by D-20 when MachineMemoryTopology::distances was deleted. Give the abstract-model directed-cost requirement a new work ID rather than reusing the historical topology-sys item.

The directed-cost half remains an open requirement on `topology-model` plus adapter inputs and stays
tracked as `SH-16.11`.

crates/topology-planner/DESIGN-RATIONALE.md:26

• This says all three historical follow-ups are tracked in the component checklist, but the checklist has no item for measurement ownership, and its naming item covers planner/model naming rather than adapter naming. Add explicit checklist work for the missing follow-up or narrow this sentence so the design rationale does not claim unscheduled work is tracked.

These are tracked as checklist work in [CHECKLIST.md](CHECKLIST.md) rather than as canonical
decisions.

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

It still reuses discharged SH-16.11 and overstates checklist tracking and historical rationale coverage.

Review details

Suppressed comments (5)

Previously missed (2) — in code that hasn't changed since the last review.

crates/topology-planner/DESIGN-NOTES.md:263

• The linked rationale is described here as containing the “detailed trigger analysis,” but the new section only summarizes the old field framing; the evidence/trigger distinction (the probe's directional measurements, single-node hosts, and D-9 reopening condition) is not present there. Either preserve that history in this Tier 2 file or change this pointer to the archive that actually contains it.
  crates/topology-planner/DESIGN-RATIONALE.md:15
• This Tier 2 rationale restates the current boundary and ownership rule that D-20 is supposed to canonically own. If D-20 changes, this copy can drift; keep the historical explanation here but reduce this paragraph to a pointer to D-20, leaving the current contract in DESIGN-NOTES.md.

crates/topology-planner/CHECKLIST.md:76

• SH-16.11 is not a live tracker for this requirement: the root completed checklist marks it discharged and superseded by D-20 for deleting MachineMemoryTopology::distances. Reusing it here makes the new abstract-model/adapter gap look owned by the old, completed topology-field work. Please remove this reference or introduce a new planner-owned follow-up ID and link that instead.

  remains tracked as `SH-16.11`.

crates/topology-planner/DESIGN-NOTES.md:258

• This repeats the same stale ownership: SH-16.11 is explicitly discharged/superseded by D-20, while this sentence presents it as the active tracking item for the new topology-model requirement. Use a new planner-owned follow-up reference, or state that the requirement is recorded here without reusing the retired ID.

The directed-cost half remains an open requirement on `topology-model` plus adapter inputs and stays
tracked as `SH-16.11`.

crates/topology-planner/DESIGN-RATIONALE.md:26

• The checklist has items for not-observed behavior and general naming/scenario work, but it has no item that schedules measurement ownership (and no item explicitly owns adapter naming). Therefore “These are tracked as checklist work” overstates the current planning state. Add explicit checklist items or narrow this sentence to the follow-ups that are actually tracked.

These are tracked as checklist work in [CHECKLIST.md](CHECKLIST.md) rather than as canonical
decisions.

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite

[MikeGrier]

@copilot , please also address issues #101 and #102 in this PR

[Copilot]

🟢 Approval recommended

No blocking correctness issues were found; the only finding is a minor tracker-heading consistency issue.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

crates/topology-planner/PLANS.md:1

• For consistency with every existing component-local tracker (for example, crates/windows-topology-sys/PLANS.md:1), make the heading identify its owning component. A generic # PLANS heading is ambiguous when these trackers are opened together.

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

@copilot , please also address issues #101 and #102 in this PR

Addressed in 1dcd6b6: EP-D-3's Tier 2 rationale now keeps the missing historical trigger context while leaving D-20 as the canonical current boundary, and EP-1+.3 now explicitly owns the remaining planner/model/adapter naming follow-up so issues #101 and #102 are covered.

[MikeGrier]

@copilot , please address:

🟢 Approval recommended

No blocking correctness issues were found; the only finding is a minor tracker-heading consistency issue.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

crates/topology-planner/PLANS.md:1

• For consistency with every existing component-local tracker (for example, crates/windows-topology-sys/PLANS.md:1), make the heading identify its owning component. A generic # PLANS heading is ambiguous when these trackers are opened together.

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🟢 Approval recommended

The documentation changes are internally consistent with D-20 and established planning conventions, with no blocking issues found.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

@copilot , please address:

🟢 Approval recommended

...

Addressed in ad62769: crates/topology-planner/PLANS.md now uses the component-specific heading # Plans: topology-planner, matching the other component-local trackers.

[Copilot]

🟢 Approval recommended

The documentation changes are internally consistent with D-20 and established planning conventions, with no unresolved issues found.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite