Brainstorm the v1 roadmap, then design and plan each phase (mvp)

[Wahbeh-Mohammad]

Goal

Produce the v1 roadmap for the Ruby SDK, then brainstorm and plan each phase of that roadmap, one phase at a time, so implementation can start with a spec, a plan, and a checklist per phase. This issue is the umbrella task for all of that planning work. Implementation itself is out of scope here and will get its own issues per phase.

Branch rules

• Base branch: mvp. Nothing is committed to mvp directly.
• Create the task branch from mvp: git checkout -b <this-issue-number>-mvp-planning mvp.
• All planning documents (roadmap, per-phase designs, plans) land on that branch and reach mvp through pull requests: one PR for the roadmap first, then one PR per phase (or per sub-phase) carrying its design and plan together.
• Implementation of a phase happens later on its own branch off mvp, named <phase-issue-number>-phase-<N[letter]>-<slug>, and is merged back as a single phase-level PR.
• No commit or push without the repo conventions in CLAUDE.md; the housekeeping probe must be clean before every PR.

Governing documents (read in this order)

1. docs/product-spec.md and docs/product-spec/ — the normative, language-agnostic specification. 645 requirement IDs across 19 prefixes (SEAM, HTTP, IO, BODY, CTX, PIPE, RECOV, RETRY, REDIR, AUTH, PAGE, SSE, SERDE, OBS, CFG, TRANSPORT, ASYNC, XCUT, NFR). Appendix C is the consolidated index. Every phase cites against these IDs.
2. docs/sdk-design-ruby.md and docs/sdk-design-ruby/ — the Ruby port design: chapter 00 is the porting method, chapters 01–09 the architecture (gem layout, seam mapping, domain model, pipelines, resilience, pagination/SSE/serde, instrumentation/configuration, toolchain), chapter 10 the deviation catalogue (19 entries), chapter 11 spec ambiguities and their resolutions, chapter 12 the requirement coverage index. This document is already segmented along the seams the roadmap should sequence.
3. The Ruby styleguide at /home/mohammad/Projects/dexpace/styleguide/ruby/ (chapters 01–15 plus README). Binding from phase 0 onward. Cite it by absolute path with the machine prefix stripped, as the knowledge corpus does.
4. CLAUDE.md — repo conventions, documentation hierarchy, phase workflow, register rules.
5. docs/README.md — ownership table for every entry under docs/ (frozen vs writable).

Knowledge corpus (use it, do not re-derive)

docs/knowledge/harvested/ holds 40 topics and 2166 entries harvested from the three governing sources, covering 623 of the 645 requirement IDs. Query it with the CLI, never by hand:

ruby scripts/knowledge.rb --prefix-info <PREFIX>        # subsystem, owning chapter, ID range, coverage
ruby scripts/knowledge.rb --gaps <PREFIX>[,<PREFIX>]     # IDs with no corpus entry (read those from the chapter)
ruby scripts/knowledge.rb --req <ID>                     # everything the corpus says about one requirement
ruby scripts/knowledge.rb --topic <topic> --section rules --brief
ruby scripts/knowledge.rb --section conflicts --brief    # the six unresolved styleguide-vs-design conflicts
ruby scripts/knowledge.rb --phase <N[x]>                 # IDs cited by an already-planned phase
ruby scripts/knowledge.rb --list-topics

The knowledge-lookup skill (.claude/skills/knowledge-lookup/SKILL.md) documents the query recipe for brainstorming a phase. Invoke it at the start of the roadmap session and at the start of every phase and every numbered task. Never edit docs/knowledge/harvested/; corrections and implementation findings go under docs/knowledge/notes/.

Decisions already locked (do not reopen)

