test-driver/SCOPE.md

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.