Files

Danijel Martinek 89d47cce5c docs: strip dead docs/superpowers/ refs across ADRs + guides + glossary

The docs/superpowers/{specs,plans}/ directory was archived to .archive/
in an earlier session (and .archive/ is gitignored). Every md link
into that path is now a broken reference for anyone consuming the
template fresh.

Stripped:
  - ADR-011: **Spec:** header line
  - ADR-015: **Spec:** + **Plan:** header lines
  - ADR-016: **Spec:** + **Plan:** header lines + footer "Spec —"
    bullet (the design rationale is captured in the ADR body itself)
  - ADR-017: **Spec:** + **Plan:** header lines
  - ADR-018: **Spec:** + **Plan:** header lines
  - guides/realtime.md: inline "the full spec" link + footer
    [Spec] entry (folded its description into the ADR-016 entry)
  - guides/events-and-jobs.md: inline "the full spec" link
  - architecture/vertical-feature-spec.md: stale "Deleted" subsection
    referencing docs/superpowers/plans/*

Updated:
  - glossary.md "PRD" entry: clarified status flow now matches the
    shipped pnpm work prd-ship lifecycle (draft -> in-review ->
    approved -> shipped); removed the parenthetical pointing at
    docs/superpowers/specs/ as a definition of "spec"
  - glossary.md "spec" flagged-ambiguity: rewritten to reflect that
    durable design lives in ADRs (docs/decisions/adr-NNN-*.md) and
    implementation seeds live in PRDs (docs/work/prds/*.prd.md) —
    "spec" should be avoided in this template

Preserved (legitimate refs to the SuperPowers plugin, not the dir):
  - agent-first-workflow-and-conformance.md mentions of
    `superpowers:brainstorming` — these reference the external
    plugin skill, not a file in the repo

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-13 17:00:11 +02:00

2.7 KiB

Raw Blame History

ADR-011: TDD Foundation

Status: Accepted Date: 2026-05-05 Supersedes: none

Context

The vertical-feature monorepo refactor (ADRs 001-010) established clean architecture with per-feature DI containers but did not enforce TDD as the path of least resistance. Agentic workers were producing code-first commits with tests added later, leading to test theatre and mock/real drift.

Decision

New package @repo/core-testing (tag: tooling) — shared test utilities: defineFactory, defineContractSuite, renderWithProviders, mock-payload helpers, jsdom setup file. Tagged tooling so any package may depend on it as devDependency without boundary violation.
Vitest base configs split into node + jsdom with safety defaults (clearMocks, restoreMocks, mockReset, unstubGlobals, sequence.shuffle) and coverage thresholds (80/75/80/80 baseline; 100% in entities + use-cases + controllers).
Factories per feature in src/__factories__/ replace inline fixtures. Stable date defaults (2026-01-01) so snapshot diffs reflect SUT behavior only.
Contract suites per repository interface in src/__contracts__/ run against every implementation (Mock + Payload). Eliminates the class of bug where the mock and the real impl drift apart.
Tests in core-* packages and apps — composition smoke tests (appRouter, payloadConfig, bind-production, providers).
Storybook test-runner — every story executed as a smoke test.
CI workflow — typecheck + lint + boundaries + test + build + e2e + storybook on every PR. Coverage uploaded as artifact.
Two new docs — tdd-workflow.md (process) + restructured adding-a-feature.md (interleaves tests with impl).

Alternatives considered

Fixture files instead of factories — rejected. Fixtures rot with schema changes and require manual updates per test.
One shared test file per impl — rejected. Contract suites give the same coverage in fewer LOC and prevent drift.
Real Postgres in tests via testcontainers — rejected for unit tests (slow, complex). Repository contract suites + vi.mock('payload') give equivalent confidence in milliseconds.
Stryker mutation testing — deferred. Coverage thresholds + contract suites get us most of the way; mutation testing is incremental.

Consequences

New package to maintain (small, mostly stable surface).
Coverage thresholds may fail builds initially; we add tests to cross threshold as features land.
Sequence shuffle may surface latent flakes; we fix as found.
Templates for new features now require writing tests first; this is by design.

Refines

ADR-006 (boundary tags) — adds @repo/core-testing as a tooling package.

2.7 KiB Raw Blame History