• Ruby >= 3.2; CI matrix 3.2, 3.3, 3.4, 4.0.
• Static types via RBS signatures shipped in each gem's sig/, gated by rbs validate and steep check; sig diff against the previous release as the API-surface lock.
• Minitest for tests; the conformance suite uses framework-agnostic assertion objects.
• Single repository, gems/-per-package monorepo. dexpace-core has zero add_dependency lines and may require only stdlib that stays default across 3.2–4.0.
• MVP gems: dexpace-core, dexpace-transport-net_http, dexpace-transport-async_http, dexpace-async-thread, dexpace-serde-json, dexpace-conformance. Later gems are listed in design chapter 02 §2.2 and in docs/deferred-items.md.
• Both transport seams survive (sync blocking contract plus a core-owned async future pivot). Timeout.timeout, Thread#raise, Thread#kill are banned repository-wide.
• Configuration precedence keeps the spec's order: explicit override > ENV > Dexpace.configure defaults > caller default.
• Two MUSTs are knowingly unsatisfied (ASYNC-3 and PIPE-33's interrupt clause) and recorded as DEF-18 in docs/deferred-items.md; do not re-litigate.

Decisions to settle before the roadmap is approved

Six conflicts between the Ruby styleguide and the port design are recorded in the corpus (--section conflicts --brief). Each must be resolved either by amending the styleguide or by recording an SDK-specific deviation, written as a note under docs/knowledge/notes/ that cites the conflict's key. The roadmap's cross-cutting constraints section states the outcome once so no phase re-argues it.

1. Ruby floor: styleguide pins 4.0+, design fixes 3.2+.
2. Typing stack: styleguide mandates Sorbet # typed: strict with runtime sig; design ships RBS + Steep.
3. Value objects: styleguide defaults to T::Struct; design uses Data.define.
4. Gems per repository: styleguide wants one gemspec per repo; design is a gems/ monorepo.
5. Autoloading: styleguide requires Zeitwerk; design forbids an autoloader in core (SEAM-1).
6. RuboCop baseline: styleguide requires rubocop-airbnb via inherit_gem; design names rubocop-minitest and rubocop-performance only.

Product-spec errata found during the design stay as notes in design chapter 11; the spec is frozen here and shared with sibling ports.

Step 1 — Roadmap brainstorm

Use the brainstorming skill. It writes to docs/superpowers/specs/; then run the housekeeping apply step to file the document under docs/work/mvp/ (see Process rules). Target file: docs/work/mvp/<YYYY-MM-DD>-ruby-sdk-v1-roadmap-design.md.

Required skeleton:

# Ruby SDK — v1 Roadmap
**Status:** Draft, approved for planning.
**Purpose:** <this is an index, not an implementation plan; each phase gets its own brainstorm → design → plan cycle when its turn comes; never absorb implementation detail as phases complete>
**Governing documents:** <the five above, with the requirement-ID vocabulary listed>
## Cross-Cutting Constraints (apply to every phase, not their own phase)
## Phase List
**Ordering rationale:**
## How Phases Get Executed
## Phase Status Notes

Phase List table columns: Phase | Name | Gem(s) | Product-spec refs | sdk-design refs. Every row names its deliverable gem(s), the spec sections or ID ranges it satisfies, and the design chapter/section it maps to; the design cell later doubles as the link to the phase's own design doc.

Cross-cutting constraints to state once: the quality gates from phase 0 onward (RuboCop, ruby -w, Steep/RBS, Minitest, SimpleCov floor, require-allowlist audit, clean-bundle isolation run, sig diff), zero-dependency core, requirement-ID traceability into checklists, the resolved styleguide-vs-design conflicts, the ban list, the register discipline (no register sections inside specs or plans).

Suggested dependency order, to be confirmed or amended with a stated rationale that distinguishes genuine dependency order from convenience order: (0) scaffold and quality gates; (1) core HTTP domain model; (2) seam foundations, discovery/registration, lifecycle; (3) I/O contracts and request/response body lifecycle; (4) execution context, recovery chain, stage pipeline; (5) resilience: retry, redirect, auth; (6) serde, SSE, pagination; (7) configuration and platform primitives, instrumentation/observability; (8) transport adapters and the async driver; (9) cross-cutting invariants and conformance suite; (10) deviation reconciliation audit. Use --prefix-info and --gaps per prefix to size each phase by its ID count.

Segmentation rule: when a phase's ID count is clearly larger than earlier phases, brainstorm a segmentation design first (its own document at the phaseN/ level) that decides the cut boundaries (prefer boundaries the spec forces, e.g. an explicit "no dependency on X" MUST), execution order, what each segment ships vs reuses, and any findings that outlive the sizing question. Only then do sub-phases phaseNa, phaseNb, … get their own design/plan/checklist.

Acceptance for "approved for planning": every phase has a deliverable, a spec citation, and a design citation; cross-cutting constraints stated once; ordering rationale explicit; execution cycle spelled out; deferred-items mechanism wired into the start and end of every phase brainstorm; the six conflicts resolved and recorded.

Step 2 — Per-phase cycle (repeat for each phase in roadmap order)

1. knowledge-lookup: --prefix-info and --gaps for the phase's prefixes, --section conflicts --brief and --origin note --brief for the same prefixes, --phase on any earlier phase it depends on. Check docs/deferred-items.md for DEF entries targeting this phase.
2. brainstorming skill → design doc in docs/superpowers/specs/, then filed as docs/work/mvp/phaseN[/phaseNx]/<date>-phaseN[x]-<slug>-design.md. Skeleton:

# Phase N — <Name> — Design
**Status:** Draft, approved for planning.
**Purpose:** ...
**Governing documents:** ...
## Scope                      (name the exact ID ranges covered)
## Prerequisite: <amendment to an earlier phase, if any>
## Module Layout              (gem, lib/ and sig/ paths)
## <Component> (`path.rb`)    (one per file; cite IDs and design sections per section)
## Testing
## Deviation Ledger (for the audit phase)   | Deviation | Reference behavior | Justification |
## Deferred Items (add to docs/deferred-items.md)   | Item | Deferred from | Target | Reason |

3. writing-plans skill → plan in docs/superpowers/plans/, filed as docs/work/mvp/phaseN[/phaseNx]/<date>-phaseN[x]-<slug>.md. Skeleton:

# Phase N — <Name> Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: subagent-driven-development or executing-plans; track tasks with the checkboxes below.
**Goal:** ...   **Architecture:** ...   **Tech Stack:** ...   **Prerequisite:** ...
## Global Constraints         (bans, invariants, lint ceilings, typing convention)
## File Structure
### Task 1: <name>            (steps: write failing test → run red → implement → run green → commit)
...
### Task N: Gates, unchanged API surface, and the checklist
## Self-Review                (design section → task table; shared types threaded; known rough edges)

Tasks map one-to-one onto files in the module layout; the last task always runs every gate, proves the public surface (sig diff) unchanged or explains the change, writes the checklist, and appends deferrals to the register.

4. Housekeeping: ruby .claude/skills/housekeeping/apply.rb --delivery mvp --phase N[x] --write files both documents; then fix any links the probe reports (ruby .claude/skills/housekeeping/probe.rb). Never cite a docs/superpowers/ path in prose.
5. Open a PR from the task branch to mvp with the design and plan. Append a dated status note to the roadmap (never edit an earlier note).
6. The checklist (<date>-phaseN[x]-<slug>-checklist.md) is written when the phase is executed, not during planning: legend ✅ Implemented and tested, 🚫 Not built (named reason), ⏳ Deferred (named target), N/A; one table per spec sub-area | ID | Level | Requirement gist | Status | Where | where "Where" cites a task number; sections for cross-phase obligations and deferred-out-of-phase items; a **Status: EXECUTED (<date>)** line naming the green gate commands.

Process rules

• Deviations: phase design's Deviation Ledger → design chapter 10 → audited in docs/deviations.md.
• Deferrals: docs/deferred-items.md (DEF-<n>), checked at the start and appended at the end of every phase brainstorm.
• Open findings: docs/open-items.md (OI-<n>). Never leave an aggregate register section inside a spec or plan.
• Frozen trees (never written by tooling): docs/knowledge/, docs/product-spec*, docs/sdk-design-ruby*.
• Housekeeping probe clean and both tooling test suites green before every PR:

ruby .claude/skills/housekeeping/probe.rb
ruby -w .claude/skills/housekeeping/test/run.rb
ruby -w scripts/test/knowledge_test.rb
ruby scripts/verify_knowledge_structure.rb

Deliverables

• Six styleguide-vs-design conflicts resolved as notes under docs/knowledge/notes/
• Roadmap document filed under docs/work/mvp/ and merged to mvp via PR
• Segmentation designs for any oversized phase
• Design + plan per phase (or sub-phase), each merged to mvp via PR, with a dated roadmap status note
• Per-phase implementation issues opened from the roadmap once its design and plan are merged