Chapter 06 — Twenty-Five Features Mapped

Chapters 04 and 05 walked the 22 Requirements. This chapter walks the 25 Features. Same graph, other side.

Chapters 04 and 05 enumerated the twenty-two Requirements of the @frenchexdev/requirements package, each with its provenance, its EARS statement, its fit criteria, its risk, and a paraphrase of the Features that satisfy it. Those two chapters drew the bipartite graph from the Requirement side: here is a WHY, and here is the WHAT that answers it.

This chapter draws the same graph from the other side. Here is a WHAT, and here are the WHYs that justify it. Twenty-five Feature classes. Their @Satisfies(...) lists. Their AC counts. Their priority flags. Their enabled flags. The test files where each one is verified.

The two views are not redundant — they are adjoint. The REQ-side view tells you which deliverables the project has committed to closing a given obligation. The Feature-side view tells you how much of that deliverable's surface is justified by the set of obligations it claims to meet. A Feature that satisfies seven Requirements (and there is one such Feature in this package) is a node you read very differently from a Feature that satisfies one (and there are several). A Feature that satisfies zero Requirements would be, by the lights of compliance --strict, an orphan — but there are none of those in this package, by construction.

The running example introduced in chapter 00 — FEATURE-TRACE-EXPLORER-TUI — returns here with its full AC walk. It is the smallest non-trivial two-REQ satisfier in the codebase: ten ACs, three @Satisfies targets, enabled flag off because it is Tier-2 roadmap. That combination makes it the cleanest pedagogical specimen.

The showcase — FEATURE-NEW-COMMAND, the interactive wizard for bootstrapping new Features — returns with its own AC walk. It satisfies seven Requirements, not three, and exposes twenty-two abstract ACs spanning wizard flows, replay, dry-run, templates, schema validation, and post-apply editor hand-off. It is the maximally-connected Feature in the bipartite graph, the node whose removal would leave the most orphaned obligations.

Between those two walkthroughs, the twenty-three other Features are enumerated in a compressed but exhaustive format: class header, @Satisfies list paraphrased, AC count, one or two illustrative methods, and deep links back to the two Requirement chapters so every edge is navigable in both directions.

How to read a Feature entry

Each entry in the enumeration section below follows a fixed schema so you can skim or drill as needed:

Heading — ### FEATURE-XXX — title. The id field of the class, then the title string literal.
Class header — the @Satisfies(...) decorator plus the four readonly properties (id, title, priority, optional enabled). Copied verbatim from the .ts source.
AC count — the number of abstract methodName(): ACResult; declarations in the class. ACs are abstract methods returning an ACResult; the count is the surface the test files must cover.
Paraphrase — one sentence summarising what the ACs, taken as a set, demand of the implementation.
Notable ACs — one or two abstract methods singled out because they illustrate a pattern (error path, integration via a port, end-to-end walk).
Satisfied Requirements — the @Satisfies targets, each written as a deep link into chapter 04 or 05 where the Requirement is fully documented. When a Feature satisfies seven Requirements, you get seven links.

The enabled flag deserves a note. A Feature with readonly enabled = false; is a roadmap Feature — its class is declared, its ACs are enumerated, but no tests are expected to cover them yet and compliance --strict ignores them. They are declarations of intent, compiled against the DSL, ready to flip to enabled = true when their stream comes around. Seventeen of the twenty-five Features in this package are currently enabled; eight are roadmap. Both kinds are enumerated below, with the roadmap Features clearly marked.

Priority deserves a second note. The enum has four levels — Critical, High, Medium, Low. Critical features gate compliance --strict: if any of their ACs lacks a bound test, the command exits non-zero. High features are active work. Medium features are scheduled. Low features are acknowledged-but-deferred. Five of the twenty-five are Critical, twelve are High, six are Medium, two are Low.

The cross-reference rule is that every link to a Requirement in this chapter targets the chapter 04 or chapter 05 anchor for that Requirement, not the raw source file. That keeps the reading loop inside the blog series rather than flipping to the package. When a link says (chapter 04) it means the Requirement is documented in the first REQ chapter; (chapter 05) means the second. A handful of Requirements in this package were added after chapters 04–05 were written; those links point forward to chapter 08, the roadmap-vs-done delta.

With the schema fixed, the enumeration follows. It is long on purpose: the bipartite is big, and this chapter is the only place where every edge is written out in full.

The twenty-five Features, enumerated

FEATURE-AUDIT-TRAIL-HOOKS — extended ChangeKind, optional signature, no-op decorators

@Satisfies(
  ReqAuditTrailHooksRequirement,
  ReqDogFoodRequirement,
  ReqParallelDeliverableRequirement,
)
export abstract class AuditHooksFeature extends Feature {
  readonly id = 'AUDIT-TRAIL-HOOKS';
  readonly title = 'Audit-trail hooks — extended ChangeKind + optional signature field + no-op decorators';
  readonly priority = Priority.Medium;
  readonly enabled = false;
}

AC count: eight. Priority: Medium. Enabled: false (Tier-2 roadmap).

The ACs demand that the ChangeKind discriminated union extend with reviewed and approved-by, that HistoryEntry gain an optional signature field typed as ed25519 or RSA-SHA256, that two new decorators (@Reviewed, @SignedOff) exist as no-ops at runtime, that history remains append-only, and that the pre-existing JSON serialisation stays backward-compatible. One end-to-end AC rounds the whole signed-history cycle through spec.json and back.

Notable: historyAppendIsImmutable() is the invariant AC — it asserts that no code path mutates a prior history entry. This is a property-test candidate covered by PROPERTY-TESTING.

Satisfies: REQ-AUDIT-TRAIL-HOOKS (chapter 05), REQ-DOG-FOOD (chapter 04), REQ-PARALLEL-DELIVERABLE (chapter 05).

FEATURE-BASE-TYPES — Priority, TestLevel, Feature abstract class

@Satisfies(
  ReqDslCompleteRequirement,
  ReqRefactorSafeRequirement,
)
export abstract class BaseTypesFeature extends Feature {
  readonly id = 'BASE-TYPES';
  readonly title = 'Requirements DSL — base types (Priority, TestLevel, Feature)';
  readonly priority = Priority.High;
}

AC count: three. Priority: High. Enabled: true.

The smallest Feature in the package. Three ACs: priorityEnumExposesAllLevels, testLevelEnumExposesAllLevels, featureClassIsAbstract. They assert the existence and shape of the three base types every other Feature depends on. Small surface, maximum leverage — if these ACs broke, almost every other test would go red.

Notable: featureClassIsAbstract() is tested by attempting new Feature(...) through a typed indirection that should fail at runtime — ensuring the abstract class contract is honoured beyond type erasure.

Satisfies: REQ-DSL-COMPLETE (chapter 04), REQ-REFACTOR-SAFE (chapter 05).

FEATURE-CLACK-ADAPTER — RealPrompt + openInEditor, no readline, no raw process

@Satisfies(
  ReqTuiModernRequirement,
  ReqParallelDeliverableRequirement,
  ReqDogFoodRequirement,
)
export abstract class ClackAdapterFeature extends Feature {
  readonly id = 'CLACK-ADAPTER';
  readonly title = '@clack/prompts adapter — realPrompt() + openInEditor(), no readline, no raw process';
  readonly priority = Priority.Medium;
}

AC count: nineteen. Priority: Medium. Enabled: true.

The adapter that concretely meets REQ-TUI-MODERN — the port definition lives in src/ports/Prompt.ts, this Feature binds it to the @clack/prompts library plus an editor-shell helper. ACs cluster into five groups: port completeness (one AC), per-method delegation (six ACs, one per clack method), cancellation semantics (four ACs, one per cancellable entry point, converting the clack-returned symbol into a typed PromptCancelledError), the editor shell (four ACs covering shell-quoting, no-op on empty lists, failure-swallow), and two isolation invariants (moduleHasNoReadlineImport, moduleHasNoDirectProcessOrChildProcessImport) tested via source-file introspection.

Notable: openInEditorSilentlySwallowsRunnerFailures() captures a design choice — if the editor fails to open, the wizard should not crash. The AC pins that choice in the type system.

Satisfies: REQ-TUI-MODERN (chapter 04), REQ-PARALLEL-DELIVERABLE (chapter 05), REQ-DOG-FOOD (chapter 04).

FEATURE-COMPLIANCE-CORE — feature parsing, coverage loading, runtime rollup, orphans

@Satisfies(
  ReqDiscoverableTraceabilityRequirement,
  ReqVisualTraceabilityRequirement,
)
export abstract class ComplianceCoreFeature extends Feature {
  readonly id = 'COMPLIANCE-CORE';
  readonly title = 'Compliance scanner — core (feature parsing, coverage loading, runtime rollup, orphans)';
  readonly priority = Priority.Critical;
}

AC count: forty-three. Priority: Critical. Enabled: true.

The biggest unit-tested Feature in the package. Forty-three ACs across seven functions: parseFeatureSource (sixteen ACs covering every branch of the TypeScript AST walker), readFeatures (three), normalizeCoveragePath (three, cross-platform), findLatestCoverageSummary (eight, covering the run-id lookup and the lex-sorted newest-run fallback), loadCoverageSummary (three), computeRuntimeCoverage (seven, covering disabled / empty / missing / partial / ok / min-pct), findOrphanSourceFiles (four).

