bmad-method-test-architecture-enterprise 1.22.6 → 1.23.0

package/.claude-plugin/marketplace.json

@@ -31,7 +31,7 @@
       "name": "bmad-method-test-architecture-enterprise",
       "source": "./",
       "description": "Master Test Architect module for quality strategy, test automation, CI/CD quality gates, and structured testing education. Part of the BMad Method ecosystem.",
-      "version": "1.22.6",
+      "version": "1.23.0",
       "author": {
         "name": "Murat K Ozcan (TEA Creator) & Brian (BMad) Madison"
       },

package/.github/ISSUE_TEMPLATE/rule_quality_report.md

@@ -0,0 +1,46 @@
+---
+name: Rule Quality Report
+about: An agent misread, ignored, or was misled by a TEA rule or knowledge fragment
+title: ''
+labels: 'rule-quality'
+assignees: ''
+---
+
+TEA ships rules. This report is about a rule that failed to steer an agent, not about TEA crashing. One report per rule, please.
+
+**Agent and model**
+Which agent ran, and which model: e.g. Claude Code / Claude Opus 4.6, Cursor / GPT-5.1, Windsurf, Codex.
+
+**Which rule**
+The file and the section inside it. Examples:
+
+- `criteria-registry.md`, row H3
+- `resources/knowledge/network-first.md`, the "declare the intercept before navigating" section
+- a step file such as `steps-c/step-03-generate-tests.md`
+
+**Which workflow was running**
+e.g. `test-design`, `automate`, `atdd`, `test-review`, `trace`, `nfr-assess`, `ci`, `framework`, `teach-me-testing`.
+
+**The prompt you gave**
+
+```text
+
+```
+
+**What it produced**
+The non-compliant part only. Trim to the smallest excerpt that still shows the violation.
+
+```text
+
+```
+
+**What it should have done**
+State the behavior the rule was supposed to produce, and why you read the rule as requiring it.
+
+**Your read of the cause** (optional)
+
+- [ ] The rule says the right thing and the agent ignored it
+- [ ] The rule is ambiguous and the agent picked a defensible wrong reading
+- [ ] The rule is wrong or out of date
+- [ ] The rule was never loaded (wrong fragment selected, or none)
+- [ ] Not sure

package/.github/workflows/quality.yaml

@@ -7,6 +7,18 @@ name: Quality & Validation
 # - Schema validation (YAML structure)
 # - Agent schema tests (fixture-based validation)
 # - Installation component tests (compilation)
+#
+# The `validate` job must stay a superset of `npm test`'s non-lint half. Three
+# suites used to run ONLY from .husky/pre-commit — test:knowledge, test:changelog,
+# and test:tea-workflow-descriptions — and `git commit --no-verify` skips that
+# hook, as does every edit made through the GitHub web UI. test:knowledge is the
+# one carrying the knowledge-copy parity check across the eight bmad-testarch workflows, so for as long as it was
+# absent here nothing in CI stopped the workflow copies of the knowledge base from
+# silently diverging from the agent's.
+#
+# test:cli is the deliberate exception in the other direction: it runs here and
+# NOT in `npm test`, because it takes ~12 minutes (measured: 12m21s) and `npm test`
+# runs on every commit through the pre-commit hook.
 
 "on":
   pull_request:
@@ -116,5 +128,44 @@ jobs:
       - name: Test agent compilation components
         run: npm run test:install
 
