docs(quality): unify skill concepts and performance interpretation

quality/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "quality",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "Evidence-driven skills that operate project-owned E2E, performance, and agent trajectory quality capabilities.",
   "author": {
     "name": "compforge",

quality/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "quality",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "Evidence-driven skills that operate project-owned E2E, performance, and agent trajectory quality capabilities.",
   "author": {
     "name": "compforge",

quality/CONCEPTS.md

@@ -0,0 +1,121 @@
+# Quality concepts
+
+E2E, performance, and trajectory skills use these semantics to identify the subject, operate a
+project capability, and interpret its evidence. Read this document before selecting a capability
+or interpreting a run. Domain workflows and preparation live in the skills and their references.
+
+## Ownership
+
+- The framework provides execution, collection, evaluation, reduction, and reporting mechanisms.
+- The project owns Cases, adapters, profiles, recordings, annotations, judgment criteria, target
+  policy, and the canonical entrypoint. Use that entrypoint when one exists.
+- The skill discovers and operates the capability, explains evidence, and improves project-owned
+  assets within the user's request. Framework presence alone does not establish usable coverage.
+
+These concepts align with the [quality-harness kernel](https://github.com/compforge/quality-harness/blob/main/docs/kernel.md).
+Map native project artifacts to their semantic roles; shared classes, field names, and file formats
+are not prerequisites. Check the project's actual SDK and artifact contracts before invoking an API
+or assuming that a model has been persisted.
+
+## Subject and runtime identity
+
+| Concept | Meaning and evidence to resolve |
+|---|---|
+| Repository | Source identity within a Forge, such as GitHub or GitLab; record its revision separately. |
+| Component | A unit in a Repository that can be independently built or released. |
+| Environment | A named deployment and runtime environment; identify its scope and configuration. |
+| Host | An optional environment access host. A cluster access host does not prove where an application process ran. |
+| Service | A Component's named runtime presence in an Environment; resolve the deployed revision independently. |
+| Workload | A named platform carrier declared by a Service; discover its actual instances and state at execution time. |
+| Operation | A named capability exposed by a Service; protocol details belong to its adapter and access configuration. |
+
+A logical Service may use several Workloads. Neither a declared Workload nor a configured endpoint
+proves readiness, and a logical Service is not necessarily a Kubernetes Service resource. Bind
+evidence to the relevant service, workload instances, and time instead of inferring identity from
+an address or display label.
+
+The **target** is the subject selected for the task. For live testing, identify its Service,
+Environment, revision, and scope; for offline analysis, identify the recorded source and cohort.
+Record the quality command's execution location and connection path as run conditions. Moving the
+test process or changing its connection need not change Environment identity, but changes the
+conditions under which results can be compared. See [environment preparation](references/environment.md).
+
+## Intent and execution facts
+
+A **Case** is reusable test intent with stable identity. Canonical Case assets belong to spec-case
+when the project uses it; profiles select Cases and experiment-local weights without rewriting
+their inputs or expected behavior. An **Experiment** names reproducible verification intent.
+
+```text
+ExperimentRun
+  → Execution
+      → OperationRun
+          → Outcome
+
+Reducer(recorded run facts) → Artifact → Report / Verdict
+```
+
+An ExperimentRun is one actual execution. Each domain owns its grouping and lifecycle: E2E can use
+CaseRun, while perf uses ArmRun for one resource/load configuration. An OperationRun records one
+real service invocation and owns its raw Outcome. A multistep Case may produce several calls; a
+perf Case can be selected repeatedly. Keep configuration identity, execution identity, and call
+identity distinct when joining evidence.
+
+A **Reducer** derives **Artifacts** from recorded facts without calling the subject again. A
+**Report** renders those artifacts. Inspect native run IDs, call IDs, manifests, and raw records;
+do not reconstruct identity from report labels. Analysis of existing traces or trajectories does
+not require inventing an Experiment, Case, or service call.
+
+## Evidence and evaluation
+
+| Concept | Semantic role |
+|---|---|
+| Observation | What execution or collection actually observed, with source identity and provenance. Outcome and recorded trajectory data are examples. |
+| Unit | The domain's addressable evaluation grain, such as a request, window, Case, or trajectory. |
+| Annotation | Supervision already available for evaluation, such as a human label or reference, with producer and provenance. |
+| Dataset | Reusable, versioned Unit facts and their Case, Observation, and Annotation relationships. |
+| EvaluationRun | One evaluation of those facts under selected components, versions, configuration, and policy. |
+| Finding | An evidenced pattern or anomaly; it may motivate investigation but is not a quality verdict or proven cause. |
+| Measurement | A factual value derived from evidence, such as latency, tokens, or resource use. |
+| Evaluation | A judgment against an explicit criterion, produced by a Judge, Verifier, assertion, or other native evaluator. |
+| Worksheet | The evaluation's rows of Unit facts and results, including missing or errored cells. This is a semantic view, not a required file format. |
+| Verdict | The run-level, machine-consumable decision under the declared policy. |
+
+Preserve the source facts when judgment fails. Missing evaluation is not an observed product
+failure. Read execution health and result coverage before interpreting scores or aggregates; a
+Finding or Measurement affects a gate only through an explicit judgment or policy.
+
+Keep one grain and stable key per analysis table. Request, window, and run aggregates answer
+different questions. Use native artifacts when available rather than inventing Dataset,
+EvaluationRun, or Worksheet files that the project does not produce.
+
+## Reuse and comparison
+
+Record subject or generator revision, evidence identity/version, and evaluation configuration
+separately. Changing source facts, Cases, or annotations changes the dataset. Changing judgment
+rules or analysis configuration can reuse the same facts in a distinct evaluation when the native
+capability supports it. Rendering a report neither recollects evidence nor reruns judgment.
+
+Comparing subject behavior requires separate executions with aligned inputs and controlled run
+conditions. Comparing judgment components requires fixed source evidence. Identify unmatched
+factors, missing observations, and coverage denominators before attributing differences to a
+revision. Domain skills define the remaining comparability requirements.
+
+## Capability, health, and decision
+
+Keep three questions separate:
+
+1. **Can this task run?** `ready` means its selected action has the necessary capability and inputs;
+   `blocked` means a prerequisite is unavailable; `no_capability` means no usable project-owned
+   entrypoint or sufficient evidence exists for the requested action. Offline analysis can be ready
+   without a live target; live execution requires verified application connectivity.
+2. **Did it execute correctly?** Preserve errors, cancellations, missing observations, partial
+   evaluation coverage, and cleanup failures. Configured components may not have executed.
+3. **What passed?** Preserve native verdict states and their scope. Skipped or missing judgments
+   are not passes; analysis without a gate policy does not prove release readiness. Passing
+   assertions or SLOs do not erase an execution or cleanup error.
+
+Report the decision with its subject and provenance, realized conditions, command or evidence
+source, coverage, native result, and artifact paths. Keep run-specific facts and reusable project
+operating knowledge beside the project's assets; keep credentials, private data, and volatile
+environment details out of the plugin.

quality/README.md

@@ -13,55 +13,36 @@ The bundled skills currently cover three independent quality views:
 - `trajectory` evaluates agent decisions and actions, compares effect and cost, finds the next
   evidence-backed problem, and organizes controlled tuning experiments.
 
-Each skill connects three layers without merging their ownership:
-
-1. a framework such as case-harness may provide reusable execution, load, evaluation, measurement,
-   artifact, and reporting primitives;
-2. each project owns its real cases, workloads, profiles, recordings, adapters, labels, Evaluators,
-   Measurers, acceptance criteria, and canonical entrypoints;
-3. the skill discovers and operates that project capability, interprets its evidence, helps evolve
-   project-owned assets when requested, and preserves project-specific knowledge beside them.
-
-During assessment, if no runnable project-owned capability exists, a skill returns `no_capability`
-rather than inventing tests or evaluations, or presenting source review as execution evidence.
-Explicit coverage work may evolve an existing project-owned capability; it does not make an absent
-suite look executable.
+The project owns the tests, profiles, recordings, adapters, and judgment criteria. A framework
+such as quality-harness supplies execution and analysis mechanisms; these skills discover and
+operate the project's canonical entrypoints, interpret evidence, and preserve useful operating
+knowledge beside the project assets.
 
 ## Operating model
 
-The skills share a small quality loop while preserving each domain's native semantics:
+The skills share [Quality concepts](CONCEPTS.md): subject and environment identity, execution
+facts, evidence and evaluation, comparison, and the distinction between capability, execution
+health, and quality decisions. Each skill retains its domain's lifecycle and judgment rules.
 
 ```text
-understand the target and runner path
-  → discover project-owned capability
-  → gate on executability
-  → run the canonical entrypoint
-  → interpret native evidence
-  → report conclusions and unknowns
-  → retain reusable operating knowledge
+identify the question and subject
+  → discover a project capability or sufficient recorded evidence
+  → prepare live execution or select existing evidence
+  → use the canonical entrypoint
+  → interpret results and coverage
+  → report the conclusion and next supported action
 ```
 
-E2E and performance execution share one target-confirmation boundary: identify the system under
-test and revision, decide whether it is local or remote, locate the runner, and verify the
-application data-plane path between them. Kubernetes API access or a configured endpoint is not by
-itself target readiness. Each skill then adds its own preparation: E2E prepares cases, fixtures,
-and scenario controls; performance additionally prepares the resource profile, load generator,
-dependency capacity, observations, safety limits, and cooldown.
-
-Execution facts, judgments, and missing evidence remain distinct. A failed assertion is not a
-runner error; an unavailable capability is not a pass; a useful analysis is not automatically a
-release verdict. Skills may organize evidence and propose the next experiment, but they do not
-claim causality or mutate the evaluated system unless the user asks.
-
-## Skills first, orchestration later
-
-Quality intentionally starts at the skill layer. E2E, performance, trajectory, and other quality
-views should first mature as independent operators with clear inputs, evidence, outcomes, and
-ownership. This keeps real project workflows visible while their common shape is still emerging.
+Live E2E and performance runs follow [environment preparation](references/environment.md): select
+the target and revision, locate the test process, verify application connectivity, prepare
+conditions, and retain cleanup evidence. Offline analysis reuses recorded facts without requiring
+a live target. No usable capability or sufficient evidence is reported as `no_capability`;
+an unavailable prerequisite is `blocked`.
 
-Only after several skills demonstrate stable contracts and repeated composition needs might an
-agent- or orchestration-level Quality Harness coordinate them. That is a future consumer of these
-skills, not a dependency or implementation goal of this plugin today.
+Execution facts and judgment remain separate. A passed assertion or SLO covers only its realized
+conditions; missing observations, skipped checks, and execution errors remain visible. Skills
+can propose the next experiment or improve project-owned assets when requested. They neither
+invent a missing suite nor supply cross-skill execution orchestration.
 
 ## Install
 
@@ -101,7 +82,7 @@ For this high-token trajectory problem, identify likely causes and controlled ex
 ```
 
 The skills operate existing project-owned quality assets. Assessment does not invent missing tests,
-workloads, profiles, recordings, labels, or evaluators. When the user asks to grow coverage, changes
+load profiles, recordings, labels, or judgment components. When the user asks to grow coverage, changes
 remain in the project-owned capability and move toward broader coverage incrementally. The skills do
 not deploy environments without authorization, modify agent behavior unless asked, or turn
 unavailable coverage into a pass.