froid-plane-test-architecture-enterprise 1.23.4

package/docs/reference/execution-targets.md

@@ -0,0 +1,106 @@
+---
+title: 'Execution Targets'
+description: Which test technologies TEA supports, at what depth, and what you supply for the rest
+---
+
+# Execution Targets
+
+TEA Core (risk scoring, test design, NFR criteria, traceability, gate decisions) applies to every project regardless of stack. This page covers the other layer: which execution technologies TEA has built-in depth for, and where that depth stops.
+
+See [Verification Architecture](/docs/explanation/verification-architecture.md) for why the two layers are separate.
+
+## How to read the tiers
+
+An execution target needs six things from TEA: detection, project layout, runner configuration, commands, CI wiring, and review criteria. How many of the six are present determines the tier.
+
+| Tier           | Detection | Project layout | Runner configuration | Commands | CI wiring | Review criteria |
+| -------------- | --------- | -------------- | -------------------- | -------- | --------- | --------------- |
+| **Full**       | Yes       | Yes            | Yes                  | Yes      | Yes       | Yes             |
+| **Generation** | Yes       | Yes            | Yes                  | Yes      | Yes       | Partial         |
+| **Evidence**   | n/a       | No             | No                   | No       | No        | No              |
+| **Core only**  | No        | No             | No                   | No       | No        | No              |
+
+**Core only is not "unsupported."** Risk assessment, test design, NFR planning, traceability, and the release gate all work on a Core-only target. What you do not get is scaffolding, generated tests, or a quality score.
+
+## Full support
+
+| Target                     | Frameworks                                               | Notes                                                                                                                                                   |
+| -------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Web browser E2E            | Playwright (default), Cypress                            | The deepest path. Fixture architecture, network-first patterns, selector resilience, burn-in, sharding, healing, and browser automation via CLI or MCP. |
+| HTTP and service tests     | Typed API clients, OpenAPI-driven suites                 | Schema validation, retries, polling for eventual consistency, operation-level coverage.                                                                 |
+| Consumer-driven contracts  | Pact (PactJS)                                            | Consumer and provider verification, message contracts for async and Kafka boundaries, broker and PactFlow integration, determinism configuration.       |
+| Component tests            | Testing Library, Cypress component, Playwright component | Red-green-refactor loop, interaction-over-implementation criteria.                                                                                      |
+| Webhook and async delivery | Provider-agnostic (WireMock, MockServer, Mockoon)        | Polling, template matching, timeout diagnostics.                                                                                                        |
+| Mobile native              | Maestro (iOS, Android, React Native, Expo, Flutter)      | `mobile` stack detection, Maestro suite scaffolding, a dedicated generation worker, two-tier device CI, and mobile rows in the review ledger.           |
+
+## Generation support
+
+TEA detects the stack, scaffolds the framework, and generates tests. It has no curated knowledge fragments for these frameworks, so generated tests follow the conventions named in the workflow step plus whatever conventions exist in your repository. Review scoring is partial: most registry criteria are written against JavaScript and browser constructs.
+
+| Language      | Frameworks                     | Scaffolds                                                                                                                          | Coverage of the six |
+| ------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
+| Python        | pytest (default), unittest     | Layout, `pyproject.toml`, `.python-version`, `pytest --cov`, CI commands                                                           | 5 of 6              |
+| Java / Kotlin | JUnit 5 (default), TestNG      | Layout, `pom.xml`, `.java-version`, `mvn test` / `gradle test`, CI commands and caching                                            | 5 of 6              |
+| Go            | `go test` (with testify)       | Layout, `go test -race ./...`, module caching                                                                                      | 5 of 6              |
+| C# / .NET     | xUnit (default), NUnit, MSTest | Layout, `.csproj`, `global.json`, `dotnet test`, NuGet restore                                                                     | 5 of 6              |
+| Ruby          | RSpec (default), Minitest      | Layout, `.rspec`, `.ruby-version`, `bundle exec rspec`, bundle caching                                                             | 5 of 6              |
+| Rust          | `cargo test`                   | Directory layout only. Offered at framework selection but not carried into config generation, scripts, or CI. Treat as incomplete. | 2 of 6              |
+| Node backend  | Jest, Vitest                   | Layout, config, commands, CI                                                                                                       | 5 of 6              |
+
+Burn-in is enabled by default for frontend and fullstack stacks and skipped by default for backend-only stacks, on the assumption that backend suites are deterministic. Override it if your backend suite touches shared state.
+
+## Evidence support
+
+TEA plans these, sets thresholds, requires the evidence, and audits what you produce. It does not run the tools or parse their output.
+
+| Category             | Tools named                              | What TEA does                                                                                                                               |
+| -------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Performance and load | k6 (worked examples), JMeter, Gatling    | Sets SLO and SLA thresholds during test design, requires results during the NFR evidence audit, scores the category PASS / CONCERNS / FAIL. |
+| Security             | OWASP ZAP, Burp Suite, `npm audit`, Snyk | Same. Threshold definition and evidence audit; no scanner is invoked or parsed.                                                             |
+| Reliability          | Your telemetry and chaos tooling         | Same.                                                                                                                                       |
+| Maintainability      | CI coverage report, jscpd, `npm audit`   | Same. Reads coverage, duplication, and vulnerability reports your CI already produces; does not run them.                                   |
+
+The NFR gate defaults to CONCERNS when a threshold or its evidence is undefined, so an unmeasured category does not silently pass.
+
+## Core only
+
+TEA has no execution support for these. Risk, design, NFR planning, traceability, and gating all apply.
+
+| Target                                                 | Status                                                                                               |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| Mobile native via Appium, XCUITest, Espresso, or Detox | No scaffolding and no review criteria. TEA scaffolds Maestro for mobile; configure these as `other`. |
+| Desktop applications (Electron, WinAppDriver, Tauri)   | No support.                                                                                          |
+| Embedded, firmware, hardware-in-the-loop               | No support.                                                                                          |
+| Mainframe and legacy (COBOL, AS/400)                   | No support.                                                                                          |
+| Data pipelines (dbt, Airflow, Great Expectations, ETL) | No support. Contract testing covers the service boundary, not the pipeline.                          |
+| LLM and agent evaluation                               | No support as a test target.                                                                         |
+
+Mobile _web_ is covered by the web browser target through device emulation. That runs a resized desktop browser engine, not a device, and should not be reported as native mobile coverage; native apps use the Maestro target above.
+
+## CI platforms
+
+| Platform       | Template | Notes                                                           |
+| -------------- | -------- | --------------------------------------------------------------- |
+| GitHub Actions | Yes      | Default when detection is ambiguous.                            |
+| GitLab CI      | Yes      |                                                                 |
+| Jenkins        | Yes      |                                                                 |
+| Azure DevOps   | Yes      | The only template with a machine-checkable backend conditional. |
+| Harness        | Yes      |                                                                 |
+| CircleCI       | No       | Generated from first principles.                                |
+
+All shipped templates are written around a Node and browser toolchain and are adapted to your stack during generation. On a non-Node backend, review the generated pipeline's install and test commands before merging rather than assuming they are correct.
+
+## Known gaps
+
+Published deliberately, so an evaluation does not have to discover them:
+
+- **No knowledge fragments exist for any backend test framework.** 40 of 59 fragments name Playwright or Cypress and 3 cover mobile; zero cover pytest, JUnit, Go test, xUnit, or RSpec. Generation for those stacks relies on inline workflow conventions rather than a curated pattern library.
+- **Review criteria are still mostly JavaScript-shaped.** The registry carries 34 rows: 7 are portable across languages, 4 are mobile-specific, 2 are playwright-utils adoption rows gated on `tea_use_playwright_utils` plus the package being installed, and the rest key on browser, Testing Library, Vitest, or Pact constructs. Scores on non-JavaScript, non-Maestro suites are directionally useful and not comparable to scores on a JavaScript suite.
+- **Rust is declared but incomplete.** See the generation table above.
+- **CI templates are Node-first.** See the CI section above.
+
+## Requesting a target
+
+Open an issue at [GitHub Issues](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/issues) describing the stack, the runner, and the file format its tests are written in. The last item matters most: a target becomes reviewable once the criteria registry has rows that can attach to its format.
+
+To extend TEA yourself, see [Extend TEA with Custom Workflows](/docs/how-to/customization/extend-tea-with-custom-workflows.md) and [Knowledge Base System](/docs/explanation/knowledge-base-system.md).