+      - name: Test knowledge base (index sync, link resolution, workflow-copy parity)
+        run: npm run test:knowledge
+
+      - name: Validate criteria-registry to fragment traceability
+        run: npm run test:criteria-fragments
+
+      - name: Test write-time enforcement hook
+        run: npm run test:enforce-hook
+
+      - name: Validate fragment-selection eval data
+        run: npm run test:eval-data
+
+      - name: Test changelog stamping
+        run: npm run test:changelog
+
+      - name: Validate TEA workflow descriptions
+        run: npm run test:tea-workflow-descriptions
+
+  # Split out of `validate` on its own: it takes ~12 minutes, and leaving it in
+  # line meant every fast check behind it reported 12 minutes late.
+  cli:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          # This job only reads. actions/checkout persists the job token in
+          # .git/config by default, where any step or test process could read it.
+          persist-credentials: false
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
       - name: Test TEA test-review CLI
         run: npm run test:cli

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.23.0] - 2026-08-15
+
+### Added
+
+- Write-time enforcement hook, scaffolded by the `framework` workflow. TEA was advisory (knowledge fragments) plus post-hoc (`test-review` scoring) with nothing at the write itself, so a `.only`, a `waitForTimeout`, or a `Thread.sleep` could land, be committed, and only surface at review. `src/workflows/testarch/bmad-testarch-framework/resources/hooks/tea-enforce.cjs` blocks the write instead, and `steps-c/step-04-docs-and-scripts.md` installs it plus its `.claude/settings.json` registration into the target project. Rules are the mechanically decidable `Absolute` rows of `criteria-registry.md` (C2, C3, C4 for Maestro flows, H1, H5, H6, H8 block; C1 warns, because its row is conditioned on a documented, still-true reason that no pattern can check). Multi-language by construction: Playwright, Cypress, Vitest/Jest, Pact, pytest, JUnit, Go test, and Maestro flows each get their own predicates and their own comment and string stripping, so a `waitForTimeout` inside a comment or a doc example is not a violation. Three passes rather than one: `--pre` blocks the fragment about to be written, `--post` re-reads the whole file from disk (which is what catches writes made through Bash, violations split across two edits, and whole-file rules), and `--stop` sweeps test files modified during the turn (which is what catches a codegen script that wrote files it never named). The hook fails open on any error of its own.
+- The hook honours the registry's `Gate` column structurally. `.tea/enforce-config.json` carries only the globs for the stack the `framework` workflow actually detected, so a repo with no Maestro flows cannot fire the Maestro rows and a repo with no pact config cannot fire H6 or H8. `excludeGlobs` keeps k6 scripts out, where `sleep(1)` is the documented way to model think-time and H1 would be confidently wrong. A closed gate is not a violation, which is defect #1 from the couture-cast PR #103 postmortem in `DESIGN-CRITERIA-REGISTRY.md`, applied to a second enforcement surface.
+- The scaffold records the hook's sha256 in `.tea/enforce-config.json`, and the hook compares its own file against it on `--stop` only, warning once and never blocking. The instruction to copy the script byte for byte pointed at a test that lives in the TEA repository, so nothing inside the target project would have noticed a locally edited copy — and a locally edited copy is exactly the one that is no longer covered by the test keeping its rules in agreement with the registry.
+- `tools/validate-criteria-fragments.js`: traceability between `criteria-registry.md` and the knowledge fragments. Nothing asserted that a registry row still had a fragment teaching it, nor that a mapped fragment still carried its claim at the registry's pinned severity. It fails on a mapped fragment that lost its anchor, a manifest row pointing at a fragment that does not exist or is not indexed in `tea-index.csv`, a severity that no longer matches the registry, and a registry row that is neither mapped nor declared a gap. It found 14 rows with no fragment teaching them at all, which are closed in this same release (below), taking coverage from 21/35 to 35/35 over 46 anchors. The gap-declaration mechanism stays: a registry row that is neither mapped to a fragment nor declared a gap fails the build, and with no real gap left to exercise that path the tool now self-checks it against a synthetic row so a refactor cannot quietly kill the guard.
+- Knowledge for the 14 registry rows nothing taught, added to the four fragments that already own the surrounding material rather than as 14 new files, since fragmenting the base makes selection worse. `test-quality.md` gains committed skips and committed focus (C1, C2), assertions that cannot fail (C3 tautological, C5 asserted against the test's own mock, C6 unreachable), and suite structure and naming (M3 counted by subject rather than by `expect` call, M4 grouping, M7 nesting, L5 behavioral names, L7 one assertion dialect). `timing-debugging.md` gains wall-clock fixtures with fake timers as the fix (H2) and unawaited promises in test bodies (M6). `component-tdd.md` gains user-level interaction over raw event dispatch (M5), gated on the project already depending on such an API. `data-factories.md` gains naming the domain literals a test hardcodes on purpose (L6), which is the half the factory patterns never covered. Examples appear in the languages each row's own predicate names — Python and JUnit skip forms for C1, `assert x == x` for C3, `freeze_time` for H2 — rather than in TypeScript alone. The `tags` and `description` columns for all four fragments gained the terms that make the new material selectable, in the agent index and all eight workflow copies.
+- `test/eval-fragment-selection.js` plus per-workflow eval data under `test/evals/`: measures whether the right fragment comes out of `tea-index.csv` for a given task, which is the failure mode where an agent loads the wrong fragment, or none, and answers from prior. Twenty-four cases across all eight workflows that ship a knowledge base (`automate`, `test-design`, `atdd`, `ci`, `framework`, `nfr`, `test-review`, `trace`), seeded from Playwright, Cypress, pytest, JUnit, Go, Pact, GitLab CI, and Maestro scenarios rather than from Playwright alone, since fragment selection for a non-JavaScript stack is where TEA is most likely to route wrong. `teach-me-testing` is excluded because it ships no `resources/knowledge`: its fragment browsing is a menu the learner drives rather than a routing decision the agent makes. Every non-JavaScript case asserts the run-level precondition that nothing else was measuring: both library flags default true, and in a repo with no JavaScript manifest neither package can be installed, so both mandates must stay closed. Ground truth is quoted from each workflow's own step files, never from `tea-index.csv` tags, because tags describe a fragment while step files decide what a run loads. `--validate-only` runs in CI with no vendor cost and rejects a name in either direction that does not exist or is not indexed for that workflow, so a typo in a forbidden list cannot pass vacuously; the scored run needs a logged-in `claude` or `codex`.
+- `.github/ISSUE_TEMPLATE/rule_quality_report.md`: a low-friction report for the failure that matters most in a rules product, an agent misreading, ignoring, or being misled by a TEA rule or knowledge fragment. Captures the agent and model, the rule and section, the workflow, the prompt, the non-compliant output, and what should have happened.
+
+### Fixed
+
+- `teach-me-testing` session 7 could reach only 42 of the 59 knowledge fragments. Every mobile fragment (`maestro-flows`, `mobile-test-strategy`, `mobile-ci-device-lab`), the entire seven-fragment webhook family, both integration mandates, `library-integration-mandate`, `confidence-gate`, and `evidence-integrity` had no category to appear under, so the only browsable view of the knowledge base silently hid a third of it. The menu gains a Mobile category and a Webhooks category, the existing categories absorb the rest, and the sixteen places that advertised "42 fragments" now state the real number. `test-knowledge-base.js` Test Suite 6 asserts all of it: every fragment appears exactly once, no phantom entries, each category subtotal matches its own list, and every stated total matches the base. The count matching the short menu is what kept the shortfall invisible.
+
+- `quality.yaml` did not run the full test suite. `test:knowledge`, `test:changelog`, and `test:tea-workflow-descriptions` ran only from `.husky/pre-commit`, which `git commit --no-verify` skips and which no GitHub web-UI edit ever reaches. `test:knowledge` is the suite carrying the knowledge-base parity check across the eight workflow copies, so until now nothing in CI stopped the workflow copies from silently diverging from the agent's. All three now run in the `validate` job, alongside the three new checks above. `test:cli` moved to its own job: it takes 12m21s measured, and leaving it in line made every fast check behind it report twelve minutes late. It stays out of `npm test` for the same reason, since `npm test` runs on every commit.
+
 ## [1.22.6] - 2026-08-14
 
 ### Fixed

package/eslint.config.mjs

@@ -81,9 +81,12 @@ export default [
     },
   },
 
