# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.

---

## One-liner

`test-driver` is a use-case-driven verification framework whose tests mature
alongside the software they protect — fluid and agentic while behaviour is hot,
deterministic once it cools.

---

## Core Idea

A test is treated not as code but as a **verification asset** with identity,
intent, evidence, lineage, maturity, temperature and energy. Use cases are the
primary behavioural source; integration, journey, multi-user, security and
resilience tests are projections of the same use case rather than separate
suites.

Verification assets progress along a maturity continuum
(`T0 Exploratory → T5 Deterministic`) called **Crystallization**. Agents may
explore and realise semantic actions against unstable interfaces; oracles remain
deterministic and independent from actors, so the framework can distinguish a
legitimate mechanical change from a product defect rather than adapting to
whatever the implementation happens to do.

**Current state:** research prototype. Concept corpus is complete
(`INTENT.md`, `docs/`); implementation has not started. See
`history/2026-08-22-concept-assessment-swot.md` for the standing assessment and
the reasoning behind the current workplan sequence.

---

## In Scope

- The conceptual model: UseCase, Actor, Scenario, SemanticAction, Observation,
  Oracle, Verdict, VerificationAsset, Finding, Adaptation, Crystallization.
- A deterministic semantic scenario kernel and its evidence format.
- The **test-driver lab** — a small mutable application under test carrying
  labelled mechanical, semantic and defect mutations as ground truth.
- Adaptation detection and the defect-vs-adaptation classifier.
- Crystallization of agentic realisations into deterministic regression tests.
- Security testing expressed as mutation of ordinary use cases.
- Self-verification of the framework's own foundational guarantees.
- The research control plane: hypotheses, experiments, findings, fitness map.

---

## Out of Scope

- Replacing unit-test frameworks, browser automation engines, or CI systems.
- Building a load-testing, fuzzing, vulnerability-scanning or observability
  platform.
- Test-management SaaS, distributed test clouds, or multi-tenant hosting.
- Making all tests agentic, or using model judgment where a deterministic oracle
  is available.
- Rewriting semantic requirements to match implementation behaviour.
- Scale and performance verification before the conceptual model is proven.

---

## Relevant When

- You need the test-driver conceptual vocabulary or its canonical concept set.
- You are working on the crystallization, adaptation-classification, or
  semantic-action binding mechanisms.
- You are extending the lab or its mutation catalogue.
- You need the framework's hypotheses, fitness scorecard, or evidence format.

---

## Not Relevant When

- You need ordinary unit or component tests for another repo — use that repo's
  own test stack.
- You are looking for fleet coordination or cross-repo memory — that is State
  Hub.

---

## Getting Oriented

1. `INTENT.md` — purpose, thesis, design heuristics, non-goals.
2. `docs/TestDriverConceptModel.md` — the canonical concept set v0.1.
3. `docs/TestDriverImprovementLoop.md` — hypotheses, findings taxonomy,
   self-improvement cycle.
4. `docs/TestDriverInitialMilestones.md` — M0–M10 and the prototype success gate.
5. `history/2026-08-22-concept-assessment-swot.md` — assessment and the reasons
   the first workplan reorders those milestones into a vertical spike.
6. `workplans/` — current work. Agent instructions: `AGENTS.md`.

---

## Stack

Deliberately boring, per `docs/TestDriverResearchPrototype.md`: Python, pytest,
Playwright, Pydantic/dataclasses, YAML, SQLite. One process, one database, one
browser engine, one application under test. Novelty belongs in the verification
model, not the infrastructure.