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

Appendix A — Glossary

This appendix is a flat, alphabetical reference for every named construct the series introduces. Each entry is a two-to-four sentence definition followed by a deep link to the chapter that defines it. No prose, no narrative — scan for the term you need.

Entries are grouped into nine sections:

  1. Decorators — the six class and method decorators that wire the chain.
  2. Base classes and core types — Feature, Requirement<S>, ACResult, Priority, TestLevel.
  3. Requirement IDs (22) — every REQ-* that governs the package.
  4. Feature IDs (25) — every *Feature class that @Satisfies one or more requirements.
  5. Styles (5) — the built-in RequirementStyle presets.
  6. Scaffolders (7) — the pluggable test-generator registry.
  7. DDD vocabulary — the tactical-design terms the package re-enters in chapter 20.
  8. FSM vocabulary — the three finite-state machines that drive lifecycle.
  9. External standards referenced — EARS, SIL, ISO 29148, SysML, BDD, Volere, A3, PDCA, Kanban Classes of Service.

Decorators

@Exclude

Method decorator that removes a helper from requirement scanning. The compliance scanner and the ESLint rule both skip any method tagged @Exclude(), so utility functions inside a @FeatureTest-decorated class do not inflate the AC-verification registry. Used sparingly — only for genuinely local helpers that are neither ACs nor test methods. Defined in chapter 03.

@Expects

Method decorator placed on an abstract AC method of a Feature to declare which TestLevels are expected to verify it. The compliance scanner reads the arguments statically via AST (the runtime is a no-op) and builds the AC × TestLevel matrix that planWrites consumes. Absence of @Expects defaults to [TestLevel.Unit], keeping the common case zero-config. Defined in chapter 03.

@FeatureTest

Class decorator that binds a test class to a Feature subclass. It is generic over the Feature type, so @Verifies invoked on its methods gains keyof T safety and the compiler catches AC typos. It also auto-registers the class with vitest (generating a describe block internally), so no test file in the package contains bare describe or it calls — satisfying REQ-DOG-FOOD. Defined in chapter 03.

@Refines

Class decorator placed on a Requirement to declare that it refines (derives from, decomposes) one or more parent Requirements, aligned with SysML's refine/derive relation. It populates a bidirectional registry (getRefinementLinks()), so both parent.refinedBy() and child.refines() views are available to the trace core. Defined in chapter 03.

@Satisfies

Class decorator placed on a Feature to declare that it satisfies one or more Requirements, aligned with SysML's satisfy relation. The decorator populates a bidirectional registry (getSatisfactionLinks()), so both feature.satisfies() and requirement.satisfiedBy() queries are O(1) at scanner time. This is the single hop that connects the WHY tier to the WHAT tier. Defined in chapter 03.

@Verifies

Method decorator that binds a test method to the AC it verifies. The generic parameter is the Feature type carried by the enclosing @FeatureTest, and the argument is constrained to keyof T & string — so a typo in an AC name is a compile error, not a runtime "test not found". This is the single hop that connects the PROOF tier to the HOW-MEASURED tier. Defined in chapter 03.

Base classes and core types

ACResult

The discriminated return type of every abstract AC method on a Feature. Its shape forces tests to return a structured pass/fail record rather than a bare boolean or a thrown assertion, making AC outcomes first-class data that the compliance reporter can aggregate. Defined in chapter 03b.

Feature

Abstract base class representing the WHAT tier of the four-tier chain. A Feature subclass declares zero or more abstract AC methods returning ACResult, and is wired to the WHY tier via @Satisfies(Req1, Req2, …) class decorators. Every AC is verified by one or more tests via @FeatureTest + @Verifies. Defined in chapter 03b.

Priority

Enum-like branded type carried on both Requirement and Feature specs, used by the style validators and the compliance gate. IndustrialStyle keys its SIL gates on Priority; AgileStyle couples it to INVEST scoring. Defined in chapter 03b.

Requirement<S>

Abstract base class representing the WHY tier, generic over a RequirementStyle S. The type parameter pulls in the style's vocabulary, validators, templates and reporter, so a single Requirement is a style-aware object rather than a free-form record. Fields include typed statement, rationale, fitCriteria, verificationMethod, source, risk, refines, tracedTo, and history. Defined in chapter 03b.

TestLevel

Enum over the seven test levels the scaffolder registry supports: Unit, Functional, EndToEnd, Accessibility, Internationalisation, Visual, Performance. @Expects(…levels) uses it to declare expected verification coverage, and planWrites uses it to route generated test files into per-level directories. Defined in chapter 03b.

