Skip to main content
Welcome. This site supports keyboard navigation and screen readers. Press ? at any time for keyboard shortcuts. Press [ to focus the sidebar, ] to focus the content. High-contrast themes are available via the toolbar.
serard@dev00:~/cv

Part 05: requirements-requirements

What it reifies

@frenchexdev/requirements-requirements is the second Tier-0 package, and the one that turns the abstract contracts of the shared kernel into the concrete specification of the entire ecosystem. Its package.json description is precise: "Domain vocabulary — Requirements + Features (the four-tier DSL's Tier-1 and Tier-2 content) for the @frenchexdev/requirements- ecosystem. Pure declarative classes; no impl, no tests."* The package contains zero runtime logic. Every file in src/ is either a Requirement subclass or a Feature subclass. The package builds with tsc and nothing else.

The package depends on one and only one workspace package — @frenchexdev/requirements-shared-kernel — and on no other runtime dependency. Its dependencies block in package.json is two lines long.

The public surface

src/index.ts is two re-export blocks: the Requirements first, then the Features. The Requirements block is the meta-spec:

// ─── Requirements ───
// Universal Reqs every package's Features satisfy
export * from './req-dog-food';
export * from './req-parallel-deliverable';
export * from './req-dsl-complete';
export * from './req-refactor-safe';
export * from './req-vocab-industry-aligned';
export * from './req-style-open-closed';
export * from './req-style-compile-time-narrowing';
export * from './req-style-separated-concerns';
// Tier-2 roadmaps + cross-cutting Reqs
export * from './req-audit-trail-hooks';
export * from './req-bootstrap-zero-friction';
export * from './req-discoverable-traceability';
export * from './req-editor-first-class';
export * from './req-live-feedback';
export * from './req-low-friction-acs';
export * from './req-orthogonal-toggling';
export * from './req-property-invariants';
export * from './req-round-trip-editable';
export * from './req-scaffold-extensibility';
export * from './req-spec-is-source-of-truth';
export * from './req-tui-modern';
export * from './req-versioned-traceability';
export * from './req-visual-traceability';

Twenty-two Requirements, grouped by intent. The first eight are universal — every package's Features must satisfy at least one of them. req-dog-food is the one Part 03 walked through verbatim; it is the requirement that mandates the practice. req-dsl-complete is the keystone that justifies the existence of this very package: a DSL that does not track Requirements (only Features) misrepresents itself. req-refactor-safe mandates that every refactoring step keeps the trace graph valid. req-vocab-industry-aligned anchors the vocabulary to ISO/IEC/IEEE 29148 and SysML; it is why Requirement's fields have the names they do.

The next fourteen Requirements are Tier-2 roadmaps — capabilities the family commits to deliver. req-spec-is-source-of-truth mandates the terraform-style plan → preview → apply pattern for any code generation. req-discoverable-traceability mandates that every scanner output is queryable without manual matrix maintenance. req-versioned-traceability mandates the content-hashing in requirements-versioning (Part 12). req-audit-trail-hooks mandates hooks for every state transition. Each Requirement carries its own fitCriteria — typed unions of quality-gate, unit-test, coverage-threshold, inspection, or analysis entries — so that what counts as satisfaction is part of the spec, not part of the test code.

The Features block re-exports the Feature classes that each capability package owns:

// ─── Features ───
// Self-Features of requirements-core (base classes, decorators, style abstractions)
export * from './base';
export * from './decorators';
export * from './style-reporter';
export * from './style-templates';
export * from './style-type-helpers';
export * from './style-validators';
export * from './style-vocabulary';
// Self-Features per impl file across the @frenchexdev/requirements-* ecosystem
export * from './audit-hooks';
export * from './behavioral-check';
export * from './clack-adapter';
export * from './compliance-core';
export * from './compliance-report';
export * from './feature-bidirectional-sync';
export * from './feature-heuristic-suggester';
export * from './feature-mermaid-graph';
export * from './feature-new-command';
export * from './feature-rename-codemod';
export * from './feature-schema-command';
export * from './feature-sync-command';
export * from './feature-trace-explorer-tui';
export * from './feature-watch-mode';
export * from './property-testing';
export * from './requirement-commands';
export * from './scaffold-core';
export * from './scaffolder-registry';
export * from './smart-constructors';
export * from './smoke';
export * from './test-bindings-scanner';
export * from './test-smells';
export * from './toggling';
export * from './trace-core';
export * from './versioning';