Every branch in src/analysis/compliance-core.ts is claimed by exactly one AC — that is the discipline this Feature encodes. When 100% branch coverage starts to ratchet down, the delta is visible at the AC granularity, not the file granularity.

Notable: parseFeatureSourceDefaultsToUnitLevelWhenNoExpects() captures the rule that an AC without an @Expects decorator is assumed to want a unit test. runtimeCoverageSomeMissingReturnsPartial() captures the three-state output of the runtime check: ok, partial, missing.

Satisfies: REQ-DISCOVERABLE-TRACEABILITY (chapter 04), REQ-VISUAL-TRACEABILITY (chapter 04).

FEATURE-COMPLIANCE-REPORT — table, ANSI, cross-reference, console rendering

@Satisfies(
  ReqDiscoverableTraceabilityRequirement,
  ReqVisualTraceabilityRequirement,
)
export abstract class ComplianceReportFeature extends Feature {
  readonly id = 'COMPLIANCE-REPORT';
  readonly title = 'Compliance scanner — report assembly, rendering, JSON payloads';
  readonly priority = Priority.Critical;
}

AC count: one hundred and one. Priority: Critical. Enabled: true.

The largest Feature in the package by AC count — one hundred and one abstract methods. The file it covers (src/analysis/compliance-report.ts) is the reporting layer that turns the core's output into formatted tables, JSON payloads, and coloured console renders. The ACs cluster into thirteen functional groups: table and ANSI helpers (nine ACs), hasBareDescribeOrIt detection (nine ACs, one per context — line comment, block comment, single-quote string, etc.), validateFsmFeatureLinks (six), test-file scanning (thirteen, one per test level and fallback), bindings summary (six), cross-reference (eleven), JSON payload assembly (seven), test-indexed JSON (four), glyph selection (four), runtime-cell formatting (six), bindings-cell formatting (five), traceability glyph (four), coloured bindings cell (five), console rendering (seventeen covering every flag and every branch), test-report rendering (four).

The file enforces 100% branch coverage as a gate; every branch is named in exactly one AC. When chapter 07 walks the test file that covers this Feature, you will see one hundred and one @Verifies(...) bindings, one per AC.

Notable: hasBareDetectsDescribeCall() and hasBareDetectsItCall() are the two ACs that encode the REQ-DOG-FOOD universal prohibition — the scanner that detects bare describe/it in test files. renderConsoleQualityGateFailOnCriticalUncovered() captures the gate that fails compliance --strict.

Satisfies: REQ-DISCOVERABLE-TRACEABILITY (chapter 04), REQ-VISUAL-TRACEABILITY (chapter 04).

FEATURE-DECORATORS — @FeatureTest, @Verifies, @Expects, @Exclude

@Satisfies(
  ReqDslCompleteRequirement,
  ReqVocabIndustryAlignedRequirement,
)
export abstract class DecoratorsFeature extends Feature {
  readonly id = 'DECORATORS';
  readonly title = 'Requirements DSL — decorators (@FeatureTest, @Verifies, @Expects, @Exclude)';
  readonly priority = Priority.Critical;
}

AC count: thirteen. Priority: Critical. Enabled: true.

The decorator surface the rest of the package consumes. Thirteen ACs cover: registry accessors (two), @FeatureTest (seven — metadata stamping, backfill-on-prior-registry-entries, auto-registration with vitest globals, skip-when-globals-absent, skip-constructor, skip-excluded-methods, timeout passthrough), @Verifies (two — registry ref, test-class and method-name capture), @Expects (one — runtime no-op), @Exclude (one — method-key stored in excluded set).

The @FeatureTest auto-registration with vitest globals is the glue that makes dog-fooding work: annotating a test class with @FeatureTest(X) causes vitest to discover and run its methods without any describe or it. This is the single most important decorator in the package, and its semantics are pinned by seven ACs.

Notable: featureTestBackfillsFeatureNameOnPriorRegistryEntries() captures a subtle ordering rule — @Verifies may run before @FeatureTest (decorators evaluate bottom-up then class-wise), and the registry must still end up consistent.

Satisfies: REQ-DSL-COMPLETE (chapter 04), REQ-VOCAB-INDUSTRY-ALIGNED (chapter 05).

FEATURE-BIDIRECTIONAL-SYNC — either .ts class or .spec.json is authoritative

@Satisfies(
  ReqRoundTripEditableRequirement,
  ReqDogFoodRequirement,
  ReqParallelDeliverableRequirement,
)
export abstract class FeatureBidirectionalSyncFeature extends Feature {
  readonly id = 'FEATURE-BIDIRECTIONAL-SYNC';
  readonly title = 'Bidirectional sync — either .ts class or .spec.json is authoritative';
  readonly priority = Priority.Medium;
  readonly enabled = false;
}

AC count: ten. Priority: Medium. Enabled: false (Tier-2 roadmap).

Bidirectional round-trip: today feature sync <spec> is one-way (spec-authoritative, source regenerated). This roadmap Feature extends it so edits to .ts classes flow back into .spec.json. Ten ACs: TS→JSON, JSON→TS, three-cycle idempotence, comment + decorator-order preservation, ambiguous-merge refusal, divergence detection, TS-does-not-compile refusal, FileSystem-port write, schema-version emission, end-to-end TS edit flowing into JSON and back.

Notable: roundTripIsIdempotentAfterThreeCycles() is the algebraic invariant — sync(sync(sync(x))) == sync(x) — a property-test candidate.

Satisfies: REQ-ROUND-TRIP-EDITABLE (chapter 05), REQ-DOG-FOOD (chapter 04), REQ-PARALLEL-DELIVERABLE (chapter 05).

FEATURE-HEURISTIC-SUGGESTER — n-gram + verb patterns from repo corpus, zero LLM

@Satisfies(
  ReqLowFrictionAcsRequirement,
  ReqDogFoodRequirement,
  ReqParallelDeliverableRequirement,
)
export abstract class FeatureHeuristicSuggesterFeature extends Feature {
  readonly id = 'FEATURE-HEURISTIC-SUGGESTER';
  readonly title = 'Wizard AC name suggester — n-gram + verb patterns from repo corpus, zero LLM';
  readonly priority = Priority.Low;
  readonly enabled = false;
}

AC count: nine. Priority: Low. Enabled: false (Tier-2 roadmap).

Offline AC-name suggester for the wizard. Nine ACs: plausible names, deterministic-and-offline, ranked-by-score, three-to-five-candidates, graceful-on-empty-corpus, reject-invalid-camelCase, read-via-FileSystem-port, called-from-wizard-before-ac-prompt, end-to-end tab-acceptance.

Notable: acSuggesterIsDeterministicAndOffline() — zero LLM, zero network. The suggestion is a hash of the repo corpus, not a Claude call.

Satisfies: REQ-LOW-FRICTION-ACS (chapter 05), REQ-DOG-FOOD (chapter 04), REQ-PARALLEL-DELIVERABLE (chapter 05).

FEATURE-MERMAID-GRAPH — full REQ→FEAT→AC→TEST DAG

@Satisfies(
  ReqVisualTraceabilityRequirement,
  ReqDogFoodRequirement,
  ReqParallelDeliverableRequirement,
)
export abstract class FeatureMermaidGraphFeature extends Feature {
  readonly id = 'FEATURE-MERMAID-GRAPH';
  readonly title = '`requirements trace graph --format mermaid` — full REQ→FEAT→AC→TEST DAG';
  readonly priority = Priority.Medium;
  readonly enabled = false;
}

AC count: ten. Priority: Medium. Enabled: false (Tier-2 roadmap).

The command that emits the four-tier DAG as a mermaid flowchart. Ten ACs: mermaid emission, disabled-Feature highlighting, covered-vs-uncovered AC distinguishing, AC-grouping-under-Feature, @Refines edges between Requirements, unknown-format refusal, empty-corpus warning, FileSystem-port discovery, stdout-or-file output, end-to-end self-rendering into README.

Notable: traceGraphRendersRefinesEdgesBetweenRequirements() — when Requirements form a tree via @Refines, the mermaid must draw those edges. The diagram is not just bipartite; it is four-tier with an inner tree.

Satisfies: REQ-VISUAL-TRACEABILITY (chapter 04), REQ-DOG-FOOD (chapter 04), REQ-PARALLEL-DELIVERABLE (chapter 05).

FEATURE-NEW-COMMAND — interactive Feature bootstrap wizard

@Satisfies(
  ReqBootstrapZeroFrictionRequirement,   // primary
  ReqSpecIsSourceOfTruthRequirement,     // joint: preview before write
  ReqEditorFirstClassRequirement,        // joint: emits $schema key
  ReqTuiModernRequirement,               // joint: uses Prompt port
  ReqDslCompleteRequirement,             // joint: wizard asks which Requirement(s)
  ReqParallelDeliverableRequirement,     // joint: one of the parallel streams
  ReqDogFoodRequirement,                 // joint: tests use @FeatureTest
)
export abstract class FeatureNewCommandFeature extends Feature {
  readonly id = 'FEATURE-NEW-COMMAND';
  readonly title = '`requirements feature new` — interactive Feature bootstrap wizard';
  readonly priority = Priority.High;
}

AC count: twenty-two. Priority: High. Enabled: true.

The showcase Feature. Seven @Satisfies targets — more than any other Feature in the package — and twenty-two abstract ACs spanning wizard flow (five), replay (three), source generation (three), test scaffolding (three), preview/dry-run (three), post-apply editor (one), safety (one), cross-link (one), schema validation (one), templates (one), coverage delta (one), end-to-end (one). Full walkthrough in the Running-example deep-dive — NEW-COMMAND section below.

Notable: walksFullWizardEndToEnd() — the single end-to-end AC that drives the wizard through every code path in a single test. refusesOverwriteUntrackedFile() — the safety AC that protects against clobbering user work.

Satisfies: REQ-BOOTSTRAP-ZERO-FRICTION (chapter 04), REQ-SPEC-IS-SOURCE-OF-TRUTH (chapter 04), REQ-EDITOR-FIRST-CLASS (chapter 04), REQ-TUI-MODERN (chapter 04), REQ-DSL-COMPLETE (chapter 04), REQ-PARALLEL-DELIVERABLE (chapter 05), REQ-DOG-FOOD (chapter 04).

FEATURE-RENAME-CODEMOD — ts-morph-driven feature / requirement / ac rename

@Satisfies(
  ReqRefactorSafeRequirement,
  ReqDogFoodRequirement,
  ReqParallelDeliverableRequirement,
)
export abstract class FeatureRenameCodemodFeature extends Feature {
  readonly id = 'FEATURE-RENAME-CODEMOD';
  readonly title = '`requirements feature rename` + `requirements requirement rename` — ts-morph-driven codemod';
  readonly priority = Priority.Medium;
  readonly enabled = false;
}

AC count: eleven. Priority: Medium. Enabled: false (Tier-2 roadmap).

The codemod that lets you rename a Feature ID, a Requirement ID, or an AC name and have every @Satisfies/@Verifies call-site update in lockstep. Eleven ACs: feature-rename-updates-all-references, requirement-rename-updates-satisfies, ac-rename-updates-verifies, on-disk filename update, spec.json id-field update, conflict refusal, type-check refusal, invalid-id refusal, dry-run-by-default, unified-diff-to-stdout, FileSystem-port write, end-to-end flow across thirty call-sites.

Notable: renameRefusesWhenResultingCodeDoesNotTypeCheck() — the codemod is allowed to fail. It is never allowed to leave the repo in an uncompilable state.

Satisfies: REQ-REFACTOR-SAFE (chapter 05), REQ-DOG-FOOD (chapter 04), REQ-PARALLEL-DELIVERABLE (chapter 05).

FEATURE-SCHEMA-COMMAND — JSON Schema generation + VS Code binding

@Satisfies(
  ReqEditorFirstClassRequirement,        // primary
  ReqSpecIsSourceOfTruthRequirement,     // joint: ajv validates spec pre-write
  ReqParallelDeliverableRequirement,     // joint
  ReqDogFoodRequirement,                 // joint
)
export abstract class FeatureSchemaCommandFeature extends Feature {
  readonly id = 'FEATURE-SCHEMA-COMMAND';
  readonly title = '`requirements schema register` — JSON Schema generation + VS Code binding';
  readonly priority = Priority.Medium;
}

AC count: nine. Priority: Medium. Enabled: true.

Schema generation (three ACs covering the ajv-compatible emission, full spec-field coverage, enum matching) plus the register subcommand (three ACs: writes-vscode-settings, merges-into-existing, refuses-conflict-without-force) plus the $schema key emission in generated specs (one AC) plus pre-write ajv validation (one AC) plus --print flag (one AC).

Notable: registerCommandMergesIntoExistingSettings() — the command never clobbers a user's .vscode/settings.json; it performs a deep merge and leaves unrelated keys alone.

Satisfies: REQ-EDITOR-FIRST-CLASS (chapter 04), REQ-SPEC-IS-SOURCE-OF-TRUTH (chapter 04), REQ-PARALLEL-DELIVERABLE (chapter 05), REQ-DOG-FOOD (chapter 04).

FEATURE-SYNC-COMMAND — reconcile spec.json with on-disk files

@Satisfies(
  ReqSpecIsSourceOfTruthRequirement,     // primary
  ReqTuiModernRequirement,               // joint: preview uses Prompt port
  ReqParallelDeliverableRequirement,     // joint
  ReqDogFoodRequirement,                 // joint
)
export abstract class FeatureSyncCommandFeature extends Feature {
  readonly id = 'FEATURE-SYNC-COMMAND';
  readonly title = '`requirements feature sync` — reconcile spec.json with on-disk files';
  readonly priority = Priority.High;
}

AC count: ten. Priority: High. Enabled: true.

The one-way sync command. Ten ACs: loads-spec-from-json, diff-classifies-create-unchanged-modified, structured-hunks-via-jsdiff, colourises-add-remove-context, interactive-prompts-per-modified, unchanged-not-prompted, dry-run-renders-without-writing, yes-flag-applies-silently, never-touches-non-scaffold-test-files, end-to-end reconciliation.

Notable: neverTouchesNonScaffoldTestFiles() — the sync preserves hand-written tests. It only overwrites files it originally scaffolded.

Satisfies: REQ-SPEC-IS-SOURCE-OF-TRUTH (chapter 04), REQ-TUI-MODERN (chapter 04), REQ-PARALLEL-DELIVERABLE (chapter 05), REQ-DOG-FOOD (chapter 04).

FEATURE-TRACE-EXPLORER-TUI — interactive TTY browser over the traceability graph

@Satisfies(
  ReqDiscoverableTraceabilityRequirement,
  ReqDogFoodRequirement,
  ReqParallelDeliverableRequirement,
)
export abstract class FeatureTraceExplorerTuiFeature extends Feature {
  readonly id = 'FEATURE-TRACE-EXPLORER-TUI';
  readonly title = '`requirements explore` — interactive TTY browser over the traceability graph';
  readonly priority = Priority.Low;
  readonly enabled = false;
}

AC count: ten. Priority: Low. Enabled: false (Tier-2 roadmap).

The running example of chapters 00–05. Full AC walk in the Running-example deep-dive — TRACE-EXPLORER-TUI section below.

Satisfies: REQ-DISCOVERABLE-TRACEABILITY (chapter 04), REQ-DOG-FOOD (chapter 04), REQ-PARALLEL-DELIVERABLE (chapter 05).

FEATURE-WATCH-MODE — live revalidation on file change

@Satisfies(
  ReqLiveFeedbackRequirement,
  ReqDogFoodRequirement,
  ReqParallelDeliverableRequirement,
)
export abstract class FeatureWatchModeFeature extends Feature {
  readonly id = 'FEATURE-WATCH-MODE';
  readonly title = '`requirements watch` — live revalidation + compliance delta on file change';
  readonly priority = Priority.Medium;
  readonly enabled = false;
}

AC count: ten. Priority: Medium. Enabled: false (Tier-2 roadmap).

The watch-mode that re-runs validation and prints a one-line compliance delta on every save. Ten ACs: detects-spec-change, revalidates-within-latency-budget, debounces-rapid-succession, prints-one-line-delta, reacts-to-feature-ts-and-spec-json, surfaces-schema-violations-inline, ignores-editor-swap-files, uses-FileSystem-port-watcher, tears-down-on-ctrl-c, end-to-end burst-of-saves yields exactly one revalidation.

Notable: watchIgnoresTemporaryEditorSwapFiles() — editors write .swp, ~ or .tmp files during saves; the watcher must not trigger on those.

Satisfies: REQ-LIVE-FEEDBACK (chapter 04), REQ-DOG-FOOD (chapter 04), REQ-PARALLEL-DELIVERABLE (chapter 05).

FEATURE-PROPERTY-TESTING — fast-check on every pure function

@Satisfies(
  ReqPropertyInvariantsRequirement,
  ReqDogFoodRequirement,
)
export abstract class PropertyTestingFeature extends Feature {
  readonly id = 'PROPERTY-TESTING';
  readonly title = 'Property + fuzzy tests via fast-check on every pure function in src/cli/*';
  readonly priority = Priority.High;
}

AC count: seventeen. Priority: High. Enabled: true.

The property-test Feature. Seventeen ACs, each pinning one algebraic invariant: smart-constructors accept-iff-regex-matches, smart-constructors throw-ParseError-on-reject, smart-constructors never-throw-other-error-types, id-helpers idempotent-and-reversible, kebab-of-id lowercase, feature-class-name always-ends-with-Feature, requirement-class-name always-ends-with-Requirement, sentence accepts-iff-non-empty-and-terminated, percentage accepts-iff-finite-and-0-to-100, specToJson deterministic-and-roundtrips, specToJson always-has-schemaVersion-first, validateSpec never-crashes-on-random-input, validateStatement never-crashes-on-random-input, diffOfEqualContent yields-all-unchanged, diffOfMissingCurrent yields-all-create, renderStatement never-crashes-on-random-input.

Each invariant is fast-checked across 200 runs; the tests shrink on failure. One AC = one property = one fc.property(...) body.

Notable: smartConstructorsNeverThrowOtherErrorTypes() — every reject path must throw ParseError, never TypeError, never a generic Error. The property holds across arbitrary inputs including symbols, BigInts, and circular references.

Satisfies: REQ-PROPERTY-INVARIANTS (chapter 05), REQ-DOG-FOOD (chapter 04).

FEATURE-REQUIREMENT-COMMANDS — Requirement new / sync / list / show / orphan

@Satisfies(
  ReqDslCompleteRequirement,             // primary — this is the keystone
  ReqVocabIndustryAlignedRequirement,    // primary — @Satisfies / @Refines semantics
  ReqSpecIsSourceOfTruthRequirement,     // joint: reuses SyncPlan machinery
  ReqTuiModernRequirement,               // joint: wizard uses Prompt port
  ReqParallelDeliverableRequirement,     // joint
  ReqDogFoodRequirement,                 // joint
)
export abstract class RequirementCommandsFeature extends Feature {
  readonly id = 'REQUIREMENT-COMMANDS';
  readonly title = '`requirements requirement *` — Requirement bootstrap + sync + list + show + orphan';
  readonly priority = Priority.Critical;
}

AC count: eighteen. Priority: Critical. Enabled: true.

The keystone of the whole DSL — this is the Feature that makes Requirements a first-class entity, matching the showcase wizard (FEATURE-NEW-COMMAND) on the Requirement side of the bipartite. Six @Satisfies targets. Eighteen ACs clustering into: requirement new wizard (five), requirement sync (one, reuses the diff core), decorator surface (three — @Satisfies bidirectional registry, @Satisfies refuses-non-Requirement, @Refines parent-child), requirement show/list/orphan (three), four-tier trace chain (one), compliance --strict extended (two), feature new wizard extension (one), generative workflows (two — custom status workflow and custom risk taxonomy).

Notable: satisfiesDecoratorRegistersBidirectionalLink() — @Satisfies writes into a bidirectional registry so you can ask a Requirement for its Features and a Feature for its Requirements in O(1). projectCanDefineCustomStatusWorkflow() — the Style system is open: a project declares its own state machine and the Requirement class narrows to it at compile time.

Satisfies: REQ-DSL-COMPLETE (chapter 04), REQ-VOCAB-INDUSTRY-ALIGNED (chapter 05), REQ-SPEC-IS-SOURCE-OF-TRUTH (chapter 04), REQ-TUI-MODERN (chapter 04), REQ-PARALLEL-DELIVERABLE (chapter 05), REQ-DOG-FOOD (chapter 04).

FEATURE-SCAFFOLD-CORE — generate test stubs for uncovered ACs

@Satisfies(
  ReqScaffoldExtensibilityRequirement,
  ReqParallelDeliverableRequirement,
)
export abstract class ScaffoldCoreFeature extends Feature {
  readonly id = 'SCAFFOLD-CORE';
  readonly title = 'Test scaffold — generate stubs for uncovered ACs';
  readonly priority = Priority.High;
}

AC count: fifteen. Priority: High. Enabled: true.

The scaffold engine that emits @FeatureTest/@Verifies-shaped test stubs for uncovered ACs. Fifteen ACs across four functions: findUncoveredACs (six), generateUnitTestStub (three), generateE2eTestStub (two), buildScaffoldResult (three). One AC for the scaffold-preserves-feature-metadata invariant.

Notable: ignoresAcsAlreadyCoveredAtLevel() — the scaffolder never overwrites existing coverage; it only fills gaps.

Satisfies: REQ-SCAFFOLD-EXTENSIBILITY (chapter 05), REQ-PARALLEL-DELIVERABLE (chapter 05).

FEATURE-SCAFFOLDER-REGISTRY — pluggable TestScaffolder, one per TestLevel

@Satisfies(
  ReqScaffoldExtensibilityRequirement,
  ReqDogFoodRequirement,
  ReqParallelDeliverableRequirement,
)
export abstract class ScaffolderRegistryFeature extends Feature {
  readonly id = 'SCAFFOLDER-REGISTRY';
  readonly title = 'Pluggable TestScaffolder registry — one strategy per TestLevel, project-extensible';
  readonly priority = Priority.High;
}

AC count: seventeen. Priority: High. Enabled: true.

The registry that makes scaffolding open for extension. Seventeen ACs: registry surface (five — covers-every-level, returns-undefined-for-unknown, register-adds, register-overrides-default, list-returns-everything), built-in scaffolders (seven — one per TestLevel: unit, e2e, functional, a11y, i18n, visual, perf), universal output invariants (three — @FeatureTest/@Verifies only, no describe or it, filename-suffix convention), integration (two — planWrites enumerates, unknown-level yields typed error).

Notable: scaffolderOutputContainsNoDescribeOrIt() — this is the self-referential AC that closes the dog-food loop for every scaffolded test. Every generated test file is checked against the same scanner used by compliance --strict.

Satisfies: REQ-SCAFFOLD-EXTENSIBILITY (chapter 05), REQ-DOG-FOOD (chapter 04), REQ-PARALLEL-DELIVERABLE (chapter 05).

FEATURE-SMART-CONSTRUCTORS — branded primitives, parse-don't-validate

@Satisfies(
  ReqDslCompleteRequirement,
  ReqDogFoodRequirement,
)
export abstract class SmartConstructorsFeature extends Feature {
  readonly id = 'SMART-CONSTRUCTORS';
  readonly title = 'Branded primitives — parse-don\'t-validate smart constructors';
  readonly priority = Priority.Medium;
}

AC count: eighteen. Priority: Medium. Enabled: true.

The parse-don't-validate layer. Eighteen ACs, two per branded primitive (accept / reject): RequirementId, FeatureId, AcName, IsoDate, Sentence (three ACs: trim-and-terminator, reject-empty, reject-missing-terminator), Percentage (three ACs: zero-to-hundred, reject-out-of-range, reject-non-finite), ParseError (two: carries-field-and-value, name-is-ParseError), plus two runtime-guard ACs (string-constructors-throw-ParseError-on-non-string, percentage-throws-ParseError-on-non-number).

Notable: stringConstructorsThrowParseErrorOnNonStringRuntimeInput() — the runtime guard protects against FFI / JSON.parse callers bypassing TypeScript.

Satisfies: REQ-DSL-COMPLETE (chapter 04), REQ-DOG-FOOD (chapter 04).

FEATURE-REQUIREMENTS-SMOKE — CLI bin smoke tests

export abstract class SmokeFeature extends Feature {
  readonly id = 'REQUIREMENTS-SMOKE';
  readonly title = 'CLI bin smoke tests — sub-command happy paths';
  readonly priority = Priority.High;
}

AC count: five. Priority: High. Enabled: true.

The bin smoke tests. Five ACs: binPrintsHelpOnHelpFlag, complianceHelpListsFlags, traceHelpListsSubcommands, scaffoldHelpListsSubcommands, traceGapsOnEmptyFixtureDoesNotCrash. These run the actual compiled bin through child_process.spawn and assert on stdout.

Notable: the absence of a @Satisfies decorator on this one Feature. The SmokeFeature class is intentionally un-satisfied — it predates the Requirement stratum and exists for its own sake (bin hygiene). Chapter 08 discusses it as one of the deltas the Requirement migration did not retrofit.

Satisfies: (none) — grandfathered pre-Requirement Feature.

FEATURE-TEST-BINDINGS-SCANNER — AST walker over @FeatureTest/@Verifies test files

@Satisfies(
  ReqDiscoverableTraceabilityRequirement,
)
export abstract class TestBindingsScannerFeature extends Feature {
  readonly id = 'TEST-BINDINGS-SCANNER';
  readonly title = 'Test bindings scanner — AST walker over @FeatureTest/@Verifies test files';
  readonly priority = Priority.Critical;
}

AC count: sixty-nine. Priority: Critical. Enabled: true.

The second-largest Feature. Sixty-nine ACs over the AST walker that produces the inferred bindings manifest. Clusters: parseTestFile and extractors (eighteen), collectImports (seven), resolveTarget (four), isInScope (two), collectCalleeNames and getRootIdentifier (ten), collectReferencedNames + transitive + helpers (seventeen), aggregateTestBindings + sortManifest (nine), collectTestFiles and scanTestBindings (nine), diffManifests (eight).

This Feature is what makes requirements compliance --strict capable of checking that every @Verifies('acName') reference in every test file actually targets a known AC. Without this scanner, the DSL would be open-loop.

Notable: transitiveBreaksCyclesViaVisitedSet() — the helper-name walker follows this.foo() → helper() → innerHelper() chains and must terminate when helpers call each other cyclically.

Satisfies: REQ-DISCOVERABLE-TRACEABILITY (chapter 04).

FEATURE-ORTHOGONAL-TOGGLING — ToggleProvider port + @Toggle decorator + ReleaseStage

@Satisfies(
  ReqOrthogonalTogglingRequirement,
  ReqDogFoodRequirement,
  ReqParallelDeliverableRequirement,
)
export abstract class TogglingFeature extends Feature {
  readonly id = 'ORTHOGONAL-TOGGLING';
  readonly title = 'Orthogonal toggling — ToggleProvider port + @Toggle decorator + ReleaseStage enum';
  readonly priority = Priority.High;
  readonly enabled = false;
}

AC count: thirteen. Priority: High. Enabled: false (Tier-2 roadmap).

The feature-toggle Feature. Thirteen ACs across four clusters: port + decorator surface (five: ToggleProvider, @Toggle, @EnabledWhen, @AvailableFrom/Until, ReleaseStage-is-orthogonal-to-status), compliance integration (two: not-applicable for toggled-off ACs, --strict ignores not-applicable), rollout + context (two), error paths (two: unknown-gate-name, unknown-env-value), integration + testability (three: stub-provider, injection-via-CLI-shell, end-to-end toggled-off AC does not fail strict gate).