Requirement IDs (22)

REQ-AI-AS-IMPLEMENTER-ADAPTER

Requires that an AI coding agent can be driven as a pluggable adapter whose inputs are AC names and whose outputs are ACResult-returning test methods, with the DSL as contract. Defined in chapter 05.

REQ-AUDIT-TRAIL-HOOKS

Requires that every requirement mutation (create / approve / amend / retire) emits an append-only HistoryEntry usable as a 21 CFR Part 11-style electronic record. Defined in chapter 05.

REQ-BOOTSTRAP-ZERO-FRICTION

Requires that a fresh install of the package produces a working requirements compliance run within one command, with no per-project configuration file required. Defined in chapter 04.

REQ-DISCOVERABLE-TRACEABILITY

Requires that any spec, feature, AC or test be navigable to its neighbours in the requirement graph without out-of-band documentation. Defined in chapter 04.

REQ-DOG-FOOD

Requires that the package contain zero describe / it calls — every test must be expressed through @FeatureTest and @Verifies, proving the DSL is usable by its own authors. Defined in chapter 04.

REQ-DSL-COMPLETE

Requires that the DSL express every requirement-engineering concept the package needs — no escape hatch to plain strings, plain objects, or untyped YAML. Defined in chapter 04.

REQ-EDITOR-FIRST-CLASS

Requires that VS Code (and any JSON-schema-aware editor) provide completion, hover and validation on every requirement and feature spec file out of the box. Defined in chapter 05.

REQ-LIVE-FEEDBACK

Requires that the developer see compliance feedback (missing ACs, orphan tests, style violations) within the same second they save a file — not at CI time. Defined in chapter 05.

REQ-LOW-FRICTION-ACS

Requires that declaring a new AC cost one line of code (one abstract method) and carry zero boilerplate — the common case must be the cheap case. Defined in chapter 04.

REQ-MULTI-FSM-ORCHESTRATION

Requires that three finite-state machines (project lifecycle, per-feature, per-AC) run concurrently and cross-validate each other at every state transition. Defined in chapter 05.

REQ-ORTHOGONAL-TOGGLING

Requires that every style, scaffolder, and validator be independently toggleable without touching core DSL code, following open/closed at the plugin boundary. Defined in chapter 05.

REQ-PARALLEL-DELIVERABLE

Requires that the DSL ship as a standalone @frenchexdev/requirements package usable outside the host CV site — no implicit coupling to the parent monorepo. Defined in chapter 04.

REQ-PROPERTY-INVARIANTS

Requires that structural invariants of the DSL (bidirectional registry consistency, history monotonicity, ID uniqueness) be property-tested with fast-check, not merely example-tested. Defined in chapter 05.

REQ-REFACTOR-SAFE

Requires that renaming a Feature, a Requirement, or an AC never silently break traceability — compiler and codemod together catch every reference. Defined in chapter 05.

REQ-ROUND-TRIP-EDITABLE

Requires that every spec be editable either as TypeScript source or through a JSON-schema-driven editor, with round-trip equivalence between the two representations. Defined in chapter 04.

REQ-SCAFFOLD-EXTENSIBILITY

Requires that new test levels (beyond the seven built-ins) be addable by registering a TestScaffolder port — no fork, no core patch. Defined in chapter 05.

REQ-SCENARIO-DRIVEN-WORKFLOW

Requires that recorded scenarios (TUI sessions, AI adapter runs) be replayable deterministically from a JSON export, acting as regression fixtures for the workflow layer itself. Defined in chapter 05.

REQ-SPEC-IS-SOURCE-OF-TRUTH

Requires that the TypeScript spec file be the canonical artifact — no auxiliary database, no JIRA synchronisation boundary, no second source of record. Defined in chapter 04.

REQ-TUI-MODERN

Requires that interactive wizards (feature new, requirement new) use a modern TUI adapter (@clack/prompts), not home-grown readline. Defined in chapter 05.

REQ-VERSIONED-TRACEABILITY

Requires that every spec carry a $schemaVersion and an append-only history log, so traceability holds across schema migrations and never loses prior states. Defined in chapter 04.

REQ-VISUAL-TRACEABILITY

Requires that the requirement graph be renderable as a Mermaid diagram directly from the registry, with no manual diagram maintenance. Defined in chapter 05.

REQ-VOCAB-INDUSTRY-ALIGNED