Roughly thirty Feature classes. Every Feature lives in a separate file; every file declares exactly one Feature with its @Satisfies link to one or more Requirements, plus the abstract methods that are the Acceptance Criteria. There is no logic in any of them — the bodies are method signatures returning ACResult. The signatures are what the scanner (Part 06) parses, what the compliance reporter (Part 07) walks, and what the trace engine (Part 10) renders into the matrix.

Where it sits

Tier 0, vocabulary slot. Depends only on @frenchexdev/requirements-shared-kernel. Consumed by every other package in the family — Tier-1 analyzers read its registries, Tier-2 use cases register their own Features against its Requirements, Tier-3 CLI lists its contents on demand.

The package must not:

  • Contain logic. No function bodies, no factories, no side effects on import. The package builds the same way a .d.ts file would if TypeScript shipped declaration-only packages natively.
  • Own its own tests. Each Feature declares the targets its Acceptance Criteria expect (abstract method), but the test implementations live in the package that owns the corresponding code. Tests travel with the code under test, not with the spec.
  • Re-export the kernel. Consumers import Feature/Requirement/decorators from @frenchexdev/requirements-shared-kernel directly. The vocabulary package does not pretend to be the kernel.

A concrete call-site

The compliance reporter — Tier 1 — opens the registries the kernel populates at module load time. Importing requirements-requirements from a consumer is what populates those registries with the universal Requirements:

import '@frenchexdev/requirements-requirements';
import {
  getRequirementRegistry,
  getSatisfactionLinks,
} from '@frenchexdev/requirements-shared-kernel';

const requirements = getRequirementRegistry();
const links = getSatisfactionLinks();

console.log(`${requirements.size} Requirements registered`);
console.log(`${links.size} Feature → Requirement satisfaction links`);

The side-effect import on line 1 is the only side effect the package has: by being imported, its index.ts re-exports execute, which causes each req-*.ts and each Feature file to evaluate, which causes the @Satisfies decorators to call the kernel's getSatisfactionLinks registry add-method, which makes both maps populated.

That side-effect-on-import pattern is what makes the system work without a build step. A consumer who runs tsx against a TypeScript file with the above imports gets a populated registry; a consumer who runs node against the compiled JavaScript gets the same registry, populated the same way. No factory call, no init(), no configuration. The kernel's registries are the integration boundary; the vocabulary package's side-effect imports are what fills them.

Why it is its own package

The case is the keystone of the whole mega-split.

First, the spec needs an importable name. If the Requirements lived in requirements-core/src/req-*.ts, then requirements-core would no longer be a zero-dep kernel — it would carry the universal Requirements that every other package wants to satisfy. The kernel's narrowness depends on isolation: the kernel ships the contracts, the vocabulary package ships the instances. Sharing one npm name between contracts and instances would force the kernel to be re-published every time a new Requirement is added, which is wrong: a new Requirement should not force a kernel version bump.

Second, dog-fooding requires a single point of truth. If two packages each shipped their own req-dog-food.ts copy — as the pre-split state did, with requirements and requirements-lib both carrying req-discoverable-traceability.ts — the trace graph would have two Requirements with the same ID, and the compliance reporter would either pick one arbitrarily or crash. Centralising the Requirements in requirements-requirements makes the "every piece of knowledge has one representation" rule physically enforced: a duplicate is a workspace conflict, not a silent disagreement.

Third, the vocabulary is the contract every team agrees to in DDD's Shared Kernel sense. The Tier-0 split into shared-kernel (infrastructure) and requirements-requirements (vocabulary) is the same distinction DDD makes between Ubiquitous Language (the shared vocabulary) and the Shared Kernel (the smallest tightly-controlled subset of code). The kernel package ships the kernel; the vocabulary package ships the language. Both Tier-0 packages together form the contract; together they are what every Tier-1+ package depends on.

The next seven pages cover the Tier-1 analyzers — the stateless functions that read the registries the kernel maintains and the vocabulary populates, and turn them into manifests, coverage reports, mutation verdicts, trace graphs, JSON specs, and version pins.

⬇ Download