Part 20: Roadmap — Phases 4–6📋

The catalogue is complete as a snapshot, but the family is mid-migration. The full plan lives in work/ROADMAP-REQ-ECOSYSTEM-DECOMPOSITION.md; this page summarises what the reader of the catalogue should expect to see change over the next few months, and why each phase is shaped the way it is.

Phase 1–3 — already shipped (mostly)📋

Phases 1, 2, and 3 of the roadmap covered the extractions this catalogue documents. Phase 1 took the leaves — scanner, test-smells, behavioral-check — out of requirements-lib. Phase 2 took the heavier capabilities — compliance, trace, spec-io. Phase 3 took the application layer — scaffolders, sync, wizards. After Phase 3, fifteen of the seventeen packages exist with their canonical names; the sixteenth (requirements-explore, a planned TUI trace explorer) is pencilled but not yet extracted.

What remains at the end of Phase 3 is the transitional debt: the requirements-lib barrel is now a compatibility re-export shim (its package.json lists every Tier-1 and Tier-2 sibling as a dependency, with each subpath re-exporting from the new home), the requirements CLI still imports from the barrel for paths that have not yet been rewired, and requirements-core still coexists with requirements-shared-kernel because the rename has not happened yet. Phases 4–6 are about clearing that debt.

Phase 4 — shrink the CLI📋

The CLI today carries pre-split duplicates: a src/base.ts that ships its own Requirement<S> subclass extending with DefaultStyleType, a duplicate req-discoverable-traceability.ts, and a two-line shim in src/analysis/test-bindings-scanner.ts labelled "moved during Ship 2" — three artefacts of unfinished prior migrations.

Phase 4 deletes all three.

• The CLI's src/base.ts goes away. The DefaultStyleType-bound Requirement<S> subclass moves into @frenchexdev/requirements-shared-kernel (or, if the maintainer prefers, into @frenchexdev/requirements-styles). Consumers of the CLI that imported Requirement from @frenchexdev/requirements now import it from the kernel or from styles, depending on whether they want the abstract shape or the default-narrowed one.
• The duplicate req-* files under packages/requirements/requirements/requirements/ are deleted. The single canonical version lives in requirements-requirements/src/.
• The src/analysis/ directory collapses to a thin re-export (or disappears entirely). Every from '@frenchexdev/requirements-lib/<subpath>' import in the CLI's source is rewritten to import directly from the appropriate Tier-1 / Tier-2 package.

End-state size of the CLI package: roughly a third of today's line count. src/bin/ (the commander entry), src/cli/prompt-shell.ts (the @clack/prompts adapter that wires the wizard's PromptPort), plus the per-subcommand wiring that translates command-line input to use-case invocations. No domain types, no analyzer logic, no duplicates.

The verification gate: grep -r '@frenchexdev/requirements-lib' packages/requirements/src/ returns nothing. The CLI no longer needs the deprecated barrel.

Phase 5 — the sharedkernel rename📋

Phase 5 is the workspace's largest mechanical change. Today the family has two Tier-0 packages with overlapping responsibilities: @frenchexdev/requirements-core (the older transitional kernel, holding base classes + decorators + the RequirementStyle abstraction + a handful of leftover cores like audit-hooks, toggling, explore-core, rename-core, watch-core) and @frenchexdev/requirements-shared-kernel (the new, narrower target — base classes, decorators, style, ports, branded IDs, period).

Phase 5 ends the duality. requirements-core is renamed to requirements-sharedkernel workspace-wide. The leftover cores (audit-hooks, toggling, explore-core, etc.) move to their correct tiers — audit-hooks likely into a new Tier-1 sibling, explore-core into the planned requirements-explore Tier-2 package, toggling and rename-core and watch-core into existing sibling homes per the maintainer's case-by-case decisions. The two-kernel state collapses into one.

Mechanically, the rename is a single codemod PR. The scope, verified by grep at planning time: 250+ package.json files (mostly the ddd-* family that depends on requirements-core for its own dog-fooding), roughly 1,000 source files (_local-features.ts, generated test stubs, the CLAUDE.md files of every workspace package that mentions the kernel, the CONTRIBUTING.md, the README files), and total ≈ 1,263 file mentions across the workspace.

The risk is in the breadth, not the depth — every change is s/@frenchexdev\/requirements-core/@frenchexdev\/requirements-sharedkernel/g. The risk lives in the breadth because a missed reference is a compile error after install; the verification is workspace-wide npx pnpm install plus per-package npx tsc --noEmit.