Requires that every DSL term map to a SysML / ISO-29148 / Volere term where one exists — invented vocabulary is a last resort, not a default. Defined in chapter 04.

Feature IDs (25)

AuditHooksFeature

Delivers the HistoryEntry emitter and the append-only log writer that satisfy REQ-AUDIT-TRAIL-HOOKS. Defined in chapter 06.

BaseTypesFeature

Delivers the branded primitive types (RequirementId, FeatureId, AcName, IsoDate, Sentence, Percentage) and their runtime guards. Defined in chapter 06.

ClackAdapterFeature

Delivers the @clack/prompts shell that backs feature new and requirement new wizards, satisfying REQ-TUI-MODERN. Defined in chapter 06.

ComplianceCoreFeature

Delivers the AST-driven compliance scanner that reads @FeatureTest/@Verifies/@Expects decorators and computes the AC × test matrix. Defined in chapter 06.

ComplianceReportFeature

Delivers the requirements compliance [--strict] CLI command and its human-readable / JSON report formats. Defined in chapter 06.

DecoratorsFeature

Delivers the six decorators themselves (@FeatureTest, @Verifies, @Expects, @Exclude, @Satisfies, @Refines) and their runtime registries. Defined in chapter 06.

FeatureBidirectionalSyncFeature

Delivers the two-way diff between a TypeScript spec file and its JSON editor representation, satisfying REQ-ROUND-TRIP-EDITABLE. Defined in chapter 06.

FeatureHeuristicSuggesterFeature

Delivers the name-similarity suggester that proposes @Satisfies / @Verifies candidates when a spec is created or renamed. Defined in chapter 06.

FeatureMermaidGraphFeature

Delivers the Mermaid-graph emitter that renders the full Requirement → Feature → AC → Test chain, satisfying REQ-VISUAL-TRACEABILITY. Defined in chapter 06.

FeatureNewCommandFeature

Delivers the requirements feature new interactive wizard, including the satisfiedBy multiselect that can recurse into requirement new. Defined in chapter 06.

FeatureRenameCodemodFeature

Delivers the rename codemod that updates every reference to a Feature, Requirement, or AC across the tree, satisfying REQ-REFACTOR-SAFE. Defined in chapter 06.

FeatureSchemaCommandFeature

Delivers the requirements schema register command that writes the JSON Schemas into .vscode/settings.json, satisfying REQ-EDITOR-FIRST-CLASS. Defined in chapter 06.

FeatureSyncCommandFeature

Delivers the requirements feature sync <spec> command with coloured diff and three-way Apply / Review / Cancel prompt. Defined in chapter 06.

FeatureTraceExplorerTuiFeature

Delivers the interactive TUI trace explorer that walks the graph from a seed node in either direction. Defined in chapter 06.

FeatureWatchModeFeature

Delivers the file-watcher that re-runs compliance within the save-to-feedback budget, satisfying REQ-LIVE-FEEDBACK. Defined in chapter 06.

PropertyTestingFeature

Delivers the fast-check invariant suite (16 properties × 200 runs) that proves registry and history structural laws, satisfying REQ-PROPERTY-INVARIANTS. Defined in chapter 06.

RequirementCommandsFeature

Delivers the requirements requirement new | sync | list | show | orphan command family. Defined in chapter 06.

ScaffoldCoreFeature

Delivers generateScaffoldForSpec and planWrites — the core that turns a Feature spec plus its @Expects matrix into a write plan. Defined in chapter 06.

ScaffolderRegistryFeature

Delivers the TestScaffolder port and the seven built-in implementations (unit / functional / e2e / a11y / i18n / visual / perf), satisfying REQ-SCAFFOLD-EXTENSIBILITY. Defined in chapter 06.

ScenarioOrchestratorFeature

Delivers the scenario replay engine that satisfies REQ-SCENARIO-DRIVEN-WORKFLOW, including record / play / validate / export commands. Defined in chapter 06.

SmartConstructorsFeature

Delivers the parse-don't-validate smart constructors for every branded primitive, returning ParseError on failure rather than throwing TypeError. Defined in chapter 06.

TestBindingsScannerFeature

Delivers the AST scanner that walks test files and extracts every @FeatureTest / @Verifies binding for the compliance core. Defined in chapter 06.

TogglingFeature

Delivers the style / scaffolder / validator toggle system that satisfies REQ-ORTHOGONAL-TOGGLING. Defined in chapter 06.

TraceCoreFeature

Delivers the graph queries trace gaps, trace matrix <feature>, and trace chain <id> <ac> over the bidirectional registries. Defined in chapter 06.