package/docs/reference/knowledge-base.md

@@ -0,0 +1,271 @@
+---
+title: 'TEA Knowledge Base Index'
+description: Complete index of TEA's 59 knowledge fragments for context engineering
+---
+
+# TEA Knowledge Base Index
+
+TEA loads domain standards into context from 59 knowledge fragments, selected per workflow by the `tea-index.csv` manifest. Why that beats prompting, and how loading is wired: [Knowledge Base System](/docs/explanation/knowledge-base-system.md).
+
+This page indexes every row of that manifest. Each entry is named by its manifest `id`, which differs from the file name for a few fragments; the link resolves to the file. The `Tier` column is the manifest's own `tier` value and decides when the fragment loads (see [Loading tiers](#loading-tiers)).
+
+## Fragment Categories
+
+### Architecture & Fixtures
+
+Core patterns for test infrastructure and fixture composition.
+
+| Fragment                                                                                                                                                                 | Tier     | Description                                                          | Key Topics                             |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------- | -------------------------------------- |
+| [fixture-architecture](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/fixture-architecture.md) | core     | Pure function → Fixture → mergeTests composition with auto-cleanup   | Testability, composition, reusability  |
+| [network-first](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/network-first.md)               | core     | Intercept-before-navigate workflow, HAR capture, deterministic waits | Flakiness prevention, network patterns |
+| [playwright-config](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/playwright-config.md)       | extended | Environment switching, timeout standards, artifact outputs           | Configuration, environments, CI        |
+| [fixtures-composition](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/fixtures-composition.md) | extended | mergeTests composition patterns for combining utilities              | Fixture merging, utility composition   |
+
+**Used in:** `framework`, `test-design`, `atdd`, `automate`, `test-review`
+
+---
+
+### Data & Setup
+
+Patterns for test data generation, authentication, and setup.
+
+| Fragment                                                                                                                                                     | Tier        | Description                                                  | Key Topics                        |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------ | --------------------------------- |
+| [data-factories](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/data-factories.md) | core        | Factory patterns with faker, overrides, API seeding, cleanup | Test data, factories, cleanup     |
+| [auth-session](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/auth-session.md)     | core        | Token persistence, multi-user, API/browser authentication    | Auth patterns, session management |
+| [email-auth](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/email-auth.md)         | specialized | Magic link extraction, state preservation, negative flows    | Authentication, email testing     |
+
+**Used in:** `framework`, `atdd`, `automate`, `test-review`
+
+---
+
+### Network & Reliability
+
+Network interception, error handling, and reliability patterns.
+
+| Fragment                                                                                                                                                                     | Tier     | Description                                                    | Key Topics                      |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------- | ------------------------------- |
+| [network-recorder](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/network-recorder.md)             | extended | HAR record/playback, CRUD detection for offline testing        | Offline testing, network replay |
+| [intercept-network-call](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/intercept-network-call.md) | extended | Network spy/stub, JSON parsing for UI tests                    | Mocking, interception, stubbing |
+| [error-handling](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/error-handling.md)                 | extended | Scoped exception handling, retry validation, telemetry logging | Error patterns, resilience      |
+| [network-error-monitor](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/network-error-monitor.md)   | extended | HTTP 4xx/5xx detection for UI tests                            | Error detection, monitoring     |
+
+**Used in:** `atdd`, `automate`, `test-review`
+
+---
+
+### Test Execution & CI
+
+CI/CD patterns, burn-in testing, and selective test execution.
+
+| Fragment                                                                                                                                                           | Tier     | Description                                        | Key Topics                   |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------- | ---------------------------- |
+| [ci-burn-in](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/ci-burn-in.md)               | extended | Staged jobs, shard orchestration, burn-in loops    | CI/CD, flakiness detection   |
+| [burn-in](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/burn-in.md)                     | extended | Smart test selection, git diff for CI optimization | Test selection, performance  |
+| [selective-testing](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/selective-testing.md) | extended | Tag/grep usage, spec filters, diff-based runs      | Test filtering, optimization |
+
+**Used in:** `ci`, `test-review`
+
+---
+
+### Quality & Standards
+
+Test quality standards, test level selection, TDD patterns, and the generation-safety gate.
+
+| Fragment                                                                                                                                                                   | Tier     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Key Topics                                |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| [test-quality](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/test-quality.md)                   | core     | Execution limits, isolation rules, green criteria                                                                                                                                                                                                                                                                                                                                                                                                           | DoD, best practices, anti-patterns        |
+| [test-levels](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/test-levels-framework.md)           | core     | Guidelines for choosing unit, integration, or end-to-end coverage                                                                                                                                                                                                                                                                                                                                                                                           | Test pyramid, level selection             |
+| [test-priorities](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/test-priorities-matrix.md)      | core     | P0–P3 criteria, coverage targets, execution ordering                                                                                                                                                                                                                                                                                                                                                                                                        | Prioritization, risk-based testing        |
+| [test-healing-patterns](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/test-healing-patterns.md) | core     | Common failure patterns and automated fixes                                                                                                                                                                                                                                                                                                                                                                                                                 | Debugging, healing, fixes                 |
+| [confidence-gate](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/confidence-gate.md)             | core     | 1-10 confidence score with a stop-and-ask rule below threshold, so the agent declares unknowns instead of fabricating them                                                                                                                                                                                                                                                                                                                                  | Agent safety, generation, governance      |
+| [evidence-integrity](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/evidence-integrity.md)       | core     | Checks that cannot fail including assertions already true before the action, three-state diagnostics, probes that issue the client's own request, verifying the outcome rather than the act, verifying framework properties before use, stating environment asymmetry including screen geometry and accumulated credentials, ranking hypotheses by the cost of the measurement that kills them, and recording what a change did rather than what it was for | Falsifiability, hollow green, diagnostics |
+| [component-tdd](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/component-tdd.md)                 | extended | Red→green→refactor workflow, provider isolation                                                                                                                                                                                                                                                                                                                                                                                                             | TDD, component testing                    |
+
+**Used in:** `test-design`, `atdd`, `automate`, `test-review`, `trace`
+
+`confidence-gate` covers selectors, endpoints, risk classification, fixtures, schemas, and data factories. Any generation step that cannot establish a value from the repo records it as an unknown rather than inventing it.
+
+`evidence-integrity` covers the other half of the same problem: a check that cannot go red, and a diagnostic that reports a verdict it could not measure. Both produce green with nothing behind it, which is why the review registry's CRITICAL rows exist.
+
+---
+
+### Risk & Gates
+
+Risk assessment, governance, and gate decision frameworks.
+
+| Fragment                                                                                                                                                                                       | Tier     | Description                                                          | Key Topics                            |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------- | ------------------------------------- |
+| [risk-governance](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/risk-governance.md)                                 | core     | Scoring matrix, category ownership, gate decision rules              | Risk assessment, governance           |
+| [probability-impact](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/probability-impact.md)                           | core     | Probability × impact scale for scoring matrix                        | Risk scoring, impact analysis         |
+| [nfr-criteria](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/nfr-criteria.md)                                       | extended | Security, performance, reliability, maintainability status           | NFRs, compliance, enterprise          |
+| [adr-quality-readiness-checklist](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/adr-quality-readiness-checklist.md) | extended | 8-category, 29-criteria framework for testability and NFR compliance | Quality readiness, ADR, NFR checklist |
+
+**Used in:** `test-design`, `nfr-assess`, `trace`
+
+---
+
+### Selectors & Timing
+
+Selector resilience, race condition debugging, and visual debugging.
+
+| Fragment                                                                                                                                                               | Tier        | Description                                           | Key Topics                         |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------- | ---------------------------------- |
+| [selector-resilience](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/selector-resilience.md) | core        | Robust selector strategies and debugging              | Selectors, locators, resilience    |
+| [timing-debugging](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/timing-debugging.md)       | extended    | Race condition identification and deterministic fixes | Race conditions, timing issues     |
+| [visual-debugging](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/visual-debugging.md)       | specialized | Trace viewer usage, artifact expectations             | Debugging, trace viewer, artifacts |
+
+**Used in:** `atdd`, `automate`, `test-review`
+
+---
+
+### Feature Flags & API Patterns
+
+Feature flag testing and pure API testing patterns.
+
+| Fragment                                                                                                                                                                 | Tier        | Description                                             | Key Topics                   |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------- | ---------------------------- |
+| [feature-flags](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/feature-flags.md)               | specialized | Enum management, targeting helpers, cleanup, checklists | Feature flags, toggles       |
+| [api-testing-patterns](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/api-testing-patterns.md) | specialized | Pure API patterns without browser                       | API testing, backend testing |
+
+**Used in:** `test-design`, `atdd`, `automate`
+
+---
+
+### Pact & Contract Testing Integration
+
+Contract testing fundamentals plus Pact.js Utils, Pact MCP, and broker operations.
+
+| Fragment                                                                                                                                                                                     | Tier        | Description                                                                                                                                                               | Key Topics                                      |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| [contract-testing](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/contract-testing.md)                             | specialized | Raw Pact patterns, publishing, verification, resilience, PactV4 four-rule determinism and FFI safety block                                                                | Contract testing, Pact fundamentals             |
+| [pactjs-utils-overview](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/pactjs-utils-overview.md)                   | specialized | Installation, flow decision tree, utility map                                                                                                                             | pactjs-utils, CDCT/BDCT, integration strategy   |
+| [pactjs-utils-mandate](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/pactjs-utils-mandate.md)                     | core        | The binding rule when `tea_use_pactjs_utils` is true: substitution table, the relevance gate before scaffolding, banned patterns, pre-emit self-check, broker degradation | Standards, contract testing, generation, review |
+| [pactjs-utils-zod-to-pact](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/pactjs-utils-zod-to-pact.md)             | specialized | `zodToPactMatchers` for consumer-curated schemas, example precedence, Pact V3 matcher mapping, anti-patterns                                                              | pactjs-utils, zod, consumer schemas, matchers   |
+| [pactjs-utils-consumer-helpers](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/pactjs-utils-consumer-helpers.md)   | specialized | Provider-state helpers: `createProviderState`, `toJsonMap`; request/response callback helpers: `setJsonBody`, `setJsonContent`                                            | pactjs-utils, consumer testing, provider state  |
+| [pactjs-utils-provider-verifier](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/pactjs-utils-provider-verifier.md) | specialized | `buildVerifierOptions`, `buildMessageVerifierOptions`, broker selectors, tagging                                                                                          | pactjs-utils, provider verification, CI         |
+| [pactjs-utils-request-filter](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/pactjs-utils-request-filter.md)       | specialized | `createRequestFilter`, `noOpRequestFilter` auth/header patterns                                                                                                           | pactjs-utils, request filter, auth injection    |
+| [pact-mcp](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/pact-mcp.md)                                             | specialized | SmartBear MCP tools for provider states, review, can-i-deploy, matrix                                                                                                     | pact-mcp, broker interaction, pactflow          |
+| [pact-consumer-framework-setup](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/pact-consumer-framework-setup.md)   | specialized | Consumer CDC framework scaffolding: directory layout, scripts, CI workflow, and PactV4 test patterns                                                                      | pactjs-utils, consumer CDC, framework setup     |
+| [pact-broker-webhooks](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/pact-broker-webhooks.md)                     | specialized | PactFlow → GitHub `repository_dispatch` auth via a dedicated machine user and classic PAT, staleness monitoring, PAT rotation runbook                                     | pact broker, webhooks, CI operations, security  |
+| [pact-consumer-di](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/pact-consumer-di.md)                             | extended    | Dependency-injection pattern for Pact consumer tests using real client code                                                                                               | pact, consumer, DI, contract accuracy           |
+
+**Used in:** `framework`, `test-design`, `atdd`, `automate`, `test-review`, `ci` (conditioned by `tea_use_pactjs_utils` and `tea_pact_mcp`)
+
+An expired PAT on the PactFlow webhook is the most common non-code cause of `can-i-deploy` timing out with `There is no verified pact between ...`. `pact-broker-webhooks` carries the rotation runbook.
+
+---
+
+### Webhook Testing
+
+Delivery-side testing for asynchronous, eventually-consistent webhook flows using the `@seontechnologies/playwright-utils` webhook module.
+
+| Fragment                                                                                                                                                                         | Tier     | Description                                                                                                                                                                       | Key Topics                                 |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| [webhook-fundamentals](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/webhook-testing-fundamentals.md) | core     | Why webhook delivery is hard: async arrival, parallel pollution, opaque timeouts, cleanup drift. Polling, typed matchers, rich errors, `startedAt` isolation                      | Async, event-driven, eventually consistent |
+| [webhook-setup](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/webhook-module-setup.md)                | core     | Fixture wiring for WireMock/MockServer/Mockoon providers, matched-only vs full-reset cleanup, the `fullyParallel` race fix                                                        | Fixtures, providers, setup                 |
+| [webhook-matchers](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/webhook-template-matchers.md)        | core     | `matchField` (dot-path exact), `matchPartial` (deep subset), `matchPredicate` (arbitrary fn), AND semantics, template factories, `clone`, `withTimeout`, `withInterval`           | Matchers, templates, patterns              |
+| [webhook-waiting](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/webhook-waiting-querying.md)          | core     | `waitFor`, `waitForCount`, `getReceived`, the drain pattern for sequential events, parallel worker safety via ID-scoped templates                                                 | Polling, querying, parallel safety         |
+| [webhook-risk](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/webhook-risk-guidance.md)                | core     | When webhook tests are required, the P2×I3 default risk score, the test checklist, failure patterns and mitigations                                                               | Risk assessment, governance, TA checklist  |
+| [webhook-timeout-error](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/webhook-timeout-error.md)       | extended | `WebhookTimeoutError` fields (`templateName`, `timeoutMs`, `totalReceived`, `receivedWebhooks`, `matcherDetails`, `toJSON`) for inspecting what arrived against what was expected | Debugging, errors                          |
+| [webhook-providers](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/webhook-providers.md)               | extended | WireMock (`deleteById` supported), MockServer (`deleteById` no-op), Mockoon (`deleteById` no-op, 100-entry limit), the custom `WebhookProvider` interface                         | Providers, capability differences          |
+
+**Used in:** `framework`, `test-design`, `atdd`, `automate`, `test-review`, `ci`, `trace`
+
+---
+
+### Mobile Native
+
+Maestro device flows and the level discipline that decides what becomes a flow at all. Loaded when `test_stack_type` is `mobile` or when the review set contains a Maestro flow (`.yaml`/`.yml` under `maestro/` or `.maestro/`, or `*.flow.yaml` or `*.flow.yml`).
+
+| Fragment                                                                                                                                                                 | Tier        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Key Topics                                                      |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| [mobile-test-strategy](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/mobile-test-strategy.md) | specialized | Mobile test level framework, what belongs in a device flow, mobile risk categories, device matrix with a gate profile matching local, CI shape, no live third-party flag evaluation in the run path                                                                                                                                                                                                                                                              | Levels, risk, device matrix, permissions, lifecycle             |
+| [maestro-flows](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/maestro-flows.md)               | specialized | Flow structure, selector hierarchy, `clearState` isolation, synchronization without sleeps, subflow composition, command semantics that differ by platform, `text:` selectors as whole-element regex, taps that report COMPLETED without being handled, visible meaning inside the viewport, asserting the transition rather than a state that may already hold                                                                                                  | Maestro, selectors, isolation, regex selectors, anti-patterns   |
+| [mobile-ci-device-lab](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/mobile-ci-device-lab.md) | specialized | Build artifact selection including why a debug-variant development build does not solve it, dev-server manifest signing in non-interactive CI, one device profile across local and CI, native modules that degrade silently in a shell, deep links reachable through the shell's routed URL form, emulator snapshot caching, repairing locally created AVDs, per-device identity for sharded runs, runner version pinning, artifact layout and failure diagnosis | Build artifact, emulator, caching, pinning, sharding, artifacts |
+
+**Used in:** `framework`, `automate`, `atdd`, `test-design`, `test-review`, `ci` (when `test_stack_type` is `mobile` or a Maestro flow is present)
+
+The browser fragments (`network-first`, `playwright-config`, `intercept-network-call`, `selector-resilience`) are deliberately NOT loaded for a mobile stack: a device flow has no DOM and no request interceptor.
+
+---
+
+### Browser Automation
+
+CLI and MCP integration for AI-driven browser automation during test generation.
+
+| Fragment                                                                                                                                                     | Tier | Description                                                                                     | Key Topics                                |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- | ----------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| [playwright-cli](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/playwright-cli.md) | core | Token-efficient CLI for AI coding agents: element refs, sessions, snapshots, browser automation | CLI, browser, agent, automation, snapshot |
+
+**Used in:** `atdd`, `automate`, `test-design`, `test-review`, `nfr-assess` (when `tea_browser_automation` is `cli` or `auto`)
+
+---
+
+### Playwright-Utils Integration
+
+Patterns for the `@seontechnologies/playwright-utils` package (10 utility modules).
+
+| Fragment                                                                                                                                                                               | Tier     | Description                                                                                                                                                                                                                    | Key Topics                                |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
+| [overview](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/overview.md)                                       | core     | Installation, design principles, fixture-based utility patterns for API and UI                                                                                                                                                 | Overview, architecture, principles        |
+| [playwright-utils-mandate](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/playwright-utils-mandate.md)       | core     | The binding rule when `tea_use_playwright_utils` is true: substitution table, REQUIRED vs RECOMMENDED levels, banned patterns, pre-emit self-check, deviation protocol                                                         | Standards, generation, review, governance |
+| [library-integration-mandate](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/library-integration-mandate.md) | core     | The general contract every library mandate instantiates: two gates (flag plus install), enforcement levels, deviation protocol, scope discipline, the flag-to-mandate registry, and the ten places a new library must be wired | Standards, governance, extensibility      |
+| [api-request](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/api-request.md)                                 | core     | Typed HTTP client, schema validation, retry logic, operation-based overload                                                                                                                                                    | API calls, HTTP, OpenAPI, codegen         |
+| [recurse](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/recurse.md)                                         | extended | Async polling for API responses, background jobs, eventual consistency                                                                                                                                                         | Polling, eventual consistency             |
+| [log](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/log.md)                                                 | extended | Report logging and structured output for API and UI tests                                                                                                                                                                      | Logging, debugging, reporting             |
+| [file-utils](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/blob/main/src/agents/froid-tea/resources/knowledge/file-utils.md)                                   | extended | CSV/XLSX/PDF/ZIP validation for API exports and UI downloads                                                                                                                                                                   | File validation, exports                  |
+
+The package's remaining fragments are indexed under the category that matches what they do: `auth-session` (Data & Setup); `network-recorder`, `intercept-network-call`, and `network-error-monitor` (Network & Reliability); `burn-in` (Test Execution & CI); `fixtures-composition` (Architecture & Fixtures, since `mergeTests` applies to all fixtures); and the seven `webhook-*` fragments (Webhook Testing).
+
+**Used in:** `framework`, `test-design`, `atdd`, `automate`, `test-review`, `ci` (all gated on `tea_use_playwright_utils: true`)
+
+`playwright-utils-mandate` loads first on every one of them. It decides how the other fragments are applied: generation follows its substitution table by default, and `test-review` reads its REQUIRED list as the firing predicate for registry rows `M9` and `L9`. `pactjs-utils-mandate` plays the same role for Pact suites and row `M10`. Both instantiate `library-integration-mandate`, which holds the contract they share and the checklist for wiring in the next library.
+
+**Official Docs:** <https://seontechnologies.github.io/playwright-utils/>
+
+---
+
+## Fragment Manifest (tea-index.csv)
+
+**Location:** `src/agents/froid-tea/resources/tea-index.csv`
+
+**Fragment location:** `src/agents/froid-tea/resources/knowledge/` (all 59 fragments in a single directory)
+
+**Structure:**
+
+```csv
+id,name,description,tags,tier,fragment_file
+test-quality,Test Quality Definition of Done,"Execution limits, isolation rules, green criteria","quality,definition-of-done,tests",core,knowledge/test-quality.md
+risk-governance,Risk Governance,"Scoring matrix, category ownership, gate decision rules","risk,governance,gates",core,knowledge/risk-governance.md
+```
+
+**Columns:**
+
+- `id` - Unique fragment identifier (kebab-case). This is the name workflows cite, and it is not always the file stem
+- `name` - Human-readable fragment name
+- `description` - What the fragment covers
+- `tags` - Searchable tags (comma-separated)
+- `tier` - Loading priority (see below)
+- `fragment_file` - Path to the fragment markdown file, relative to `resources/`
+
+### Loading tiers
+
+Workflows do not carry per-workflow fragment lists. Each workflow step declares `knowledgeIndex: './resources/tea-index.csv'` and selects fragments at run time by tier, then narrows by stack and config:
+
+- **Core:** loaded whenever the workflow starts.
+- **Extended:** loaded when the workflow's context calls for it, such as `auth-session` once the tests involve authentication.
+- **Specialized:** loaded only on a matching use case, such as `contract-testing` for microservices or `email-auth` for email flows.
+
+Loading core fragments alone cuts context usage 40-50% against loading everything.
+
+Four config keys narrow the set further: `tea_use_playwright_utils`, `tea_use_pactjs_utils`, `tea_pact_mcp`, and `tea_browser_automation`. `test_stack_type: mobile` swaps the browser fragments for the Maestro pair. See [TEA Configuration](/docs/reference/configuration.md).
+
+---
+
+## Related
+
+- [Knowledge Base System](/docs/explanation/knowledge-base-system.md) - How context engineering works and why
+- [TEA Overview](/docs/explanation/tea-overview.md) - How the knowledge base fits in TEA
+- [TEA Command Reference](/docs/reference/commands.md) - Workflows that use fragments