One architectural question stayed open during Phase 5 planning: should the family have one shared kernel or two? The roadmap's Q1 recommends one, on the grounds that a separate "core domain" layer above the shared kernel would force every Tier-1 package to depend on two foundational packages with overlapping concepts and cost ceremony without payoff. The user is asked to confirm before Phase 5 ships.

Phase 6 — sunset the barrel📋

@frenchexdev/requirements-lib exists today only as a backwards-compatibility re-export. After Phase 4, no production code in the workspace imports from it. After Phase 5, no ddd-* package outside the bounded context imports from it either. Phase 6 sunsets it formally:

1. Mark requirements-lib's package.json "deprecated": true.
2. Keep the barrel re-exports for one minor release cycle so external consumers (if any exist) have time to migrate.
3. Remove the package and its re-exports in the next major version bump.

The verification gate: ls packages/requirements-lib/ returns "No such file". The barrel is gone; the family is what the catalogue describes.

Open architectural questions📋

Two questions stayed open in the roadmap and are worth flagging because they affect the catalogue's future shape.

The first — recapped from the roadmap's Q1 — is "one shared kernel or two layers?". The recommendation is one. Adding a second foundational layer above Tier 0 would force every Tier-1 package to depend on two foundational packages with overlapping concepts, costing ceremony without payoff. The shared kernel IS the only thing every package needs; the four-tier DSL (Requirement → Feature → AC → Test) is the domain model, but it lives in the capability packages — each capability extends Feature / Requirement to describe its own ACs. No second layer needed.

The second — the roadmap's Q3 — is "where does requirements-styles belong?". Two options: (a) keep as cross-cutting, Tier 0 owns the abstractions, requirements-styles owns the five concrete presets, consumers pick which to import; or (b) fold into shared-kernel. The recommendation is keep independent. Styles are an extension point; the kernel should not ship five opinionated presets. The shared-kernel ships only the RequirementStyle shape and Requirement<S> base; styles provide the S instances. Bundling presets into the kernel would make the kernel larger and consumers without style needs would pay for them.

The third question is not in the roadmap but follows from the maintainer's record on AST grounding versus behavioural grounding (feedback_ast_vs_behavioral_grounding.md): "how strictly should behavioral-check gate publication?". Today the package is opt-in — npx requirements behavioral-check runs on demand, not as part of npm test. The plan recorded in project_behavioral_grounding_requirements.md proposes a requirements behavioral-check --strict mode that demands every AC has a mutation kill-rate above a threshold; the proposal is scoped to a single honest AC of the requirements-lib equivalent first, and will expand if the result is convincing.

Verification at each phase boundary📋

The roadmap's Section 7 specifies the verification gates the maintainer runs locally at each phase boundary. The pattern, applied to any package the phase touches:

1. npx pnpm install from workspace root — must report no cyclic-deps WARN after Phase 1a, no cyclic-deps anywhere after Phase 4.
2. Per-package npx pnpm --filter <package> build — must succeed in topological order (shared-kernel → Tier 1 → Tier 2 → Tier 3).
3. Per-package npx vitest run --coverage — 100% on each affected package's src/**.
4. Per-package npx requirements compliance --strict — regenerate bindings, no orphans, no uncovered critical ACs.
5. Spot checks per phase:
   • After Phase 4: grep -r '@frenchexdev/requirements-lib' packages/requirements/src/ returns nothing.
   • After Phase 5: grep -r '@frenchexdev/requirements-core' packages/ returns nothing.
   • After Phase 6: packages/requirements-lib/ is deleted.

What the reader takes away📋

The mega-split is not the end of the work; it is the architecture that lets the work continue. With seventeen packages instead of one barrel, every future capability — coverage-trend tracking, LSP integration, a CI bot, a documentation generator, a custom style — lands as a new sibling rather than a new branch in a monolithic file. The dependency graph stays acyclic by construction. The dog-fooding loop stays closed. Every new Requirement lands in requirements-requirements/src/ and is read by the same scanner that scans every other package.

The catalogue this series documents is what the family looks like today. The roadmap tells the reader what to expect in the next three months. Beyond that, the only thing the maintainer commits to is the rule that gives the catalogue its centre of gravity: every package preaches what it lives, every Feature satisfies a Requirement, every AC binds to a test, and every test is dog-fooded by the same DSL the package exports. Requirements-as-code, all the way down.