VersioningFeature

Delivers the $schemaVersion field and the migration pipeline that satisfies REQ-VERSIONED-TRACEABILITY. Defined in chapter 06.

Styles (5)

AgileStyle

A RequirementStyle preset aligned with Scrum / XP / SAFe / BDD. Its validator enforces the INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable) on each requirement, and its templates produce Given/When/Then scenarios compatible with Gherkin-based runners. Defined in chapter 11.

DefaultStyle

The baseline RequirementStyle, aligned with ISO/IEC/IEEE 29148 and Volere, with EARS statements as the primary pattern. It is the style every requirement in the package uses unless otherwise specified, and the style Requirement<S> defaults to when S is left inferred. Defined in chapter 08.

IndustrialStyle

A heavy-gate RequirementStyle aligned with IEC 61508 / 61511 / 62443 / 61131-3 / 61850, ISA-88/95/18.2, 21 CFR Part 11, and GAMP 5. It drives a thirteen-state lifecycle and a SIL 1–4 priority coupling, so a requirement cannot be approved without a validated hazard analysis and a signed electronic record. Defined in chapter 09.

KanbanStyle

A RequirementStyle aligned with David J. Anderson's Kanban Method. It models requirements as work items with explicit Classes of Service (Standard, Fixed-Date, Expedite, Intangible) and couples validators to WIP limits and cycle-time distributions rather than to EARS patterns. Defined in chapter 11.

LeanStyle

A RequirementStyle aligned with Toyota's Lean tradition: A3 problem-solving, PDCA cycles, Gemba walks, Value Stream Mapping, and Kaizen. Its templates emit A3 headings (Background, Current Condition, Goal, Analysis, Countermeasures, Plan, Follow-up) and its validator enforces root-cause evidence before a requirement can leave the analysed state. Defined in chapter 10.

Scaffolders (7)

a11y scaffolder

Emits @FeatureTest/@Verifies test skeletons routed to test/a11y/, wired to the accessibility tooling of the host project (axe, pa11y). Selected when an AC declares @Expects(TestLevel.Accessibility). Defined in chapter 14.

e2e scaffolder

Emits @FeatureTest/@Verifies test skeletons routed to test/e2e/, wired to the host project's end-to-end runner (Playwright in this monorepo). Selected when an AC declares @Expects(TestLevel.EndToEnd). Defined in chapter 14.

functional scaffolder

Emits test skeletons routed to test/functional/ — tests that exercise full modules through their public API without external process boundaries. Selected when an AC declares @Expects(TestLevel.Functional). Defined in chapter 14.

i18n scaffolder

Emits test skeletons routed to test/i18n/, verifying that translated strings, plural forms, and locale-dependent formatting hold for the locales the host project ships. Selected when an AC declares @Expects(TestLevel.Internationalisation). Defined in chapter 14.

perf scaffolder

Emits test skeletons routed to test/perf/, asserting runtime budgets against measured baselines. Selected when an AC declares @Expects(TestLevel.Performance). Defined in chapter 14.

unit scaffolder

Emits test skeletons routed to test/unit/ — the default level when no @Expects is present. Targets pure functions and single-class behaviour with no I/O. Defined in chapter 14.

visual scaffolder

Emits test skeletons routed to test/visual/, comparing rendered output against stored baselines. Selected when an AC declares @Expects(TestLevel.Visual). Defined in chapter 14.

DDD vocabulary

Aggregate

A cluster of Entity and Value Object instances treated as a single consistency boundary. In the DSL re-reading of chapter 20, each Feature plus its AC methods forms an aggregate rooted on the Feature class — the registry never exposes ACs outside the Feature they belong to. Defined in chapter 20.

Bounded Context

A linguistic and model boundary within which a term has a single, unambiguous meaning. The package itself is one bounded context; each style (DefaultStyle, IndustrialStyle, …) is a sub-context with its own vocabulary. Defined in chapter 20.

Entity

An object with identity that persists across mutations. In the DSL, Requirement and Feature subclasses are entities keyed by their class name; their AC methods and history entries hang off that identity. Defined in chapter 20.

Policy

A named rule that governs state transitions or validations. In the DSL, style validators (INVEST, SIL gates, A3 completeness) are policies attached to the RequirementStyle and applied at transition time by the per-feature and per-AC FSMs. Defined in chapter 20.

Use Case

An application-layer coordinator orchestrating domain objects to fulfil an intent. Each CLI command (compliance, trace gaps, feature new, …) is one use case; its handler depends on domain types (Feature, Requirement<S>) and on ports (FileSystem). Defined in chapter 20.

