Unify tool language across docs and code (#30)

Author: V3RON

AGENTS.md

@@ -0,0 +1,6 @@
+## Naming
+
+Follow `DICTIONARY.md`.
+
+- Reuse existing dictionary terms in code, docs, tests, and CLI text.
+- Before introducing a new name, check `DICTIONARY.md` and ask the user for approval.

CHANGELOG.md

@@ -6,15 +6,15 @@
 
 - [#19](https://github.com/callstackincubator/skillgym/pull/19) [`ae5aed5`](https://github.com/callstackincubator/skillgym/commit/ae5aed524592b954be6225d4d47d16e3bbcd35f4) Thanks [@V3RON](https://github.com/V3RON)! - Classify assertion failures (for example timeouts vs expectation mismatches) and show the kind in standard, JSON summary, and GitHub Actions output.
 
-- [#20](https://github.com/callstackincubator/skillgym/pull/20) [`39393cc`](https://github.com/callstackincubator/skillgym/commit/39393cc07cb22ce713e35f9fc2dd86b56a4ffa19) Thanks [@V3RON](https://github.com/V3RON)! - Add soft assertions so a test case can record multiple failures and report them together instead of stopping at the first one.
+- [#20](https://github.com/callstackincubator/skillgym/pull/20) [`39393cc`](https://github.com/callstackincubator/skillgym/commit/39393cc07cb22ce713e35f9fc2dd86b56a4ffa19) Thanks [@V3RON](https://github.com/V3RON)! - Add soft assertions so a case can record multiple failures and report them together instead of stopping at the first one.
 
 ## 0.6.0
 
 ### Minor Changes
 
 - [#10](https://github.com/callstackincubator/skillgym/pull/10) [`adb3708`](https://github.com/callstackincubator/skillgym/commit/adb3708a8cb234b79f3acd6356c6f249736363ea) Thanks [@V3RON](https://github.com/V3RON)! - You can now mark known failures so expected problems do not block a run.
 
-- [`ff92fea`](https://github.com/callstackincubator/skillgym/commit/ff92fea9a4c316729ecb4e21ba2b3909e9ff82f1) Thanks [@V3RON](https://github.com/V3RON)! - You can now filter benchmark runs by tag.
+- [`ff92fea`](https://github.com/callstackincubator/skillgym/commit/ff92fea9a4c316729ecb4e21ba2b3909e9ff82f1) Thanks [@V3RON](https://github.com/V3RON)! - You can now filter benchmark executions by tag.
 
 - [`ff92fea`](https://github.com/callstackincubator/skillgym/commit/ff92fea9a4c316729ecb4e21ba2b3909e9ff82f1) Thanks [@V3RON](https://github.com/V3RON)! - Asserting on commands is now easier and more reliable.
 
@@ -28,4 +28,4 @@
 
 - [`ff92fea`](https://github.com/callstackincubator/skillgym/commit/ff92fea9a4c316729ecb4e21ba2b3909e9ff82f1) Thanks [@V3RON](https://github.com/V3RON)! - Benchmark suites now use available CPU capacity more efficiently.
 
-- [`ff92fea`](https://github.com/callstackincubator/skillgym/commit/ff92fea9a4c316729ecb4e21ba2b3909e9ff82f1) Thanks [@V3RON](https://github.com/V3RON)! - The basic example now includes the latest max-steps scenario.
+- [`ff92fea`](https://github.com/callstackincubator/skillgym/commit/ff92fea9a4c316729ecb4e21ba2b3909e9ff82f1) Thanks [@V3RON](https://github.com/V3RON)! - The basic example now includes the latest max-steps case.

DICTIONARY.md

@@ -0,0 +1,41 @@
+# SkillGym Dictionary
+
+This is the domain dictionary for `skillgym`.
+
+Use the existing vocabulary in code, docs, tests, issues, and conversations.
+Prefer reusing an existing term over inventing a new one.
+Before adding or changing a term, check this file and ask the user for approval.
+
+## Terms
+
+- `SkillGym`: The product, package, CLI, and repository.
+- `suite file`: Module file that exports one suite.
+- `suite`: User-authored collection of cases and optional workspace config.
+- `case`: One definition with a prompt, assertions, and optional metadata.
+- `prompt`: Exact instruction sent to the agent.
+- `runner`: Configured execution target: agent type plus model.
+- `agent`: External coding agent doing the work.
+- `suite run`: One top-level `skillgym run ...` over one suite.
+- `execution`: One case x runner unit of work, including all its repetitions and retries.
+- `repetition`: One planned sample within an execution.
+- `retry`: Rerunning the same repetition after failure.
+- `session`: One concrete agent interaction; not a synonym for `repetition`.
+- `session report`: Normalized record of a completed session, exposed to assertions.
+- `assertion`: Rule deciding whether a case passed or failed.
+- `expected failure`: Assertion failure treated as suite-successful because it captures a known gap.
+- `failure classification`: Stable category assigned to a failure.
+- `failure class`: The value representing a failure classification.
+- `result`: Pass/fail outcome object; not a session report.
+- `artifact`: Preserved file or directory written by SkillGym.
+- `artifact directory`: Directory holding artifacts for one scope such as a suite run, execution, repetition, retry, or session.
+- `workspace`: Directory where the agent runs.
+- `shared workspace`: Run directly in one real directory.
+- `isolated workspace`: Fresh workspace created per execution.
+- `workspace template`: Directory copied into an isolated workspace before execution.
+- `workspace bootstrap`: Command run in an isolated workspace before the agent starts.
+- `schedule`: Execution ordering and concurrency policy.
+- `reporter`: Component rendering suite-run progress and results.
+- `skill detection`: Evidence that a skill was used, with confidence and evidence.
+- `session event`: Normalized event observed during a session.
+- `snapshot baseline`: Stored token baseline for a benchmark case x runner pair.
+- `token regression check`: Comparison of current token usage against the snapshot baseline.

README.md

@@ -8,7 +8,7 @@
 
 ## Why it's useful
 
-When you evaluate agent skills manually, it is hard to tell whether the agent actually selected the right skill, used it at the right time, and behaved correctly end to end. `skillgym` gives you a repeatable way to run real sessions, preserve session artifacts, verify outcomes with TypeScript assertions, and catch token regressions with snapshots.
+When you evaluate agent skills manually, it is hard to tell whether the agent actually selected the right skill, used it at the right time, and behaved correctly end to end. `skillgym` gives you a repeatable way to run real sessions, preserve session artifacts, verify results with TypeScript assertions, and catch token regressions with snapshots.
 
 ## Supported runners
 
@@ -75,10 +75,10 @@ export default config;
 Create a suite file such as `./skillgym/basic-suite.ts`:
 
 ```ts
-import type { TestSuite } from "skillgym";
+import type { Suite } from "skillgym";
 import { assert } from "skillgym";
 
-const suite: TestSuite = [
+const suite: Suite = [
   {
     id: "always-passes",
     prompt: "Say only: skillgym ready",
@@ -113,7 +113,7 @@ npx skillgym skills list
 npx skillgym skills get core
 ```
 
-Explain a failed run by resuming the original runner session from the exact failed leaf artifact directory:
+Explain a failed execution by resuming the original runner session from the exact failed artifact directory:
 
 ```bash
 npx skillgym explain ./.skillgym-results/run-1/case-a/open-main/repeat-1
@@ -137,7 +137,7 @@ TypeScript runtime limitations:
 - a `skillgym.config.*` file with a non-empty `runners` map
 - at least one configured runner with `agent.type` and `agent.model`
 - the corresponding CLI installed and working in your environment
-- a suite file that exports test cases
+- a suite file that exports cases
 
 Config is discovered upward from the suite file directory. CLI flags override config values.
 
@@ -148,21 +148,21 @@ Use `agent.model` instead of `commandArgs` when you need to select the agent mod
 
 A runner is one configured agent target. It tells `skillgym` which CLI to launch and which model to use for a run.
 
-Each test case runs once per selected runner. For example, 3 cases and 2 runners produce 6 executions.
+Each case runs once per selected runner. For example, 3 cases and 2 runners produce 6 executions.
 
 ## Configuration
 
 Most important config properties:
 
-- `run.cwd`: working directory used for shared-workspace runs
-- `run.outputDir`: where artifacts, reports, and preserved workspaces are written
+- `run.cwd`: working directory used for shared-workspace executions
+- `run.outputDir`: suite-run artifact directory where artifacts, reports, and preserved workspaces are written
 - `run.reporter`: built-in `standard` reporter or a custom reporter module path
 - `run.schedule`: execution scheduling mode for case x runner pairs
 - `run.maxParallel`: maximum concurrent executions for non-serial schedules, defaulting to available CPU parallelism
 - `run.repeat`: require this many successful repetitions per case x runner execution
-- `run.repeatFailure`: retry the current repetition up to this many additional attempts after failure
+- `run.repeatFailure`: retry the current repetition up to this many additional sessions after failure
 - `run.retryFailed`: compatibility alias for `run.repeatFailure`
-- `run.maxSteps`: best-effort limit on streamed agent steps before skillgym terminates the run
+- `run.maxSteps`: best-effort limit on streamed agent steps before skillgym terminates the execution
 - `run.workspace`: default workspace mode for the suite
 - `defaults.timeoutMs`: default per-case timeout
 - `runners.<id>.agent.type`: which agent integration to use, currently `opencode`, `codex`, `claude-code`, or `cursor-agent`
@@ -181,15 +181,15 @@ The execution unit is one case x runner pair. `skillgym` expands the suite into
 
 For concurrent schedules, `run.maxParallel` defaults to `os.availableParallelism()`. This limits how many SkillGym executions are active at once; it does not pin or limit CPU cores used by an individual agent process.
 
-Concurrent schedules do not copy or isolate the workspace by themselves. Overlapping runs may still interact through the same filesystem state and live runner output unless you use isolated workspaces. OpenCode, Codex, and Claude Code runtime state are isolated per run under each artifact directory.
+Concurrent schedules do not copy or isolate the workspace by themselves. Overlapping executions may still interact through the same filesystem state and live runner output unless you use isolated workspaces. OpenCode, Codex, and Claude Code runtime state are isolated per execution under each artifact directory.
 
-`run.repeat` is useful when you want stability sampling instead of a single lucky pass. Each case x runner execution keeps running until it records the requested number of successful classified outcomes, or stops early when one repetition still fails after exhausting `run.repeatFailure` retries.
+`run.repeat` is useful when you want stability sampling instead of a single lucky pass. Each case x runner execution keeps running until it records the requested number of successful classified results, or stops early when one repetition still fails after exhausting `run.repeatFailure` retries.
 
-`run.repeatFailure` retries only the current repetition when it still counts as failed after result classification. SkillGym keeps all repetition and retry artifacts, averages visible duration and token metrics across the final outcomes of completed successful repetitions, and preserves the full nested detail in `results.json`.
+`run.repeatFailure` retries only the current repetition when it still counts as failed after result classification. SkillGym keeps all repetition and retry artifacts, averages visible duration and token metrics across the final results of completed successful repetitions, and preserves the full nested detail in `results.json`.
 
-Artifacts for repeated runs are grouped under the stable case x runner directory using `repeat-N` directories, with retry attempts nested as `attempt-N` inside the repetition that needed recovery.
+Artifacts for repeated executions are grouped under the stable case x runner directory using `repeat-N` directories, with retry sessions nested as `session-N` inside the repetition that needed recovery.
 
-`run.maxSteps` is enforced on a best-effort basis by monitoring each runner's streamed JSONL output. A step is one observed model round, not one token and not necessarily one tool call, but the exact boundary is still runner-defined, so the same prompt may consume different numbers of steps across agents. When the observed step count exceeds the configured limit, skillgym kills the agent process, fails the run with origin `max-steps`, and preserves raw stdout/stderr artifacts for debugging. No partial normalized report is produced for that failure.
+`run.maxSteps` is enforced on a best-effort basis by monitoring each runner's streamed JSONL output. A step is one observed model round, not one token and not necessarily one tool call, but the exact boundary is still runner-defined, so the same prompt may consume different numbers of steps across agents. When the observed step count exceeds the configured limit, skillgym kills the agent process, fails the execution with origin `max-steps`, and preserves raw stdout/stderr artifacts for debugging. No partial session report is produced for that failure.
 
 ## Workspaces
 
@@ -200,7 +200,7 @@ A workspace is the directory where an execution runs.
 - `shared`: run directly in one real directory
 - `isolated`: create a fresh temporary workspace per case x runner execution
 
-Use `shared` when you want the agent to work against your real project checkout. Use `isolated` when you want clean filesystem state per execution or need to prepare each run from a template.
+Use `shared` when you want the agent to work against your real project checkout. Use `isolated` when you want clean filesystem state per execution or need to prepare each execution from a template.
 
 You can configure workspaces in `skillgym.config.*` with `run.workspace`, or per suite with a named `workspace` export. Suite-level workspace config overrides config-level `run.workspace`.
 
@@ -217,15 +217,15 @@ export const workspace = {
 };
 ```
 
-In isolated mode, each execution gets its own workspace. `templateDir` copies a starter project into that workspace, and `bootstrap` runs before the agent starts. Successful isolated runs are cleaned up; failed ones are preserved under `outputDir/workspaces` for debugging.
+In isolated mode, each execution gets its own workspace. `templateDir` copies a starter project into that workspace, and `bootstrap` runs before the agent starts. Successful isolated executions are cleaned up; failed ones are preserved under `outputDir/workspaces` for debugging.
 
 See [Workspaces](docs/workspaces.md) for the full workspace reference.
 
 ## Assertions
 
 `assert` extends Node's `node:assert/strict` helpers, so standard methods like `assert.ok`, `assert.equal`, and `assert.match` still work.
 
-`assert.soft.*` mirrors the same sync assertion surface and collects failures until the current test case finishes, so one run can report multiple assertion mismatches together.
+`assert.soft.*` mirrors the same sync assertion surface and collects failures until the current case finishes, so one execution can report multiple assertion mismatches together.
 
 Built-in grouped assertions cover:
 
@@ -269,16 +269,16 @@ assert.fileReads.includes(report, /SKILL\.md$/, {
 });
 ```
 
-When at least one explainable assertion fails, skillgym writes `explain.json` into the failed leaf artifact directory. Running `skillgym explain <artifactDir>` resumes the original runner session, asks each persisted question, and writes `explanations.json` with the answers.
+When at least one explainable assertion fails, skillgym writes `explain.json` into the failed artifact directory. Running `skillgym explain <artifactDir>` resumes the original runner session, asks each persisted question, and writes `explanations.json` with the answers.
 
-For historical isolated-workspace runs, deferred explain currently depends on the recorded workspace still being resumable by the underlying runner.
+For historical isolated-workspace executions, deferred explain currently depends on the recorded workspace still being resumable by the underlying runner.
 
 See the [assertion reference](docs/assertions.md).
 See [Deferred Explain](docs/explain.md).
 
 ## Snapshots
 
-Snapshot checks can fail runs when token usage regresses beyond a configured tolerance.
+Snapshot checks can fail executions when token usage regresses beyond a configured tolerance.
 
 ```bash
 npx skillgym run ./examples/basic-suite.ts --update-snapshots
@@ -294,7 +294,7 @@ The [skill selection suite](examples/skill-selection-suite.ts) targets a real in
 npx skillgym run ./examples/skill-selection-suite.ts
 ```
 
-The [workspace isolation suite](examples/workspace-isolation-suite.ts) demonstrates isolated workspace setup with a template directory and bootstrap command:
+The [workspace isolation suite](examples/workspace-isolation-suite.ts) demonstrates an isolated workspace with a template directory and bootstrap command:
 
 ```bash
 npx skillgym run ./examples/workspace-isolation-suite.ts
@@ -311,7 +311,7 @@ npx skillgym run ./examples/failure-classification-suite.ts
 The documentation site is at [incubator.callstack.com/skillgym](https://incubator.callstack.com/skillgym/). Repository docs:
 
 - [Docs Overview](docs/readme.md)
-- [Test Cases](docs/test-cases.md)
+- [Test Cases](docs/cases.md)
 - [Assertions](docs/assertions.md)
 - [Workspaces](docs/workspaces.md)
 - [Reporters](docs/reporters.md)

docs/assertions.md

@@ -21,7 +21,7 @@ assert.classify("missing-flag", () => {
 
 ## Failure classification
 
-Use `assert.classify(...)` when you want an assertion failure to carry a stable structured class that reporters can group across runs.
+Use `assert.classify(...)` when you want an assertion failure to carry a stable structured class that reporters can group across executions.
 
 ```ts
 assert.classify({ id: "wrong-cli-alias", label: "Wrong CLI alias" }, () => {
@@ -51,7 +51,7 @@ Rules:
 `assert.soft` mirrors the sync assertion methods on the root `assert` export and the grouped SkillGym helpers.
 
 - soft failures are collected in execution order
-- the runner throws a single `AssertionError` after `testCase.assert(report, ctx)` completes
+- the runner throws a single `AssertionError` after `case_.assert(report, ctx)` completes
 - if a hard `AssertionError` is thrown after soft failures were collected, the final failure includes both
 - `assert.soft.rejects(...)` and `assert.soft.doesNotReject(...)` remain hard assertions in the first implementation
 
@@ -116,7 +116,7 @@ Grouped assertions can attach a follow-up question that `skillgym` persists when
 
 - `explain.question` can be a fixed string
 - or a callback that renders a question from the failing assertion context
-- questions are persisted only for failed runs
+- questions are persisted only for failed executions
 - unsupported assertions are skipped unless you provide a custom `explain.question`
 
 Example:
@@ -130,7 +130,7 @@ assert.fileReads.includes(report, /SKILL\.md$/, {
 });
 ```
 
-When at least one explainable assertion fails, `skillgym` writes `explain.json` into the failed leaf artifact directory. You can later resume the original runner session with `skillgym explain <artifactDir>`.
+When at least one explainable assertion fails, `skillgym` writes `explain.json` into the failed artifact directory. You can later resume the original runner session with `skillgym explain <artifactDir>`.
 
 ## Skills
 
@@ -350,5 +350,5 @@ assert.output.notEmpty(report);
 
 ## Related docs
 
-- `test-cases.md`
+- `cases.md`
 - `session-report.md`