package/docs/reference/live-verification-results.md

@@ -0,0 +1,193 @@
+---
+title: 'Live Verification Results'
+description: The JSON contract trace reads when a requirement was verified by running the system rather than by adding a test file
+---
+
+# Live Verification Results
+
+This file records verification performed by running the system rather than by adding a test file. `trace` reads it under the `live` coverage level and counts a record as coverage alongside static tests.
+
+Two limits apply, and both are enforced:
+
+- **A record must be recorded against the commit under trace.** A `source_sha` that does not match makes the record `stale`, and stale contributes no coverage.
+- **Live-only evidence can never produce a PASS gate.** A requirement whose only evidence is a live record caps the gate at CONCERNS.
+
+## What this contract is for
+
+`trace` reads this file. It never writes it, and it never runs anything to produce it.
+
+Any producer can emit it. An agent that drove the app, a shell script wrapping a smoke run, a CI job posting results from a device farm, or a person recording an outcome by hand all satisfy the contract equally. `trace` has no dependency on which one you used, matching how TEA records every other kind of evidence independently of the tool that produced it. See [Verification Architecture](/docs/explanation/verification-architecture.md).
+
+## Where trace looks
+
+```yaml
+live_results_input: '{test_artifacts}/live-verification-results.json'
+```
+
+Set a different path in the `trace` workflow's `workflow.yaml` if you produce the file elsewhere. When the file is absent, `trace` uses static test discovery only.
+
+## File schema
+
+```json
+{
+  "schema_version": "0.1.0",
+  "source_sha": "9f2c41d8b7e35a06c1d4f8e29b7a3c5d6e081f42",
+  "observed_at": "2026-08-11T14:32:00Z",
+  "producer": "manual verification by release engineer",
+  "results": [
+    {
+      "id": "1.3-LIVE-001",
+      "requirement_id": "AC-1",
+      "title": "User can sign in with a valid password",
+      "status": "pass",
+      "evidence": "Signed in as qa@example.com, landed on /dashboard with the account menu populated."
+    }
+  ]
+}
+```
+
+A longer example covering a passing record, a blocked one, and one recorded against an older commit ships with the workflow at `src/workflows/testarch/froid-testarch-trace/resources/live-verification-results.example.json`.
+
+The tables below distinguish **Enforced** fields, whose absence stops a record or the whole file from counting, from **Recorded** fields, which are carried into the report but never rejected. Getting an enforced field wrong changes your coverage; getting a recorded field wrong only makes the report less useful.
+
+### Top-level fields
+
+| Field            | Trace does                                                                                               |
+| ---------------- | -------------------------------------------------------------------------------------------------------- |
+| `schema_version` | **Enforced.** `"0.1.0"`. A different major version makes the whole file unreadable and raises a blocker. |
+| `source_sha`     | **Enforced.** The git commit the observations were made against. Per-result `source_sha` overrides it.   |
+| `results`        | **Enforced.** Must be an array. May be empty. Anything else makes the file unreadable.                   |
+| `observed_at`    | Recorded. ISO 8601 timestamp. Per-result `observed_at` overrides it.                                     |
+| `producer`       | Recorded. Free text naming whatever recorded the run. Reported back in `e2e-trace-summary.json`.         |
+
+### Result records
+
+| Field            | Trace does                                                                                                 |
+| ---------------- | ---------------------------------------------------------------------------------------------------------- |
+| `id`             | **Enforced.** Test-case ID, format below. Must be unique in the file; a repeat is `invalid`.               |
+| `requirement_id` | **Enforced.** The oracle item this verifies. Must match an id `trace` resolved, such as `AC-1` or `J-02`.  |
+| `status`         | **Enforced.** One of `pass`, `fail`, `blocked`, `skipped`.                                                 |
+| `source_sha`     | **Enforced** when the file has no top-level `source_sha`. Overrides the file-level commit for this record. |
+| `title`          | Recorded. What was verified, in one line. Falls back to the `id` when absent.                              |
+| `evidence`       | Recorded. What was observed, or a URL to a recording, log, or screenshot.                                  |
+| `observed_at`    | Recorded. Overrides the file-level timestamp for this record.                                              |
+
+### Test-case ID format
+
+```
+{target}-LIVE-{NNN}
+```
+
+`{target}` is the story, epic, or release identifier already used for the run. `{NNN}` is a zero-padded sequence. This matches the existing `1.3-E2E-001` convention, with `LIVE` as the level segment, so live results sort and read alongside static test IDs in the matrix.
+
+Examples: `1.3-LIVE-001`, `2.7-LIVE-014`, `v1.4.0-LIVE-003`.
+
+## What counts as coverage
+
+A record counts as coverage only when all four hold:
+
+1. Its `status` is `pass`.
+2. Its `source_sha` matches the commit under trace.
+3. It carries a unique `id` and a `requirement_id`.
+4. That `requirement_id` names an item in the coverage oracle `trace` resolved, and no other record reports a `fail` for the same item.
+
+Everything else is recorded as a blocker in the traceability matrix and contributes no coverage:
+
+| Outcome        | What happened                                                                      | Blocker severity |
+| -------------- | ---------------------------------------------------------------------------------- | ---------------- |
+| `stale`        | Recorded against a different commit than the one under trace                       | high             |
+| `unverifiable` | The current commit sha could not be resolved, so freshness is unknowable           | high             |
+| `fail`         | The verification failed                                                            | high             |
+| `contradicted` | Passed, but another record reports a `fail` for the same `requirement_id`          | high             |
+| `blocked`      | The verification never reached a verdict                                           | medium           |
+| `skipped`      | The verification was skipped                                                       | medium           |
+| `unmatched`    | `requirement_id` names an item not in the resolved coverage oracle                 | medium           |
+| `invalid`      | Missing or duplicate `id`, missing `requirement_id`, no `source_sha`, bad `status` | medium           |
+
+An unreadable file (bad JSON, no `results` array, or an unsupported `schema_version`) produces one file-level blocker with the id `live-results-unreadable` at high severity.
+
+A non-`pass` status is reported as itself regardless of freshness. A `fail` cannot count at any commit, so calling it stale would send you to re-record a run that already told you the requirement is broken.
+
+**Replace records, do not append them.** If you re-verify a requirement that previously failed, overwrite the old record. A file containing both a `fail` and a `pass` for the same `requirement_id` sets the passing record aside as `contradicted` and credits no coverage, because the alternative is letting an appended retry quietly overwrite a recorded failure.
+
+Two consequences worth planning around:
+
+**A stale live result is not a soft warning.** If a P0 requirement's only evidence is a live result recorded against an older commit, that requirement is uncovered, P0 coverage drops below 100%, and the gate fails. This is deliberate. A live pass is an observation of code that existed at one moment; carrying it forward would let a green gate describe software nobody ran. Re-record against the current commit or add a re-runnable test.
+
+**Short shas are fine.** Freshness compares case-insensitively and accepts an abbreviated sha of 7 characters or more as a prefix match, the same way `git` resolves them.
+
+## Why live-only coverage cannot reach PASS
+
+A requirement whose only evidence is a live record caps the gate at CONCERNS, never PASS. Live evidence leaves nothing anyone can re-run: it does not re-execute on the next commit, in CI, or for the next reviewer. That is the same treatment `trace` already gives requirements traced against an inferred oracle, and for the same reason. It is good enough to count, not good enough to sign off unconditionally.
+
+The cap only ever lowers a PASS to CONCERNS. It never lifts a FAIL, and it never fires when every counted requirement also has static test coverage.
+
+To reach PASS, add a re-runnable test at any level for the requirements the matrix reports as live-only. `trace` names them in its recommendations.
+
+## Turning the level off
+
+Remove `live` from `coverage_levels` in the `trace` workflow's `workflow.yaml`:
+
+```yaml
+coverage_levels: 'e2e,api,component,unit'
+```
+
+`trace` then ignores the results file entirely, including a stale one.
+
+The one exception is `collection_mode: runtime_manifest`. That mode names the results file as the run's only evidence source, so it implies the `live` level and reads the file whether or not `coverage_levels` lists it. Removing `live` does not turn live evidence off under that mode. To turn it off, change the collection mode as well.
+
+## Runs with no static suite
+
+Set `collection_mode: runtime_manifest` when recorded live verification is the run's only evidence source. `trace` skips static test discovery and reads the results file alone.
+
+Under that mode a missing or unreadable results file resolves `collection_status` to `INACCESSIBLE`, and no gate is emitted. The alternative would be reporting 0% coverage, which reads as "nothing is verified" when the truth is "the evidence could not be read".
+
+Because static discovery never runs, the `auth_negative_path_status` and `error_path_status` heuristics report `unknown` rather than `present`. Nothing examined those paths, so nothing can vouch for them.
+
+## What you get back
+
+`e2e-trace-summary.json` (schema `0.2.0` and later) carries a `live_evidence` block:
+
+```json
+{
+  "live_evidence": {
+    "present": true,
+    "results_file": "_froid-output/test-artifacts/live-verification-results.json",
+    "freshness": "fresh",
+    "recorded_source_sha": "9f2c41d8b7e35a06c1d4f8e29b7a3c5d6e081f42",
+    "current_source_sha": "9f2c41d8b7e35a06c1d4f8e29b7a3c5d6e081f42",
+    "producer": "manual verification by release engineer",
+    "counted": 3,
+    "stale": 0,
+    "unverifiable": 0,
+    "failed": 0,
+    "contradicted": 0,
+    "blocked": 0,
+    "skipped": 0,
+    "unmatched": 0,
+    "invalid": 0,
+    "requirements_live_only": 2
+  }
+}
+```
+
+`freshness` is one of:
+
+| Value          | Meaning                                                                     |
+| -------------- | --------------------------------------------------------------------------- |
+| `fresh`        | Every record was checkable and recorded against the commit under trace      |
+| `mixed`        | Some records counted, others are stale or unverifiable                      |
+| `stale`        | Records exist but none counted, because none matched the commit under trace |
+| `unverifiable` | The current commit sha could not be resolved, so nothing could be checked   |
+| `unreadable`   | The file exists but could not be parsed or failed its schema check          |
+| `not_present`  | No results file                                                             |
+
+`freshness` reports currency, not success. `fresh` means every record was checkable against the commit under trace; a fresh file can still be full of `fail` and `blocked` records. To gate on "current **and** successful", require `freshness === 'fresh'` and every non-counted counter at zero. `mixed` exists so that one counted record among twenty stale ones cannot report as current.
+
+Counted results also appear under `coverage.by_level.live`, so a dashboard can show how much of a release rests on evidence with no re-runnable artifact behind it.
+
+## Related
+
+- [How to Run Trace with TEA](/docs/how-to/workflows/run-trace.md) - the workflow that reads this file
+- [Verification Architecture](/docs/explanation/verification-architecture.md) - why evidence is recorded independently of the tool that produced it
+- [TEA Configuration](/docs/reference/configuration.md) - where TEA artifacts are written