Value Object

An immutable object defined by its attributes, with no identity of its own. In the DSL, EarsStatement, FitCriterion, Rationale, Evidence, and RequirementSource are value objects — two instances with the same fields are the same value. Defined in chapter 20.

FSM vocabulary

PerAcFsm

The innermost of the three finite-state machines. One instance per AC method on every Feature; its state records whether the AC is unverified, verified-by-unit, verified-by-functional, verified-by-e2e (and so on), failing, or excluded. Its transitions are triggered by compliance-scan events. Defined in chapter 15.

PerFeatureFsm

The middle FSM. One instance per Feature class; its state aggregates the PerAcFsm states (fully-covered, partially-covered, orphan, retired) and couples to the style validator's lifecycle (draft / reviewed / approved / amended). Defined in chapter 15.

ProjectLifecycleFsm

The outermost FSM. A single instance per package; its state aggregates the PerFeatureFsm instances and the strict-compliance gate (green / yellow / red). The CLI's compliance --strict exit code is a direct projection of this FSM's current state. Defined in chapter 15.

External standards referenced

21 CFR Part 11

US Food and Drug Administration regulation governing electronic records and electronic signatures in FDA-regulated industries. IndustrialStyle and AuditHooksFeature align with its Part E requirements — append-only records, attributable signatures, audit trails. Defined in chapter 09.

A3

A Toyota problem-solving format that fits a full analysis onto a single A3-size sheet, with eight canonical headings from Background to Follow-up. LeanStyle templates emit these headings and its validator enforces completeness before a requirement can be approved. Defined in chapter 10.

BDD

Behaviour-Driven Development, popularised by Dan North: requirements expressed as Given/When/Then scenarios tied to executable specifications. AgileStyle templates produce BDD-compatible scenarios, and the functional scaffolder maps Given/When/Then arms onto test methods. Defined in chapter 11.

EARS

Easy Approach to Requirements Syntax, five structured patterns (Ubiquitous, Event-driven, State-driven, Optional-feature, Unwanted-behaviour) plus a free-form fallback. DefaultStyle uses EarsStatement as its primary statement discriminated union, so the editor can auto-complete the correct pattern arm. Defined in chapter 08.

GAMP 5

Good Automated Manufacturing Practice guidance from ISPE, the de-facto standard for validating computerised systems in regulated pharmaceutical and life-sciences contexts. IndustrialStyle references it as a source for its heavy-gate lifecycle and for the required evidence types. Defined in chapter 09.

IEC 61508

International Electrotechnical Commission standard on functional safety of electrical, electronic and programmable electronic safety-related systems. It defines the Safety Integrity Level (SIL) concept that IndustrialStyle couples to Priority. Defined in chapter 09.

ISO 29148

ISO/IEC/IEEE 29148:2018, the canonical standard for systems-and-software-engineering requirements processes. DefaultStyle's vocabulary (statement / rationale / fit criterion / verification method / source / priority / risk) maps one-to-one to its required attributes. Defined in chapter 08.

Kanban Classes of Service

David J. Anderson's classification of work items into Standard, Fixed-Date, Expedite, and Intangible service classes, each with its own policy and SLA. KanbanStyle exposes the classification as a discriminated union on Requirement.priority and drives its flow metrics off it. Defined in chapter 11.

PDCA

The Deming / Shewhart Plan-Do-Check-Act cycle, the backbone of continuous-improvement practice. LeanStyle's lifecycle maps each state transition onto a PDCA quadrant, so a requirement's history reads as a sequence of closed PDCA loops. Defined in chapter 10.

SIL

Safety Integrity Level, four discrete risk-reduction tiers defined by IEC 61508 (SIL 1 = lowest, SIL 4 = highest). IndustrialStyle projects Priority onto SIL and gates approval on the evidence class each tier demands (hazard analysis, FMEA, independent assessment). Defined in chapter 09.

SysML

Systems Modelling Language, an OMG standard extending UML for systems engineering. Its satisfy, refine, derive and verify relations are the direct ancestors of the DSL's @Satisfies, @Refines, and @Verifies decorators. Defined in chapter 19b.

Volere

The requirements template and process developed by James and Suzanne Robertson. DefaultStyle borrows its fit-criterion / rationale / source separation, which is why the DSL's Requirement carries those as distinct typed fields rather than one free-form description. Defined in chapter 08.

See also

⬇ Download