Skip to content

docs(roadmap): correct the P2 row, two GW-2 steps, and the discovery sprint cut#269

Merged
JArmandoAnaya merged 1 commit into
mainfrom
docs-p2-roadmap-gw2-corrections
Jul 16, 2026
Merged

docs(roadmap): correct the P2 row, two GW-2 steps, and the discovery sprint cut#269
JArmandoAnaya merged 1 commit into
mainfrom
docs-p2-roadmap-gw2-corrections

Conversation

@JArmandoAnaya

Copy link
Copy Markdown
Contributor

Docs only, no behaviour change. Executing P2 surfaced four places where the committed docs no longer matched the code or a decision already taken.

1. The roadmap's P2 row contradicted the agreed style contract

It described road styles as "draggable assets preserving prior attributes" — the reverse of what was decided, and the same wording that made GW-2 step 11 self-contradictory. A style defines the lane profile; it cannot both apply and preserve the lane edits it replaces. The row now states the real contract: replaces the cross section and boundary marks, preserves everything orthogonal to it (reference-line geometry, elevation, junction connectivity).

Same row: (supersedes #95/#97) sat on enclosed-area surfaces, but #95 is tee-on-commit and #97 is grade-match — both extend-from-endpoint concerns. Moved.

2. The roadmap never mentioned the Help workstream

#265 and #266 are two of P2's eleven sprints and were scoped as permanent cross-pillar infrastructure every later pillar grows — yet docs/roadmap/README.md had zero references to it. A reader could not tell it existed. The P2 row now names it, and the sprint conventions record the cross-pillar workstream rule (titled for the workstream, labelled for both) so help-sM isn't read as a violation of the pN-sM convention.

3. Two GW-2 steps amended (approved)

Both are documentation defects, not implementation-dependent wording, so they land now rather than at close-out — otherwise nine sprints run against an acceptance script describing a product nobody built. #264 keeps ownership of any further refinement once the tools exist.

  • Step 3 claimed "a junction is created automatically at the overlap". Nothing does that. create_road_tool.cpp:186-189 only calls create_road/create_linked_road, and SnapKind is {Grid, RoadEndpoint, TangentContinuation} — no side or crossing candidate. Junctions are made solely with the Create Junction tool. The kernel ops do exist (assembly::cross_onto_road, tee_onto_road, attach_t_junction), so P2 wires them up in p2-s3: extend-from-endpoint + tee/cross on commit #214 and the step now says when the junction forms.
  • Step 11 asked for "lane count edits" to survive a style that defines the lane count. Now explicit and testable, and it names the elevation profile edited back in step 7 — which is the interesting preservation case in this workflow.

A short amendments note under ## Steps records both, following GW-1's precedent of an inline prose note rather than a separate section.

4. The discovery report's sprint cut was stale

It still listed interior add_lane under p2-s1 after that moved to p2-s2 (renumbering must remap JunctionConnection::lane_links — the contract p2-s2 rewrites, so one sprint should own it), and predated #262#266 existing, so those rows had no issue links. Also links the dead-dependency finding to #268 (libigl never linked; Manifold unused outside a smoke test — filed, deliberately unscheduled, outside P2).

Verification

Relative links and anchors checked locally against what the docs link check job enforces (lychee --offline --include-fragments). docs/roadmap/golden_workflows/gw1_camera.md is deliberately untouched — it carries the maintainer's in-progress GW-1 hand-run.

…sprint cut

Executing P2 surfaced four places where the committed docs no longer matched
either the code or a decision already taken.

The roadmap's P2 row described road styles as "preserving prior attributes".
That is the reverse of the agreed contract, and it is the same wording that
made GW-2 step 11 self-contradictory: a style DEFINES the lane profile, so it
cannot both apply and preserve the lane edits it replaces. The row now says
what a style actually does — replaces the cross section and the boundary
marks, preserves everything orthogonal to it. The row also gained the in-app
Help workstream, which is two of P2's sprints and permanent cross-pillar
infrastructure, yet appeared nowhere in the roadmap; and its "supersedes
#95/#97" moved onto extend-from-endpoint, which is what #95 (tee-on-commit)
and #97 (grade match) are actually about.

Two GW-2 steps are amended. Both are documentation defects rather than
implementation-dependent wording, so they land now instead of waiting for the
close-out sprint — nine sprints would otherwise run against an acceptance
script that describes a product nobody built:

- Step 3 claimed a junction is created "automatically at the overlap". Nothing
  does that: Create Road only authors a road, and the snap set has no side or
  crossing candidate, so junctions are made solely with the Create Junction
  tool. The kernel operations to form one on commit do exist, so P2 wires them
  up (#214) and the step now says when the junction forms.
- Step 11 asked for "lane count edits" to survive a style that defines the
  lane count. The preservation contract is now explicit and testable.

The discovery report's sprint cut still had interior add_lane under p2-s1
after it moved to p2-s2 (renumbering must remap JunctionConnection::lane_links,
which is the contract p2-s2 rewrites — one sprint should own it), and predated
#262#266 existing, so those rows had no links.

Also records the cross-pillar workstream convention the help sprints follow —
titled for the workstream, labelled for both — so `help-sM` is not read as a
violation of the `pN-sM` rule, and links the dead-dependency finding to #268.

No behaviour change; docs only.
@JArmandoAnaya JArmandoAnaya merged commit a9734d8 into main Jul 16, 2026
14 checks passed
@JArmandoAnaya JArmandoAnaya deleted the docs-p2-roadmap-gw2-corrections branch July 16, 2026 01:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant