The hardest objection to typed specs is not technical. It is human. "My PM can't read TypeScript abstract classes." Fair. But your PM can't read Cucumber step definitions either — they just think they can because the syntax looks like English. We solve the real problem: render the specs as actual English.

The Readability Objection📋

BDD's original promise was that business stakeholders would read and write Gherkin scenarios. In practice, PMs read them occasionally and write them never. The "Given/When/Then" syntax is close enough to English to feel approachable, but far enough from it to require training. And the step definitions behind those scenarios? Pure code, invisible to the PM.

Typed specs face the same objection but more honestly. An abstract class is obviously code. A PM looks at it and says "I can't read that." Good. At least no one pretends otherwise.

The solution is not to make code look like English. The solution is to generate English from code.

Before: Opaque to PMs📋

After: Dashboard Renders Natural Language📋

1. Natural-Language Rendering📋

Every acceptance criterion in tspec is an abstract method with a JSDoc comment. The scanner extracts the JSDoc. The dashboard renders it as a human-readable bullet point.

Source code:

/** Clicking a TOC entry loads the corresponding page. */
abstract tocClickLoadsPage(): ACResult;

Dashboard renders:

• Covered: "Clicking a TOC entry loads the corresponding page." (green checkmark)
• Uncovered: "Clicking a TOC entry loads the corresponding page." (red cross)

The abstract class is the source of truth — it compiles, it gets scanned, it participates in coverage analysis. The dashboard is the readable view. The PM never needs to open a code editor. They open the Diem dashboard, navigate to the feature, and see a list of plain-English statements with green or red indicators.

This is not a lossy translation. The JSDoc is written by the developer specifically to be PM-readable. The method name (tocClickLoadsPage) is for the compiler. The JSDoc is for humans. Both live on the same artifact, so they cannot drift apart.

If a developer writes a method without JSDoc, the dashboard shows the method name converted to a readable form (camelCase to sentence case). That looks ugly enough to motivate adding proper descriptions.

2. Approval Workflow📋

The Workflow DSL defines lifecycle states. Two of those states — Proposed and Approved — exist specifically for stakeholder interaction.

A developer writes a feature spec and moves it to Proposed. The PM opens the dashboard, reads the natural-language ACs, and either approves the feature (moving it to Approved) or leaves a comment asking for changes. The developer revises, the PM reviews again. No code reading required at any point.

The approval is recorded in the workflow history: who approved, when, which version of the ACs they saw. For regulated industries, this audit trail matters. ISO 13485 (medical devices) and IEC 62304 require documented evidence that requirements were reviewed and approved by authorized personnel. The dashboard provides that evidence automatically.

The PM's approval is on the rendered English, but it maps to specific abstract methods in a specific commit. The traceability is exact.

3. Comment Threads📋

Diem supports per-entity comment threads. In the Feature Detail view, comments attach to the feature itself or to individual acceptance criteria.

A PM reads an AC that says "Search results are paginated with 20 items per page" and comments: "Should this be configurable? Our enterprise customers want 50." The developer sees the comment on the specific AC, replies, and if needed, adds a new AC: abstract searchPaginationIsConfigurable(): ACResult; with JSDoc "The number of search results per page is configurable by the user."

The conversation is stored in Diem, not in code. Code stays clean — abstract methods and JSDoc only. Discussion, context, and decision history live in the dashboard where PMs are comfortable.

This closes a gap that BDD never solved. Gherkin scenarios live in files. Discussion about those scenarios lives in Jira tickets, Slack threads, email chains — disconnected from the specs themselves. In tspec, the discussion is attached directly to the AC it concerns.

4. Gherkin Export📋

Some teams have existing BDD tooling they are not ready to abandon. Some auditors specifically request Gherkin-formatted documentation. tspec accommodates both with auto-generated .feature files.

Input:

/** Clicking a TOC entry loads the corresponding page. */
abstract tocClickLoadsPage(): ACResult;

/** The TOC highlights the currently active page. */
abstract tocHighlightsActivePage(): ACResult;

Generated output:

Feature: Table of Contents Navigation

  Scenario: Clicking a TOC entry loads the corresponding page
    Given the user is viewing a document with a table of contents
    When the user clicks a TOC entry
    Then the corresponding page loads

  Scenario: The TOC highlights the currently active page
    Given the user has navigated to a page via the TOC
    Then the TOC entry for that page is highlighted

The Scenario line comes directly from the JSDoc. The Given/When/Then steps are generated using configurable templates — the default template produces reasonable output, and teams can customize the generation rules.

The key insight: the .feature files are generated artifacts, not source-of-truth artifacts. They exist for compatibility and documentation. The abstract class remains authoritative. If someone edits the .feature file by hand, the next generation overwrites it. One source of truth, multiple output formats.

5. PDF and Confluence Export📋

Compliance officers reviewing for ISO 27001 or SOC 2 do not want to log into a dashboard. They want a PDF they can stamp and file.

The report generator produces compliance documentation in multiple formats:

• PDF: Feature list, AC coverage, test evidence, approval history, timeline. Formatted for printing with headers, page numbers, and a summary table.
• Confluence: Wiki-formatted pages pushed via API. One page per Epic, sub-pages per Feature. Auto-updated on each scan.
• CSV: Raw data for auditors who want to run their own pivot tables.
• JSON: Machine-readable for integration with GRC (Governance, Risk, Compliance) platforms.

The content is identical across formats — it comes from the same scan data. The format is a rendering concern, handled by output adapters. Adding a new format means writing a new adapter, not restructuring the data.

6. Manual Test Tracking📋

Not every acceptance criterion can be automated. "The UI feels responsive" is subjective. "The PDF renders correctly on paper" requires printing. "The accessibility audit passes" involves a human with a screen reader.

The dashboard supports manual test tracking. A QA engineer opens a feature, finds an uncovered AC, and marks it as "manually verified" with notes, screenshots, and a date. The scanner tracks automated coverage. The dashboard combines both.

Coverage percentage = (automated-covered ACs + manually-verified ACs) / total ACs.

A feature with 8 ACs might have 6 covered by automated tests and 2 manually verified. That is 100% coverage. The dashboard distinguishes the two with icons — automated tests get a robot icon, manual verifications get a clipboard icon — so the team knows which ACs depend on human effort and might need re-verification after changes.

Manual verifications have an expiration policy. If a feature's code changes significantly (measured by scanner diff), manual verifications are flagged as "stale" and require re-verification. The system does not silently count outdated manual checks as current coverage.

Closing BDD's Last Advantage📋

BDD had one genuine advantage over code-level specifications: readability for non-developers. tspec closes that gap without adopting BDD's disadvantages (disconnected step definitions, fragile regex matching, no compiler enforcement).

The abstract class is the spec. The compiler enforces it. The scanner measures it. The dashboard renders it in English. The PM approves it. The auditor exports it as PDF. Everyone works from the same source of truth, in the format that suits them.

Previous: Part VIII: Dashboard Deep-Dive | Next: Part X: Dog-Fooding