-  // CLI scripts under cli/**, tools/** and test/**
+  // CLI scripts under cli/**, tools/** and test/**, plus the hook scripts the
+  // framework workflow copies verbatim into a user's project. Those must stay
+  // plain, dependency-free CommonJS that runs on whatever Node the project has,
+  // so the same relaxations apply.
   {
-    files: ['cli/**/*.js', 'tools/**/*.js', 'tools/**/*.mjs', 'test/**/*.js'],
+    files: ['cli/**/*.js', 'tools/**/*.js', 'tools/**/*.mjs', 'test/**/*.js', 'src/workflows/**/resources/hooks/*.cjs'],
     rules: {
       // Allow CommonJS patterns for Node CLI scripts
       'unicorn/prefer-module': 'off',

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-test-architecture-enterprise",
-  "version": "1.22.6",
+  "version": "1.23.0",
   "description": "Master Test Architect for quality strategy, test automation, and release gates",
   "keywords": [
     "bmad",
@@ -39,6 +39,7 @@
     "docs:fix-links": "node tools/fix-doc-links.js --write",
     "docs:preview": "npm --prefix website run preview",
     "docs:validate-links": "node tools/validate-doc-links.js",
+    "eval:fragment-selection": "node test/eval-fragment-selection.js",
     "eval:test-review": "node test/eval-test-review.js",
     "format:check": "prettier --check .",
     "format:fix": "prettier --write .",
@@ -51,10 +52,13 @@
     "release:minor": "gh workflow run publish.yaml -f channel=latest -f bump=minor",
     "release:next": "gh workflow run publish.yaml -f channel=next",
     "release:patch": "gh workflow run publish.yaml -f channel=latest -f bump=patch",
-    "test": "npm run test:schemas && npm run test:install && npm run test:knowledge && npm run test:release-metadata && npm run test:changelog && npm run test:tea-workflow-descriptions && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:schemas && npm run test:install && npm run test:knowledge && npm run test:criteria-fragments && npm run test:enforce-hook && npm run test:eval-data && npm run test:release-metadata && npm run test:changelog && npm run test:tea-workflow-descriptions && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
     "test:changelog": "node test/test-stamp-changelog.js",
     "test:cli": "node test/test-test-review-cli.js",
     "test:coverage": "c8 npm test",
+    "test:criteria-fragments": "node tools/validate-criteria-fragments.js",
+    "test:enforce-hook": "node test/test-enforce-hook.js",
+    "test:eval-data": "node test/eval-fragment-selection.js --validate-only",
     "test:install": "node test/test-installation-components.js",
     "test:knowledge": "node test/test-knowledge-base.js",
     "test:release-metadata": "node test/test-release-metadata.js",

package/src/agents/bmad-tea/resources/knowledge/component-tdd.md

@@ -455,6 +455,42 @@ export default defineConfig({
 - Update snapshots when visual changes are intentional
 - Visual tests catch unintended CSS/layout regressions
 
+### Example 5: User-Level Interaction, Not Raw Event Dispatch
+
+**Context**: A component test exists to prove the component behaves the way a person driving it would experience. `fireEvent` dispatches one synthetic event straight at the node. A real interaction is a sequence: pointer down, focus, key events, input events, pointer up, blur. Dispatching only the middle one skips everything the component might legitimately depend on, so the test can pass against a component no user can operate: a button that never receives focus, a field whose `onKeyDown` handler is never exercised, an input that ignores paste.
+
+This is gated on the project already depending on a user-level API. Where `userEvent` (or its equivalent) is a project dependency, it is the interaction API and `fireEvent` is the deviation. Where it is not installed, `fireEvent` is what the project has and this row does not fire. Adding a dependency is a project decision, not a review finding.
+
+`fireEvent` remains the right tool for the events a user cannot produce directly: a synthetic `error` on an image, a `transitionend`, a scroll event from an observer.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: dispatches change directly. Focus, key events, and input events never
+// happen, so a component that validates on keystroke is never exercised.
+fireEvent.change(screen.getByLabelText('Email'), { target: { value: 'ada@example.com' } });
+fireEvent.click(screen.getByRole('button', { name: 'Submit' }));
+expect(onSubmit).toHaveBeenCalled();
+
+// ✅ GOOD: the full interaction sequence a person produces
+const user = userEvent.setup();
+await user.type(screen.getByLabelText('Email'), 'ada@example.com');
+await user.click(screen.getByRole('button', { name: 'Submit' }));
+expect(onSubmit).toHaveBeenCalledWith({ email: 'ada@example.com' });
+
+// ✅ ACCEPTABLE: an event no user can dispatch by hand
+fireEvent.error(screen.getByRole('img', { name: 'Avatar' }));
+expect(screen.getByTestId('avatar-fallback')).toBeVisible();
+```
+
+**Key Points**:
+
+- Where a user-level API is already a project dependency, it is the interaction API
+- The failure mode is a passing test for a component a real user cannot operate
+- `userEvent` is asynchronous: its calls are awaited, which also removes a class of unawaited-promise flake
+- `fireEvent` stays correct for events users cannot produce (`error`, `transitionend`, observer-driven scroll)
+- If the project has no user-level API installed, this is not a violation
+
 ## Integration Points
 
 - **Used in workflows**: `*atdd` (component test generation), `*automate` (component test expansion), `*framework` (component testing setup)

package/src/agents/bmad-tea/resources/knowledge/data-factories.md

@@ -437,6 +437,45 @@ test('free accounts cannot access analytics', async ({ page, apiRequest }) => {
 - Still allow overrides: `createProAccount({ maxUsers: 50 })` works
 - Test intent clear: `createProAccount()` vs `createAccount({ plan: 'pro', features: [...] })`
 
+### Example 6: Naming the Literals You Do Hardcode
+
+**Context**: Everything above is about generating data so tests stay parallel-safe and unique. This is the other half, and the factories do not cover it: the literals a test writes on purpose because the assertion is about that exact value. A boundary, a rate, a limit, a status code, a currency scale.
+
+Those are correct to hardcode. Leaving them anonymous is what costs. `expect(fee).toBe(2.9)` tells the next reader that the fee is 2.9 and nothing about why, so when the number changes nobody can tell whether the test encodes a requirement or someone's old guess. The reader has to go find the pricing document, and usually does not.
+
+The fix is a name, not a comment, and not a constant file. A named constant beside the test, or a factory override that reads as the domain fact, puts the meaning at the point of use.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: two unexplained literals. Which is a requirement, which is arbitrary?
+test('applies the processing fee', async () => {
+  const order = createOrder({ subtotal: 100 });
+  expect(feeFor(order)).toBe(2.9);
+});
+
+// ✅ GOOD: each number states what it is
+const STRIPE_PERCENT_FEE = 0.029; // per the payments contract, section 4
+
+test('applies the processing fee', async () => {
+  const subtotal = 100;
+  const order = createOrder({ subtotal });
+  expect(feeFor(order)).toBe(subtotal * STRIPE_PERCENT_FEE);
+});
+
+// ✅ ALSO GOOD: the factory carries the domain fact, so the test reads as
+// behavior and the limit needs no name at the call site at all
+const order = createOrderAtItemLimit();
+await expect(addItem(order)).rejects.toThrow('order is full');
+```
+
+**Key Points**:
+
+- Generate data that only needs to be unique; name data that carries meaning
+- The test is where the requirement gets encoded, so the number needs to say which requirement
+- Name at the point of use; a shared constants file moves the meaning away from the reader again
+- A value used once, whose meaning the test name already states, does not need a second name; this is about unexplained literals, not about every number
+
 ## Integration Points
 
 - **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (factory setup)

package/src/agents/bmad-tea/resources/knowledge/test-quality.md

@@ -639,6 +639,183 @@ test('admin action', async ({ page }) => {
 - Reuse auth sessions via `storageState` (Playwright) or `setCookie` (Cypress)
 - Skip unnecessary flows (email verification, multi-step signups)
 
+### Example 6: Committed Skips and Committed Focus
+
+**Context**: A suite reports green. Two of the ways it does that have nothing to do with the code being correct: a test that was turned off, and a test that turned every one of its siblings off.
+
+A skip is not automatically a defect. A skip whose reason nobody can read is. The reason belongs on the line or the line directly above it, it has to name the condition that will make the test runnable again, and it has to still be true. A `FIXME` pointing at a bug closed six months ago is a deleted test with extra steps. If you cannot write that reason, delete the test; a deleted test is honest about the coverage you no longer have, and a permanently skipped one is not.
+
+Focus is different, and worse. `.only` is a debugging tool that changes what the whole file runs. Committed, the file still passes, still reports as a passing file, and covers one test. Nothing in the output says the other nineteen did not run.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: the reason is gone, so nobody can tell whether this is still needed
+test.skip('checkout applies the promo code', async ({ page }) => {
+  /* ... */
+});
+
+// ✅ GOOD: the condition to remove the skip is on the line
+// FIXME(TEA-412): promo service returns 500 in staging; re-enable when TEA-412 lands
+test.skip('checkout applies the promo code', async ({ page }) => {
+  /* ... */
+});
+
+// ❌ BAD: the other tests in this file no longer run, and nothing says so
+test.only('checkout applies the promo code', async ({ page }) => {
+  /* ... */
+});
+```
+
+```python
+# ❌ BAD: skipped with no reason anyone can act on
+@pytest.mark.skip
+def test_invoice_voids_after_payment():
+    ...
+
+# ✅ GOOD: pytest carries the reason in the marker itself
+@pytest.mark.skip(reason="void endpoint returns 500 upstream, see TEA-412")
+def test_invoice_voids_after_payment():
+    ...
+```
+
+```java
+// ❌ BAD: JUnit's bare form records nothing
+@Disabled
+void settlementRetriesWithBackoff() { }
+
+// ✅ GOOD: the annotation takes the reason
+@Disabled("flaky against the shared broker; unblocked by TEA-412")
+void settlementRetriesWithBackoff() { }
+```
+
+**Key Points**:
+
+- A skip with a documented, still-true reason is acceptable; a bare one is not
+- Prefer deleting over skipping indefinitely: coverage you admit losing beats coverage you pretend to have
+- `.only`, `fdescribe`, and `fit` must never be committed: they disable siblings silently
+- Guard both in CI, not only in review: a grep in the pipeline costs nothing and a committed `.only` costs a release
+
+### Example 7: Assertions That Cannot Fail
+
+**Context**: Example 3 keeps assertions visible. Visible is not the same as meaningful. Three shapes execute, look like assertions in the diff, and prove nothing: one compares a value to itself, one checks the mock instead of the system, and one never runs at all. All three are worse than having no test, because the suite reports green and the coverage number goes up.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: compares a value to itself; passes no matter what the app does
+expect(true).toBe(true);
+expect(user.id).toBe(user.id);
+
+// ✅ GOOD: the expectation could differ from the actual
+expect(response.status()).toBe(201);
+expect(user.email).toBe(userData.email);
+
+// ❌ BAD: the only assertion is against the mock this test configured.
+// Nothing called into the system between setting it up and checking it,
+// so this proves the mocking library works.
+const repo = { save: vi.fn().mockResolvedValue({ id: 1 }) };
+repo.save({ name: 'Ada' });
+expect(repo.save).toHaveBeenCalledWith({ name: 'Ada' });
+
+// ✅ GOOD: the system under test is what calls the mock, and the assertion
+// is about what the system returned
+const repo = { save: vi.fn().mockResolvedValue({ id: 1 }) };
+const created = await createAccount(repo, { name: 'Ada' });
+expect(created.id).toBe(1);
+expect(repo.save).toHaveBeenCalledWith({ name: 'Ada' });
+
+// ❌ BAD: unreachable. The return happens first.
+test('rejects an expired token', async () => {
+  const result = await authorize(expiredToken);
+  return;
+  expect(result.ok).toBe(false);
+});
+
+// ❌ BAD: unreachable. The happy path never enters the catch, so a passing
+// run asserts nothing and a broken run is swallowed.
+try {
+  await authorize(expiredToken);
+} catch (error) {
+  expect(error.code).toBe('EXPIRED');
+}
+
+// ✅ GOOD: assert on the rejection itself, against the same property the
+// catch block was checking. `rejects.toThrow('EXPIRED')` matches the error
+// MESSAGE, so swapping it in here would quietly assert something else.
+await expect(authorize(expiredToken)).rejects.toMatchObject({ code: 'EXPIRED' });
+```
+
+```python
+# ❌ BAD: tautological; true for every possible value of total
+assert total == total
+
+# ✅ GOOD
+assert total == Decimal("42.00")
+```
+
+**Key Points**:
+
+- If the assertion would pass against a completely broken implementation, it is not an assertion
+- Configuring a mock and then asserting on that same mock, with no call into the system between, tests the mocking library
+- An assertion after an unconditional `return`, or inside a `catch` the happy path never enters, or inside a callback the test never awaits, does not run
+- Prefer `rejects`/`raises` forms over `try`/`catch` around the thing you expect to throw: they fail when nothing throws
+
+### Example 8: Suite Structure, Naming, and One Dialect
+
+**Context**: These do not make a test wrong. They make a failure expensive to read, which is the same cost paid every time the suite goes red for the next several years.
+
+A test that asserts against three unrelated subjects does not localize: the failure says the test broke, not which behavior broke. Count subjects, not `expect` calls: three assertions about one response is one concern, and one assertion each about a response, a database row, and an email is three. An ungrouped file prints failures with no subject line. Nesting past three levels means the reader reconstructs the setup from four `beforeEach` blocks before they can read the test. A name that states the implementation goes stale the moment the implementation changes and tells the reader nothing when it fails. And a file that mixes assertion dialects makes every reader translate between two styles for no benefit.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: three unrelated subjects; a failure does not say which one broke
+test('checkout works correctly', async ({ page, request }) => {
+  await checkout(page);
+  expect(await orderCount(request)).toBe(1); // subject: the order API
+  expect(await inventoryFor(request, 'sku-1')).toBe(9); // subject: inventory
+  expect(await lastEmail()).toContain('Order confirmed'); // subject: email
+});
+
+// ✅ GOOD: one subject per test, grouped, named for the behavior
+describe('checkout', () => {
+  test('records the order', async ({ request }) => {
+    /* one subject */
+  });
+  test('decrements inventory for the purchased sku', async ({ request }) => {
+    /* one subject */
+  });
+  test('sends the confirmation email', async () => {
+    /* one subject */
+  });
+});
+
+// ❌ BAD: names the implementation, or nothing at all
+test('calls handleSubmit()', ...);
+test('getUserById works correctly', ...);
+
+// ✅ GOOD: names the behavior, so the failure line is the bug report
+test('rejects a submission with no email', ...);
+test('returns 404 for an unknown user id', ...);
+
+// ❌ BAD: two dialects in one file
+expect(response.status()).toBe(200);
+assert.equal(body.role, 'admin');
+
+// ✅ GOOD: pick the house dialect and keep it
+expect(response.status()).toBe(200);
+expect(body.role).toBe('admin');
+```
+
+**Key Points**:
+
+- One concern per test, counted by subject rather than by `expect` call
+- Group with `describe`/`context` once a file has three or more tests, so failures print with a subject
+- Keep `describe` nesting and block nesting at three levels or fewer
+- Name the behavior, not the method, the selector, or "works correctly"
+- One assertion dialect per file, matching whatever the repo already uses
+
 ## Integration Points
 
 - **Used in workflows**: `*atdd` (test generation quality), `*automate` (test expansion quality), `*test-review` (quality validation)
@@ -661,5 +838,11 @@ Every test must pass these criteria:
 - [ ] **Explicit Assertions** - Keep `expect()` calls in test bodies, not hidden in helpers
 - [ ] **Unique Data** - Use `faker` for dynamic data; never hardcode IDs or emails
 - [ ] **Parallel-Safe** - Tests don't share state; run successfully with `--workers=4`
+- [ ] **No Committed Focus** - No `.only`, `fdescribe`, or `fit` reaches the branch
+- [ ] **Skips Documented** - Every skip carries a still-true reason naming what would re-enable it
+- [ ] **Assertions Can Fail** - No self-comparison, no assertion against only the mock the test configured, nothing after an unconditional `return`
+- [ ] **One Concern** - Counted by subject, not by `expect` call
+- [ ] **Grouped and Shallow** - `describe`/`context` once a file has three tests; nesting three levels or fewer
+- [ ] **Behavioral Names, One Dialect** - Names state the behavior; the file uses a single assertion style
 
 _Source: Murat quality checklist, Definition of Done requirements (lines 370-381, 406-422)._

package/src/agents/bmad-tea/resources/knowledge/timing-debugging.md

@@ -290,6 +290,98 @@ test.describe('Timing Anti-Patterns to Avoid', () => {
 
 ---
 
+### Example 4: Fixtures Derived From the Live Clock
+
+**Context**: A hard wait makes a test slow and flaky. Reading the live clock makes it flaky on a schedule nobody can reproduce. The test that builds an expiry, a token lifetime, a TTL, or a scheduling boundary from `Date.now()` passes all day and fails at a month boundary, at midnight UTC, on the last day of February, or on the CI runner whose clock drifted four seconds.
+
+This is a HIGH rather than a MEDIUM because of what these values usually govern. A token lifetime computed from the wall clock is a security boundary tested against a moving target: the test cannot distinguish "the expiry logic is correct" from "the expiry has not happened yet."
+
+The fix is to control time rather than to read it. Freeze it, then move it deliberately to the boundary the behavior is about.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: the boundary moves with the clock, and the failure lands on a Tuesday
+const token = issueToken({ expiresAt: Date.now() + 3600_000 });
+await sleep(1000);
+expect(isExpired(token)).toBe(false); // proves nothing about expiry
+
+// ✅ GOOD: freeze, then step across the boundary on purpose.
+// Restore in afterEach, never as the last line of the test: an assertion that
+// throws would skip that line and leave every later test on a fake clock, which
+// is the unreset-shared-state defect wearing a different hat.
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+test('the token expires at its TTL', () => {
+  vi.useFakeTimers();
+  vi.setSystemTime(new Date('2026-01-01T00:00:00Z'));
+  const token = issueToken({ ttlSeconds: 3600 });
+  expect(isExpired(token)).toBe(false);
+  vi.advanceTimersByTime(3601_000);
+  expect(isExpired(token)).toBe(true); // the boundary is what is under test
+});
+```
+
+```python
+# ❌ BAD: the fixture is different on every run
+expires_at = time.time() + 3600
+
+# ✅ GOOD: pin the clock, then move it
+with freeze_time("2026-01-01T00:00:00Z") as frozen:
+    token = issue_token(ttl_seconds=3600)
+    assert not is_expired(token)
+    frozen.tick(3601)
+    assert is_expired(token)
+```
+
+**Key Points**:
+
+- A time-bounded value built from the live clock is not a fixture, it is a variable
+- Freeze the clock and advance it deliberately; the boundary is the behavior under test
+- Restore real timers in `afterEach`, so a failing assertion cannot leave a later test on a fake clock
+- Where the production code already takes an injectable clock, pass one. A production seam the application itself uses beats a test-only seam that only the suite knows about
+- A timestamp merely stamped into a record and never asserted against is not this defect; the row is about values that govern an expiry, a lifetime, a TTL, or a schedule
+
+### Example 5: Promises Nobody Awaited
+
+**Context**: The most common way for a race condition to be in the test rather than in the application. A promise-returning call that is neither awaited nor returned starts its work and hands control straight to the next line, so the assertion runs against the state from before the effect. Usually it still passes, because the effect is fast. It fails on the loaded CI runner, which is the one machine where the failure is least reproducible.
+
+An unawaited rejection is the second half: it surfaces as an unhandled rejection attributed to whichever test happened to be running when it settled, so the reported test and the broken test are different tests.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: the click may not have landed when the assertion runs
+test('adds the item to the cart', async ({ page }) => {
+  page.getByRole('button', { name: 'Add to cart' }).click();
+  await expect(page.getByTestId('cart-count')).toHaveText('1');
+});
+
+// ❌ BAD: the setup promise is still in flight
+test('shows the seeded order', async ({ page, request }) => {
+  seedOrder(request, { id: 'ord-1' });
+  await page.goto('/orders/ord-1');
+  await expect(page.getByText('ord-1')).toBeVisible();
+});
+
+// ✅ GOOD: await the effect before asserting on it
+test('adds the item to the cart', async ({ page }) => {
+  await page.getByRole('button', { name: 'Add to cart' }).click();
+  await expect(page.getByTestId('cart-count')).toHaveText('1');
+});
+```
+
+**Key Points**:
+
+- Every promise-returning call in a test body is awaited or explicitly returned
+- The symptom is a test that passes locally and fails on a loaded runner, which reads as flake rather than as a missing `await`
+- An unhandled rejection is usually attributed to the wrong test, so treat one as a signal to audit `await` coverage across the file, not only in the named test
+- `no-floating-promises` in the linter catches this class before the suite ever runs; prefer that to catching it in review
+
+---
+
 ## Async Debugging Techniques
 
 ### Technique 1: Promise Chain Analysis

package/src/agents/bmad-tea/resources/tea-index.csv

@@ -2,8 +2,8 @@ id,name,description,tags,tier,fragment_file
 library-integration-mandate,Library Integration Mandate,"General contract for every TEA integration library flag: the two gates (flag true plus package installed), REQUIRED vs RECOMMENDED levels, deviation protocol, scope discipline, the flag-to-mandate registry, and the ten places a new library must be wired","standards,governance,generation,review,integration,mandate",core,knowledge/library-integration-mandate.md
 fixture-architecture,Fixture Architecture,"Composable fixture patterns (pure function → fixture → merge) and reuse rules","fixtures,architecture,playwright,cypress",core,knowledge/fixture-architecture.md
 network-first,Network-First Safeguards,"Intercept-before-navigate workflow, HAR capture, deterministic waits, edge mocking","network,stability,playwright,cypress,ui",core,knowledge/network-first.md
-data-factories,Data Factories and API Setup,"Factories with overrides, API seeding, cleanup discipline","data,factories,setup,api,backend,seeding",core,knowledge/data-factories.md
-component-tdd,Component TDD Loop,"Red→green→refactor workflow, provider isolation, accessibility assertions","component-testing,tdd,ui",extended,knowledge/component-tdd.md
+data-factories,Data Factories and API Setup,"Factories with overrides, API seeding, cleanup discipline, and naming the domain literals a test hardcodes on purpose","data,factories,setup,api,backend,seeding,magic-value,literals,naming,constants",core,knowledge/data-factories.md
+component-tdd,Component TDD Loop,"Red→green→refactor workflow, provider isolation, accessibility assertions, and user-level interaction over raw event dispatch","component-testing,tdd,ui,user-event,fire-event,interaction",extended,knowledge/component-tdd.md
 playwright-config,Playwright Config Guardrails,"Environment switching, timeout standards, artifact outputs","playwright,config,env",extended,knowledge/playwright-config.md
 ci-burn-in,CI and Burn-In Strategy,"Staged jobs, shard orchestration, burn-in loops, artifact policy","ci,automation,flakiness",extended,knowledge/ci-burn-in.md
 selective-testing,Selective Test Execution,"Tag/grep usage, spec filters, diff-based runs, promotion rules","risk-based,selection,strategy",extended,knowledge/selective-testing.md
@@ -14,13 +14,13 @@ error-handling,Error Handling Checks,"Scoped exception handling, retry validatio
 visual-debugging,Visual Debugging Toolkit,"Trace viewer usage, artifact expectations, accessibility integration","debugging,dx,tooling,ui",specialized,knowledge/visual-debugging.md
 risk-governance,Risk Governance,"Scoring matrix, category ownership, gate decision rules","risk,governance,gates",core,knowledge/risk-governance.md
 probability-impact,Probability and Impact Scale,"Shared definitions for scoring matrix and gate thresholds","risk,scoring,scale",core,knowledge/probability-impact.md
-test-quality,Test Quality Definition of Done,"Execution limits, isolation rules, green criteria","quality,definition-of-done,tests",core,knowledge/test-quality.md
+test-quality,Test Quality Definition of Done,"Execution limits, isolation rules, green criteria, committed skips and focus, assertions that cannot fail, and suite structure and naming","quality,definition-of-done,tests,skip,only,focused,disabled,tautological,assertions,mocks,unreachable,concerns,grouping,nesting,naming,assertion-style",core,knowledge/test-quality.md
 nfr-criteria,NFR Review Criteria,"Security, performance, reliability, maintainability status definitions","nfr,assessment,quality",extended,knowledge/nfr-criteria.md
 test-levels,Test Levels Framework,"Guidelines for choosing unit, integration, or end-to-end coverage","testing,levels,selection,api,backend,ui",core,knowledge/test-levels-framework.md
 test-priorities,Test Priorities Matrix,"P0–P3 criteria, coverage targets, execution ordering","testing,prioritization,risk",core,knowledge/test-priorities-matrix.md
 test-healing-patterns,Test Healing Patterns,"Common failure patterns and automated fixes","healing,debugging,patterns",core,knowledge/test-healing-patterns.md
 selector-resilience,Selector Resilience,"Robust selector strategies and debugging techniques","selectors,locators,debugging,ui",core,knowledge/selector-resilience.md
-timing-debugging,Timing Debugging,"Race condition identification and deterministic wait fixes","timing,async,debugging",extended,knowledge/timing-debugging.md
+timing-debugging,Timing Debugging,"Race condition identification, deterministic wait fixes, wall-clock fixtures and fake timers, and unawaited promises in test bodies","timing,async,debugging,clock,fake-timers,expiry,ttl,unawaited,await,floating-promise",extended,knowledge/timing-debugging.md
 overview,Playwright Utils Overview,"Installation, design principles, fixture patterns for API and UI testing","playwright-utils,fixtures,api,backend,ui",core,knowledge/overview.md
 playwright-utils-mandate,Playwright Utils Mandate,"Binding rule when tea_use_playwright_utils is true: substitution table (page.route to interceptNetworkCall, raw request to apiRequest, waitForTimeout to recurse), REQUIRED vs RECOMMENDED levels, banned patterns, pre-emit self-check, deviation protocol","playwright-utils,standards,generation,review,governance,mandate",core,knowledge/playwright-utils-mandate.md
 api-request,API Request,"Typed HTTP client, schema validation, retry logic, operation-based overload for API and service testing","api,backend,service-testing,api-testing,playwright-utils,openapi,codegen,operation",core,knowledge/api-request.md

package/src/workflows/testarch/bmad-teach-me-testing/data/curriculum.yaml

@@ -78,7 +78,7 @@ sessions:
     duration: "ongoing"
     difficulty: advanced
     objective: "Deep-dive into specific knowledge fragments"
-    description: "Menu-driven exploration of 42 knowledge fragments organized by category"
+    description: "Menu-driven exploration of 59 knowledge fragments organized by category"
     recommended_for:
       - experienced
     prerequisites: []

package/src/workflows/testarch/bmad-teach-me-testing/data/session-content-map.yaml

@@ -219,4 +219,4 @@ sessions:
     key_concepts:
       - "Menu-driven fragment exploration"
       - "Just-in-time deep-dive learning"
-      - "42 knowledge fragments organized by category"
+      - "59 knowledge fragments organized by category"