Notable: complianceStrictIgnoresNotApplicableAcs() — the strict gate must distinguish uncovered from not-applicable. A toggled-off AC is not a gap.

Satisfies: REQ-ORTHOGONAL-TOGGLING (chapter 05), REQ-DOG-FOOD (chapter 04), REQ-PARALLEL-DELIVERABLE (chapter 05).

FEATURE-TRACE-CORE — gaps, matrix, chain, impact, hotspots, fragile

@Satisfies(
  ReqDiscoverableTraceabilityRequirement,
)
export abstract class TraceCoreFeature extends Feature {
  readonly id = 'TRACE-CORE';
  readonly title = 'Trace queries — gaps, matrix, chain, impact, hotspots, fragile';
  readonly priority = Priority.Critical;
}

AC count: seventy. Priority: Critical. Enabled: true.

The query core powering requirements trace <query>. Seventy ACs across eighteen functions: buildTraceIndex (ten), normalizePath (two), queryFileToFeatures (three), queryFeatureToFiles (four), queryFileToTests (two), queryFeatureToTests (three), queryImpact (four), queryHotspots (two), queryFragile (three), queryFsm (four), queryGaps (five), queryMatrix (five), queryChain (five), render functions (eighteen covering each query's rendering branch).

Every trace subcommand — gaps, matrix <feature>, chain <id> <ac>, impact <files...>, hotspots, fragile, fsm — is one cluster of ACs in this Feature.

Notable: buildsChainWithRequirementFsmAndTests() — the chain query walks Requirement → Feature → AC → Test, the full four-tier, for a single AC. This is the AC that pins the tracer's completeness across the whole stack.

Satisfies: REQ-DISCOVERABLE-TRACEABILITY (chapter 04).

FEATURE-VERSIONING — monotonic version + content-hash + pin resolution

@Satisfies(
  ReqVersionedTraceabilityRequirement,
  ReqDogFoodRequirement,
  ReqParallelDeliverableRequirement,
)
export abstract class VersioningFeature extends Feature {
  readonly id = 'VERSIONING';
  readonly title = 'Versioning — monotonic version + content-hash + pin resolution on every spec node';
  readonly priority = Priority.High;
  readonly enabled = false;
}

AC count: fifteen. Priority: High. Enabled: false (Tier-2 roadmap).

Per-spec-node versioning with content-hash and pin resolution. Fifteen ACs: version computation (six), pinning surface on @Satisfies and @Verifies (three), error paths (four: drift, unpinned-warn-not-fail, pin-mismatch, history-entry-missing), integration (two: history-logs-bump, FileSystem-port-write), end-to-end pinned-Feature-survives-Requirement-edit.

Notable: contentHashExcludesHistoryAndSchemaVersion() — the hash is over spec content, not audit metadata. Otherwise every history entry would bump the version recursively.

Satisfies: REQ-VERSIONED-TRACEABILITY (chapter 05), REQ-DOG-FOOD (chapter 04), REQ-PARALLEL-DELIVERABLE (chapter 05).

FEATURE-SCENARIO-AI-ADAPTER — AiAdapter port + Stub + ClaudeApi

@Satisfies(
  ReqAiAsImplementerAdapterRequirement,
  ReqScenarioDrivenWorkflowRequirement,
  ReqParallelDeliverableRequirement,
  ReqDogFoodRequirement,
)
export abstract class ScenarioAiAdapterFeature extends Feature {
  readonly id = 'SCENARIO-AI-ADAPTER';
  readonly title = 'AiAdapter port + Stub + ClaudeApi implementations with prompt caching';
  readonly priority = Priority.Medium;
  readonly enabled = false;
}

AC count: ten. Priority: Medium. Enabled: false (Tier-2 roadmap).

The AI implementer port plus two adapters. Ten ACs: port shape (three), stub adapter (three — deterministic throw-stub, no network, selected-when-ai-flag-absent), Claude adapter (four — isolates Anthropic import, prompt caching by default, env API key, retries, cache-hit/miss telemetry).

Notable: claudeAdapterIsolatesAnthropicImport() — the anthropic package must be imported behind a dynamic barrier so test runs with --no-ai never pay the dependency cost.

Satisfies: REQ-AI-AS-IMPLEMENTER-ADAPTER (chapter 08), REQ-SCENARIO-DRIVEN-WORKFLOW (chapter 08), REQ-PARALLEL-DELIVERABLE (chapter 05), REQ-DOG-FOOD (chapter 04).

FEATURE-SCENARIO-EXPORT — post-run Markdown / PDF capture

@Satisfies(
  ReqScenarioDrivenWorkflowRequirement,
  ReqParallelDeliverableRequirement,
  ReqDogFoodRequirement,
)
export abstract class ScenarioExportCommandFeature extends Feature {
  readonly id = 'SCENARIO-EXPORT';
  readonly title = '`requirements scenario export` — post-run Markdown / PDF capture';
  readonly priority = Priority.Low;
  readonly enabled = false;
}

AC count: six. Priority: Low. Enabled: false (Tier-2 roadmap).

Markdown/PDF export of a scenario run. Six ACs: markdown artifact, PDF artifact, narration blocks, compliance report, FSM transition mermaid, overwrite refusal without --force.

Notable: exportIncludesFsmTransitionMermaid() — the export is the demo artifact; the FSM trace is what makes it readable.

Satisfies: REQ-SCENARIO-DRIVEN-WORKFLOW (chapter 08), REQ-PARALLEL-DELIVERABLE (chapter 05), REQ-DOG-FOOD (chapter 04).

FEATURE-SCENARIO-INSPECT — dry-run FSM trace

@Satisfies(
  ReqScenarioDrivenWorkflowRequirement,
  ReqMultiFsmOrchestrationRequirement,
  ReqParallelDeliverableRequirement,
  ReqDogFoodRequirement,
)
export abstract class ScenarioInspectCommandFeature extends Feature {
  readonly id = 'SCENARIO-INSPECT';
  readonly title = '`requirements scenario inspect <file>` — dry-run FSM trace';
  readonly priority = Priority.Medium;
  readonly enabled = false;
}

AC count: seven. Priority: Medium. Enabled: false (Tier-2 roadmap).

Dry-run the FSM transitions a scenario would walk, without side effect. Seven ACs: project-lifecycle transitions, per-feature transitions, per-AC transitions, annotation with event-and-guard, no-file-write, mermaid-output-flag, expected-artifact-paths.

Notable: inspectPerformsNoFileWrite() — the invariant. The command is side-effect free.

Satisfies: REQ-SCENARIO-DRIVEN-WORKFLOW (chapter 08), REQ-MULTI-FSM-ORCHESTRATION (chapter 08), REQ-PARALLEL-DELIVERABLE (chapter 05), REQ-DOG-FOOD (chapter 04).

FEATURE-SCENARIO-LIST — enumerate available scenarii

@Satisfies(
  ReqScenarioDrivenWorkflowRequirement,
  ReqParallelDeliverableRequirement,
  ReqDogFoodRequirement,
)
export abstract class ScenarioListCommandFeature extends Feature {
  readonly id = 'SCENARIO-LIST';
  readonly title = '`requirements scenario list` — enumerate available scenarii';
  readonly priority = Priority.Low;
  readonly enabled = false;
}

AC count: six. Priority: Low. Enabled: false (Tier-2 roadmap).

Scenario registry enumeration. Six ACs: built-in scenarii, project-defined scenarii, id-title-style triple, JSON output flag, alphabetical order by id, empty-registry helpful hint.

Notable: listIncludesProjectDefinedScenarii() — the registry is open: a project adds a scenario and list picks it up without recompilation of the bin.

Satisfies: REQ-SCENARIO-DRIVEN-WORKFLOW (chapter 08), REQ-PARALLEL-DELIVERABLE (chapter 05), REQ-DOG-FOOD (chapter 04).

FEATURE-SCENARIO-ORCHESTRATOR — 3 coordinated FSMs + event bus + replay log

@Satisfies(
  ReqMultiFsmOrchestrationRequirement,
  ReqScenarioDrivenWorkflowRequirement,
  ReqAiAsImplementerAdapterRequirement,
  ReqParallelDeliverableRequirement,
  ReqDogFoodRequirement,
)
export abstract class ScenarioOrchestratorFeature extends Feature {
  readonly id = 'SCENARIO-ORCHESTRATOR';
  readonly title = 'Scenario orchestrator — 3 coordinated FSMs + event bus + replay log';
  readonly priority = Priority.High;
  readonly enabled = false;
}

AC count: nineteen. Priority: High. Enabled: false (Tier-2 roadmap).

The orchestrator that coordinates three FSMs (project / per-feature / per-AC) via an event bus. Nineteen ACs: ProjectLifecycleFsm (ten — eight states plus Failed plus every-transition-tested), PerFeatureFsm (three), PerAcFsm (three), event bus + replay log (three), determinism (one).

Notable: orchestratorReplaysFromLogProducesIdenticalFinalStates() — the replay property: starting from Empty and applying the logged event sequence yields the same final state as the original run.

Satisfies: REQ-MULTI-FSM-ORCHESTRATION (chapter 08), REQ-SCENARIO-DRIVEN-WORKFLOW (chapter 08), REQ-AI-AS-IMPLEMENTER-ADAPTER (chapter 08), REQ-PARALLEL-DELIVERABLE (chapter 05), REQ-DOG-FOOD (chapter 04).

FEATURE-SCENARIO-PLAY — non-interactive project generation

@Satisfies(
  ReqScenarioDrivenWorkflowRequirement,
  ReqMultiFsmOrchestrationRequirement,
  ReqAiAsImplementerAdapterRequirement,
  ReqParallelDeliverableRequirement,
  ReqDogFoodRequirement,
)
export abstract class ScenarioPlayCommandFeature extends Feature {
  readonly id = 'SCENARIO-PLAY';
  readonly title = '`requirements scenario play <file>` — non-interactive project generation';
  readonly priority = Priority.High;
  readonly enabled = false;
}

AC count: fifteen. Priority: High. Enabled: false (Tier-2 roadmap).

The scenario playback bin. Fifteen ACs: loading + validation (four), orchestration (two: dispatch-to-orchestrator, produces-four-tier-project), narration (three), flags (four: --ai, --no-ai deterministic stubs, --seed, --dry-run), closure (two: compliance --strict at end, expected-artifacts-exist).

Notable: scenarioPlayRunsComplianceStrictAtEnd() — the self-check. Every scenario run ends by running compliance --strict on the project it just generated. A scenario that does not produce a gate-passing project is a failed scenario.

Satisfies: REQ-SCENARIO-DRIVEN-WORKFLOW (chapter 08), REQ-MULTI-FSM-ORCHESTRATION (chapter 08), REQ-AI-AS-IMPLEMENTER-ADAPTER (chapter 08), REQ-PARALLEL-DELIVERABLE (chapter 05), REQ-DOG-FOOD (chapter 04).

FEATURE-SCENARIO-RECORD — capture a session into a scenario file

@Satisfies(
  ReqScenarioDrivenWorkflowRequirement,
  ReqParallelDeliverableRequirement,
  ReqDogFoodRequirement,
)
export abstract class ScenarioRecordCommandFeature extends Feature {
  readonly id = 'SCENARIO-RECORD';
  readonly title = '`requirements scenario record` — capture a session into a scenario file';
  readonly priority = Priority.Medium;
  readonly enabled = false;
}

AC count: nine. Priority: Medium. Enabled: false (Tier-2 roadmap).

Record an interactive wizard session (or an existing project) into a scenario JSON for later replay. Nine ACs: captures-interactive-session, captures-from-existing-project, schema-versioned-JSON, includes-satisfies-forward-refs, includes-expects-per-ac, replay-fidelity-produces-identical-artifacts, refuses-overwrite-without-force, output-passes-validate-command, supports-partial-seeding-from-features-only.

Notable: recordReplayFidelityProducesIdenticalArtifacts() — the round-trip property for the scenario format: record → play → record → play must yield byte-identical outputs.

Satisfies: REQ-SCENARIO-DRIVEN-WORKFLOW (chapter 08), REQ-PARALLEL-DELIVERABLE (chapter 05), REQ-DOG-FOOD (chapter 04).

FEATURE-SCENARIO-VALIDATE — schema + cross-reference check

@Satisfies(
  ReqScenarioDrivenWorkflowRequirement,
  ReqParallelDeliverableRequirement,
  ReqDogFoodRequirement,
)
export abstract class ScenarioValidateCommandFeature extends Feature {
  readonly id = 'SCENARIO-VALIDATE';
  readonly title = '`requirements scenario validate <file>` — schema + cross-reference check';
  readonly priority = Priority.High;
  readonly enabled = false;
}

AC count: eight. Priority: High. Enabled: false (Tier-2 roadmap).

Validate a scenario file without side effect. Eight ACs: accepts-well-formed, rejects-missing-fields, reports-ajv-errors-in-friendly-format, cross-checks-satisfies-forward-refs, cross-checks-satisfiedBy-forward-refs, rejects-duplicate-ids, performs-no-file-write, exits-non-zero-on-failure.

Notable: validateCrossChecksSatisfiesForwardReferences() — the scenario format allows forward references (a Feature can @Satisfies a Requirement defined later in the file); the validator checks every one resolves.

Satisfies: REQ-SCENARIO-DRIVEN-WORKFLOW (chapter 08), REQ-PARALLEL-DELIVERABLE (chapter 05), REQ-DOG-FOOD (chapter 04).

Running-example deep-dive — TRACE-EXPLORER-TUI

With the twenty-five enumerated, the first deep-dive returns to the running example.

FEATURE-TRACE-EXPLORER-TUI has ten abstract ACs, three @Satisfies edges, and the enabled = false flag. The ten ACs, in class order, and the obligation each one ultimately traces back to via the @Satisfies chain:

traceExplorerBuildsGraph() — the explorer, when started, reads the traceability index and constructs an in-memory graph with Requirement, Feature, AC, and Test nodes. Traces to REQ-DISCOVERABLE-TRACEABILITY — if the graph cannot be built, nothing can be discovered.
traceExplorerHandlesArrowKeyNavigation() — arrow keys move a cursor across graph nodes. Traces to REQ-DISCOVERABLE-TRACEABILITY — discovery is mechanical, not lexical; a user who does not know the vocabulary can still browse.
traceExplorerDrillsDownFromAnyNode() — pressing Enter on any node expands its neighbours in the adjacent tier. Traces to REQ-DISCOVERABLE-TRACEABILITY — the four-tier chain is walkable from any entry point.
traceExplorerOpensHelpOverlayOnQuestionMark() — pressing ? overlays a help panel. Traces to REQ-DISCOVERABLE-TRACEABILITY — the TUI self-documents.
traceExplorerJumpsBackUpWithBackspace() — backspace returns to the previous node. Traces to REQ-DISCOVERABLE-TRACEABILITY — navigation is reversible, no dead ends.
traceExplorerRefusesToStartOnNonTty() — when stdout is not a TTY, the command fails fast with a clear message. Traces indirectly to REQ-DOG-FOOD — the refusal itself must be tested without describe/it, and to REQ-DISCOVERABLE-TRACEABILITY — a TUI that prints garbage into a pipe is not discoverable.
traceExplorerExitsCleanlyOnCtrlC() — Ctrl+C tears down the terminal state and returns cleanly. Traces to REQ-DISCOVERABLE-TRACEABILITY — the TUI never leaves the terminal in a broken state.
traceExplorerUsesFileSystemPortForDiscovery() — the explorer reads through the FileSystem port, never through node:fs directly. Traces to REQ-PARALLEL-DELIVERABLE — the port discipline is what lets the Feature ship independently of the other streams, because its tests inject an in-memory port.
traceExplorerUsesPromptPortForInteraction() — the explorer reads input through the Prompt port, never through node:readline. Traces to REQ-PARALLEL-DELIVERABLE — same reasoning as the previous AC.
endToEndNavigatesReqToFeatToAcToTest() — the end-to-end AC: start the explorer on a known fixture, arrow-key across REQ → FEAT → AC → TEST, and assert the final node is the expected test file. Traces to all three Requirements simultaneously: it is the reachability proof (REQ-DISCOVERABLE-TRACEABILITY), it uses the port injection pattern (REQ-PARALLEL-DELIVERABLE), and it is itself written with @FeatureTest + @Verifies (REQ-DOG-FOOD).

The lesson the ten ACs carry, collectively, is that the bipartite edge is not a label but a constraint generator. Three @Satisfies entries produce ten ACs whose purposes, taken together, form the minimal set of test obligations for a Feature that honours those three Requirements. Remove REQ-PARALLEL-DELIVERABLE and the two port-integration ACs (#8, #9) lose their justification. Remove REQ-DOG-FOOD and the constraints on how the tests themselves must be written evaporate. Remove REQ-DISCOVERABLE-TRACEABILITY and the Feature has no reason to exist at all.

The enabled = false flag is worth a second pass. It means compliance --strict ignores this Feature when checking for uncovered critical ACs — the ten methods above are declarations of intent, not active debts. When the TUI stream enters active work, the flag flips to true, the ten ACs become gate-relevant, and the scaffolder produces ten test stubs ready for fill-in. The flag is the switch between declared-and-planned and declared-and-verified. Both states are first-class; they share the same class syntax.

Running-example deep-dive — NEW-COMMAND

The showcase Feature — FEATURE-NEW-COMMAND — has twenty-two ACs and seven @Satisfies edges. This is the maximally-connected node of the bipartite graph, the single Feature whose removal would leave the largest number of orphaned obligations. A walk through its ACs clarifies why.

The @Satisfies chain declares seven Requirements:

REQ-BOOTSTRAP-ZERO-FRICTION (primary) — "it must be possible to declare a new Feature in under sixty seconds"
REQ-SPEC-IS-SOURCE-OF-TRUTH (joint) — "preview before every write; no silent regeneration"
REQ-EDITOR-FIRST-CLASS (joint) — "generated specs carry $schema for VS Code binding"
REQ-TUI-MODERN (joint) — "the wizard uses the Prompt port, never readline"
REQ-DSL-COMPLETE (joint) — "the wizard asks which Requirement(s) the Feature satisfies"
REQ-PARALLEL-DELIVERABLE (joint) — "owned by Stream A with cross-border contributions from B/C/E/F"
REQ-DOG-FOOD (joint) — "the tests for this Feature use @FeatureTest/@Verifies, never describe/it"

Each of the twenty-two ACs traces to one or more of those seven. The clusters:

Wizard flow (five ACs, primary to BOOTSTRAP-ZERO-FRICTION): wizardCollectsIdTitlePriority (the minimum viable four prompts), wizardLoopsAcsUntilEnd (add-AC prompt loops until the user says "end"), wizardValidatesIdFormat (the ID regex is enforced by a smart constructor, feeding back into SMART-CONSTRUCTORS coverage), wizardValidatesAcNameFormat (camelCase enforcement), wizardRefusesEmptyExpects (an AC must declare at least one TestLevel).

Replay (three ACs, joint SPEC-IS-SOURCE-OF-TRUTH + DOG-FOOD): replaySeedsDefaultsFromSpec (the wizard pre-fills from an existing .spec.json), replayOffersKeepEditDeletePerAc (per-AC three-way prompt), yesFlagSkipsAllPromptsAndApplies (non-interactive mode).

Source generation (three ACs, joint SPEC-IS-SOURCE-OF-TRUTH + DSL-COMPLETE): generateFeatureSourceMatchesSpec (the emitted .ts round-trips back to the same .spec.json), generatedFileGoesToFeaturesDir (path discipline), specJsonSavedNextToFeature (the .spec.json lives beside the .ts).

Test scaffolding (three ACs, joint SPEC-IS-SOURCE-OF-TRUTH + PARALLEL-DELIVERABLE): scaffoldsUnitTestsForUncoveredAcs (routes through SCAFFOLD-CORE), scaffoldsE2eOnlyWhenAcExpectsEndToEnd (the TestLevel routing), noTestFlagSkipsScaffolding (opt-out).

Preview / dry-run (three ACs, primary to SPEC-IS-SOURCE-OF-TRUTH): previewShowsDiffBeforeAnyWrite (nothing is written without a diff), previewOffersApplyReviewCancel (three-way final prompt), dryRunFlagForcesPreviewCancel (--dry-run is preview-only).

Post-apply editor (one AC, joint EDITOR-FIRST-CLASS): endOfWizardOffersOpenInEditor — the wizard offers to open the generated .ts and .spec.json in the user's $EDITOR.

Safety (one AC, joint SPEC-IS-SOURCE-OF-TRUTH): refusesOverwriteUntrackedFile — the wizard refuses to overwrite a file not tracked by git, preventing data loss on an unexpected path collision.

Cross-link (one AC, primary to DSL-COMPLETE): wizardOffersRequirementSelection — the multiselect over existing Requirement classes that makes the @Satisfies edge selectable from the wizard itself. This is what makes the DSL reflexive: a user can bootstrap a Feature and connect it to the Requirements it satisfies, without leaving the TUI.

Schema validation (one AC, joint EDITOR-FIRST-CLASS): replayValidatesSpecAgainstSchema — on replay, the loaded .spec.json is validated against the generated JSON Schema before any further prompt is shown.

Templates (one AC, primary to BOOTSTRAP-ZERO-FRICTION): templateFlagPreFillsSpec — --template web-crud or --template cli-smoke pre-fills the wizard with a canonical skeleton.

Coverage delta (one AC, joint SPEC-IS-SOURCE-OF-TRUTH): previewIncludesCoverageDelta — the preview shows how compliance --strict will change after the apply: new uncovered ACs, new covered ACs, net delta.

End-to-end (one AC, touches all seven): walksFullWizardEndToEnd — the single end-to-end test that drives the wizard through every code path above, asserting the final state of .ts / .spec.json / test stubs / VS Code settings, all in one fixture.

The structural point is that twenty-two ACs are not twenty-two independent constraints. They are the closure of seven Requirements under the rule any AC that demonstrably serves more than zero of the satisfied Requirements is a legitimate member of the Feature. Several ACs serve four or five Requirements at once (the end-to-end is the extreme case, serving all seven). The Feature is not a big bag of tests; it is the smallest set of ACs whose union demonstrates that the seven Requirements are jointly met.

This is what "showcase" means in the bipartite. Not "biggest" in some aggregate sense, but the node with the most edges. And because @Satisfies is bidirectional, each of those seven Requirements lists FEATURE-NEW-COMMAND in its own satisfiers set. REQ-BOOTSTRAP-ZERO-FRICTION is currently satisfied by exactly one Feature: this one. REQ-TUI-MODERN is satisfied by FEATURE-NEW-COMMAND plus FEATURE-CLACK-ADAPTER plus FEATURE-SYNC-COMMAND plus FEATURE-REQUIREMENT-COMMANDS. The density propagates.

Diagram 1 — Feature → Requirement bipartite

Alt text: Bipartite flowchart with twenty-five Features on the left and twenty-two Requirements on the right, every @Satisfies edge drawn. REQ-DSL-COMPLETE and REQ-DOG-FOOD are highlighted as super-connectors; FEATURE-NEW-COMMAND and FEATURE-REQUIREMENT-COMMANDS are highlighted as the showcase nodes with seven and six outgoing edges respectively.

Caption: The full @Satisfies bipartite of the @frenchexdev/requirements package. Two super-connector Requirements (DOG-FOOD, satisfied by almost every Feature; DSL-COMPLETE, satisfied by everything that touches core vocabulary) anchor the right side. Two showcase Features (NEW-COMMAND with seven edges, REQUIREMENT-COMMANDS with six) anchor the left. Between them, a characteristic hub-and-spoke shape: most Features connect to two or three Requirements, a handful to five or more. FEATURE-REQUIREMENTS-SMOKE has zero edges — the pre-Requirement grandfathered Feature discussed in the enumeration.

Diagram 2 — AC-density heatmap

Alt text: Bar chart with twenty-eight columns showing AC count per Feature, ordered ascending from SMOKE at three ACs to COMPLIANCE-REPORT at one hundred and one ACs. The distribution is long-tailed: most Features sit between five and twenty ACs, with four outliers above forty (COMPLIANCE-CORE, TEST-BINDINGS-SCANNER, TRACE-CORE, COMPLIANCE-REPORT).

Caption: AC-density distribution across the twenty-five Features (plus the eight scenario sub-Features, shown separately). The long-tail shape is what compliance --strict reads as the verification load profile: four Features carry more than half the AC mass, and they are all Critical priority. The median Feature has ten to fifteen ACs; the showcase Feature NEW-COMMAND has twenty-two. The minimum is three (BASE-TYPES, where the ACs are the three enum / class existence assertions). The chart makes it visible which test files chapter 07 will treat in greatest depth.

The shape of the whole

With the enumeration and the two diagrams in hand, the shape of the bipartite emerges.

Two super-connector Requirements. REQ-DOG-FOOD is satisfied by twenty-two of the twenty-five Features. The three exceptions are the pre-Requirement grandfathered SmokeFeature, plus the two core-analysis Features (COMPLIANCE-CORE, COMPLIANCE-REPORT) which satisfy REQ-DISCOVERABLE-TRACEABILITY and REQ-VISUAL-TRACEABILITY instead — but in practice are dog-fooded anyway, just through a different edge. REQ-DSL-COMPLETE is satisfied by every Feature that touches the core vocabulary: BASE-TYPES, DECORATORS, SMART-CONSTRUCTORS, FEATURE-NEW-COMMAND, REQUIREMENT-COMMANDS. Two Requirements, most of the edges. This is what it looks like when a non-functional invariant has been absorbed into the architecture.

A handful of focal Requirements. REQ-BOOTSTRAP-ZERO-FRICTION has exactly one satisfier (FEATURE-NEW-COMMAND). REQ-PROPERTY-INVARIANTS has exactly one satisfier (PROPERTY-TESTING). REQ-REFACTOR-SAFE has two (BASE-TYPES declares the invariants; FEATURE-RENAME-CODEMOD enforces them). These are the focal Requirements: one deliverable owns each.

One showcase Feature. FEATURE-NEW-COMMAND at seven edges, FEATURE-REQUIREMENT-COMMANDS at six. These are the two nodes whose removal would disconnect the most Requirements.

One pre-Requirement grandfather. SmokeFeature — the CLI bin smoke tests — satisfies zero Requirements. It is the deliberate outlier, preserved as a reminder that the Requirement stratum was added to a pre-existing Feature stratum and not all legacy edges have been retrofitted. Chapter 08 discusses whether it should be.

The universal parallel-deliverable edge. Every roadmap Feature (the eight with enabled = false) carries a REQ-PARALLEL-DELIVERABLE edge. This is not coincidence: the parallel-deliverable Requirement is the one that justifies Tier-2 roadmap Features being declared at all. Without it, declarations with no bound tests would be orphans; with it, they are planned parallel streams waiting for their gate.

The scenario cluster. The eight scenario sub-Features form a tight sub-bipartite of their own, anchored by REQ-SCENARIO-DRIVEN-WORKFLOW, REQ-MULTI-FSM-ORCHESTRATION, and REQ-AI-AS-IMPLEMENTER-ADAPTER. They are post-dated Requirements — added after chapters 04–05 were written, documented in chapter 08. The cluster demonstrates the Requirement stratum absorbing a new concern without breaking the existing bipartite: the eight new Features plug into three new Requirements, and REQ-DOG-FOOD plus REQ-PARALLEL-DELIVERABLE are re-used unchanged.

The shape is what chapter 12 will render as the global traceability graph, with tests added as a third tier. The shape is what chapter 13 will gate on. The shape is also what makes the dog-food claim concrete: if this graph is wrong, compliance --strict is the command that fails. Every @Satisfies edge in the diagrams above is a registry entry that the scanner reads, cross-checks against test bindings, and reports on. The bipartite is not a picture; it is a data structure, printed.

Running-example recap

The running example, one more time. FEATURE-TRACE-EXPLORER-TUI sits at three edges and ten ACs. It is small enough to quote in full, non-trivial enough to exhibit every structural point this chapter raises: the @Satisfies chain is typed, the abstract ACs accumulate the verification load, the enabled = false flag parks the Feature in the roadmap without disqualifying it from the bipartite. Chapter 07 will count the @FeatureTest / @Verifies bindings — once it is built, this Feature will contribute ten of them.

Chapter 04 — Twenty-Two Requirements, Part One: the REQ-side view of the bipartite, first half.
Chapter 05 — Twenty-Two Requirements, Part Two: the REQ-side view, second half.
Chapter 07 — Fifty-Four Tests, Only Decorators: the test-file side, enumerating every @FeatureTest / @Verifies binding.
Chapter 12 — Traceability Graphs, Rendered: the global four-tier DAG, with tests added.
Chapter 13 — Compliance, Strictly: the --strict gate and the shape it reads.

Previous: Chapter 05 — Twenty-Two Requirements, Part Two Next: Chapter 07 — Fifty-Four Tests, Only Decorators

`[` or `Alt+S`	Focus sidebar navigation
`]` or `Alt+C`	Focus main content
`↑` `↓`	Navigate between sidebar items
`Enter`	Open page / toggle section
`Space`	Toggle section expand/collapse
`Escape`	Close overlay / sidebar

`Ctrl+K`	Open search
`?`	Show this help

`Ctrl+=` or `Ctrl+↑`	Increase font size
`Ctrl+−` or `Ctrl+↓`	Decrease font size
`f`	Open console font selector

`Ctrl+⇧+=` or `Ctrl+⇧+↑`	Browser zoom in
`Ctrl+⇧+−` or `Ctrl+⇧+↓`	Browser zoom out
`Ctrl+⇧+0`	Reset browser zoom

`Tab`	Focus a diagram or image
`Enter`	Open full size overlay
`+` `−`	Zoom in / out (in overlay)
`Escape`	Close overlay, return focus

Chapter 06 — Twenty-Five Features Mapped📋

How to read a Feature entry📋

The twenty-five Features, enumerated📋

FEATURE-AUDIT-TRAIL-HOOKS — extended ChangeKind, optional signature, no-op decorators📋

FEATURE-BASE-TYPES — Priority, TestLevel, Feature abstract class📋

FEATURE-CLACK-ADAPTER — RealPrompt + openInEditor, no readline, no raw process📋

FEATURE-COMPLIANCE-CORE — feature parsing, coverage loading, runtime rollup, orphans📋

FEATURE-COMPLIANCE-REPORT — table, ANSI, cross-reference, console rendering📋

FEATURE-DECORATORS — @FeatureTest, @Verifies, @Expects, @Exclude📋

FEATURE-BIDIRECTIONAL-SYNC — either .ts class or .spec.json is authoritative📋

FEATURE-HEURISTIC-SUGGESTER — n-gram + verb patterns from repo corpus, zero LLM📋

FEATURE-MERMAID-GRAPH — full REQ→FEAT→AC→TEST DAG📋

FEATURE-NEW-COMMAND — interactive Feature bootstrap wizard📋

FEATURE-RENAME-CODEMOD — ts-morph-driven feature / requirement / ac rename📋

FEATURE-SCHEMA-COMMAND — JSON Schema generation + VS Code binding📋

FEATURE-SYNC-COMMAND — reconcile spec.json with on-disk files📋

FEATURE-TRACE-EXPLORER-TUI — interactive TTY browser over the traceability graph📋

FEATURE-WATCH-MODE — live revalidation on file change📋

FEATURE-PROPERTY-TESTING — fast-check on every pure function📋

FEATURE-REQUIREMENT-COMMANDS — Requirement new / sync / list / show / orphan📋

FEATURE-SCAFFOLD-CORE — generate test stubs for uncovered ACs📋

FEATURE-SCAFFOLDER-REGISTRY — pluggable TestScaffolder, one per TestLevel📋

FEATURE-SMART-CONSTRUCTORS — branded primitives, parse-don't-validate📋

FEATURE-REQUIREMENTS-SMOKE — CLI bin smoke tests📋

FEATURE-TEST-BINDINGS-SCANNER — AST walker over @FeatureTest/@Verifies test files📋

FEATURE-ORTHOGONAL-TOGGLING — ToggleProvider port + @Toggle decorator + ReleaseStage📋

FEATURE-TRACE-CORE — gaps, matrix, chain, impact, hotspots, fragile📋

FEATURE-VERSIONING — monotonic version + content-hash + pin resolution📋

FEATURE-SCENARIO-AI-ADAPTER — AiAdapter port + Stub + ClaudeApi📋

FEATURE-SCENARIO-EXPORT — post-run Markdown / PDF capture📋

FEATURE-SCENARIO-INSPECT — dry-run FSM trace📋

FEATURE-SCENARIO-LIST — enumerate available scenarii📋

FEATURE-SCENARIO-ORCHESTRATOR — 3 coordinated FSMs + event bus + replay log📋

FEATURE-SCENARIO-PLAY — non-interactive project generation📋

FEATURE-SCENARIO-RECORD — capture a session into a scenario file📋

FEATURE-SCENARIO-VALIDATE — schema + cross-reference check📋

Running-example deep-dive — TRACE-EXPLORER-TUI📋

Running-example deep-dive — NEW-COMMAND📋

Diagram 1 — Feature → Requirement bipartite📋

Diagram 2 — AC-density heatmap📋

The shape of the whole📋

Running-example recap📋

Related reading📋

Chapter 06 — Twenty-Five Features Mapped

How to read a Feature entry

The twenty-five Features, enumerated

FEATURE-AUDIT-TRAIL-HOOKS — extended ChangeKind, optional signature, no-op decorators

FEATURE-BASE-TYPES — Priority, TestLevel, Feature abstract class

FEATURE-CLACK-ADAPTER — RealPrompt + openInEditor, no readline, no raw process

FEATURE-COMPLIANCE-CORE — feature parsing, coverage loading, runtime rollup, orphans

FEATURE-COMPLIANCE-REPORT — table, ANSI, cross-reference, console rendering

FEATURE-DECORATORS — @FeatureTest, @Verifies, @Expects, @Exclude

FEATURE-BIDIRECTIONAL-SYNC — either .ts class or .spec.json is authoritative

FEATURE-HEURISTIC-SUGGESTER — n-gram + verb patterns from repo corpus, zero LLM

FEATURE-MERMAID-GRAPH — full REQ→FEAT→AC→TEST DAG

FEATURE-NEW-COMMAND — interactive Feature bootstrap wizard

FEATURE-RENAME-CODEMOD — ts-morph-driven feature / requirement / ac rename

FEATURE-SCHEMA-COMMAND — JSON Schema generation + VS Code binding

FEATURE-SYNC-COMMAND — reconcile spec.json with on-disk files

FEATURE-TRACE-EXPLORER-TUI — interactive TTY browser over the traceability graph

FEATURE-WATCH-MODE — live revalidation on file change

FEATURE-PROPERTY-TESTING — fast-check on every pure function

FEATURE-REQUIREMENT-COMMANDS — Requirement new / sync / list / show / orphan

FEATURE-SCAFFOLD-CORE — generate test stubs for uncovered ACs

FEATURE-SCAFFOLDER-REGISTRY — pluggable TestScaffolder, one per TestLevel

FEATURE-SMART-CONSTRUCTORS — branded primitives, parse-don't-validate

FEATURE-REQUIREMENTS-SMOKE — CLI bin smoke tests

FEATURE-TEST-BINDINGS-SCANNER — AST walker over @FeatureTest/@Verifies test files

FEATURE-ORTHOGONAL-TOGGLING — ToggleProvider port + @Toggle decorator + ReleaseStage

FEATURE-TRACE-CORE — gaps, matrix, chain, impact, hotspots, fragile

FEATURE-VERSIONING — monotonic version + content-hash + pin resolution

FEATURE-SCENARIO-AI-ADAPTER — AiAdapter port + Stub + ClaudeApi

FEATURE-SCENARIO-EXPORT — post-run Markdown / PDF capture

FEATURE-SCENARIO-INSPECT — dry-run FSM trace

FEATURE-SCENARIO-LIST — enumerate available scenarii

FEATURE-SCENARIO-ORCHESTRATOR — 3 coordinated FSMs + event bus + replay log

FEATURE-SCENARIO-PLAY — non-interactive project generation

FEATURE-SCENARIO-RECORD — capture a session into a scenario file

FEATURE-SCENARIO-VALIDATE — schema + cross-reference check

Running-example deep-dive — TRACE-EXPLORER-TUI

Running-example deep-dive — NEW-COMMAND

Diagram 1 — Feature → Requirement bipartite

Diagram 2 — AC-density heatmap

The shape of the whole

Running-example recap

Related reading