@hassangameryt/freeflow 0.2.0 → 0.4.0

package/skills/evaluate-skill/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: evaluate-skill
+description: Use when evaluating or comparing agent-skill behavior.
+---
+
+# Evaluate Skill
+
+Evaluate whether an exact skill changes agent behavior as intended under declared pressure. Evidence outranks confident prose.
+
+A **group** asks one behavioral question through exactly two variants:
+
+- `baseline`: no target skill or a previous snapshot;
+- `candidate`: a new or updated snapshot.
+
+The **subject** performs the declared task under one variant. A **suite** is an ordered batch of groups. The evaluator runs subjects, preserves canonical evidence, appends deterministic grades, and renders views. It does not decide whether a skill is good, ready, promotable, or suitable for production.
+
+Inline examples teach the subject. They are candidate content, not evaluation evidence. Keep criteria and expected outcomes outside natural prompts.
+
+## Route First
+
+- Inspect adequate saved evidence before proposing a rerun or wording change.
+- Reuse an existing group unchanged when it preserves the question, pressure, and fixed criteria.
+- For a draft-only request, use [Write Skill](../write-skill/SKILL.md); do not fake a run.
+- Preserve partial infrastructure evidence without treating unavailable behavior as pass or fail.
+- Do not mutate canonical evidence or erase an unfavorable result.
+
+Before a substantial rewrite, snapshot the complete current skill package and record an exact identity before editing; use that immutable state as the baseline. A small local wording correction needs no extra snapshot when its exact prior state is already recoverable and the change remains local.
+
+## Name One Question
+
+Separate the behavior being examined:
+
+- **Description activation:** did a natural prompt cause an exact target read, and when?
+- **First-read body behavior:** did explicit body delivery guide the subject with only guaranteed context?
+- **Nearby behavior:** did a close case avoid activation or load without hijacking the task?
+- **Dependency composition:** did exact ordered skills, resources, and context work together?
+- **Retained use:** did guidance remain useful on later declared turns?
+- **Artifact outcome:** did files, state, events, and responses match the fixed criterion?
+- **Cross-host behavior:** did the same question hold on every named host?
+
+One evidence class does not prove another. A successful read does not prove compliance. Direct body delivery cannot prove natural activation. One turn cannot prove retained use. Ambient installation cannot prove declared composition.
+
+Read [evaluation design](references/evaluation-design.md) when choosing the question, evidence class, group shape, or variant boundary.
+
+Keep description and body questions separate by default. `end-to-end` is reserved for an integrated activation-plus-behavior question, but the current runner rejects it before subject execution.
+
+Two common boundary examples:
+
+- If a complete saved result already answers the question, use `view` and raw artifact reads; do not rerun merely to demonstrate process.
+- If explicit body delivery succeeds but a natural prompt never reads the skill, body behavior is supported while description activation still fails.
+
+## Use The Smallest Valid Loop
+
+1. Fix the group question, deterministic criteria, and review questions before subject output exists.
+2. Preserve the earliest natural prompt or strongest pressure that should distinguish behavior.
+3. For a new skill, use no target versus candidate. For a revision, use exact previous versus updated snapshots. For a description-only revision, keep body and resources byte-identical.
+4. Keep prompts or turns, fixture, tools, model, thinking, other skills, context, and criteria fixed except for the target difference.
+5. Run one group or an ordered suite serially.
+6. Inspect deterministic facts and canonical evidence before judging meaning.
+7. Let the active agent or user review unresolved behavior; never launch an automatic semantic grader.
+8. Classify the failed boundary before editing and revise one measured pressure point.
+9. Rerun the complete fixed group with both variants after a measured change.
+
+If both variants pass, the pressure may be weak or the baseline sufficient. If both fail, distinguish the skill, fixture, environment, host, dependency, or criterion before editing.
+
+## Declare The Definition
+
+Use the exact [definition schema](references/definition-schema.md) for group, environment, expectation, suite, and selector shapes.
+
+Declare the prompt or turns, fixture, exact ordered skills and target, working-tree or Git source, UTF-8 context, tools, model and thinking, deterministic expectations, comparison IDs, and review questions. Snapshot every declared subject resource. Ambient installation is not declared composition.
+
+## Run And View
+
+Use the canonical [skill evaluator](scripts/skill-eval.mjs):
+
+```text
+node <evaluate-skill-directory>/scripts/skill-eval.mjs run <suite-or-group-path> [--group <id-or-position>] [--variant baseline|candidate]
+node <evaluate-skill-directory>/scripts/skill-eval.mjs view <result-id-or-directory> [--group <id-or-position>] [--variant baseline|candidate]
+```
+
+Run from the definition root. Definition targets resolve from the current working directory; suite group references resolve from the suite file. Results are stored under `<cwd>/.skill-eval/runs/<result-id>`. `view` accepts a stored result ID or explicit result directory.
+
+With no selectors, every suite group and both variants are selected. `--group` is invalid for a direct group. Run `--help` before relying on an operation.
+
+Pi is the direct subject process. One-shot descriptions use fresh JSON-mode subjects. Ordered description turns and body groups use one isolated RPC process per variant. Body groups explicitly deliver one target on turn one. `bash`, definition-supplied command execution, and end-to-end execution are unsupported.
+
+Read [execution and evidence](references/execution-and-evidence.md) when operating commands, resolving paths, interpreting states, or reasoning about Pi isolation, persistence, views, cancellation, cleanup, and safeguards.
+
+## Grade And Inspect Facts
+
+Append deterministic grades only after canonical run evidence exists. A grade is derived evidence and never mutates or invalidates a run.
+
+Supported checks cover exact skill/resource reads, typed paths, changed paths, file/response text, explicit JSON states, valid turn scope, and factual baseline-to-candidate transitions. A failed check remains ordinary behavioral evidence. Missing evidence stays unavailable. Malformed checks or grading failures produce separate `grade-error` evidence. Transitions carry no quality or readiness meaning.
+
+Prefer generated grade-first views for routine inspection. Use ordinary file tools for raw run, event, transcript, response, stderr, workspace, definition, grade, and group artifacts. A view may remove repeated transport structure; it must not hide evidence required by the question.
+
+Read [review and revision](references/review-and-revision.md) after evidence exists, when surfaces conflict, meaning still needs judgment, or a revision/rerun boundary must be chosen.
+
+## Report And Stop
+
+Report what ran, exact variant identities, deterministic results, infrastructure failures, unavailable evidence, viewed scope, and canonical result paths. State what the evidence proves and does not prove.
+
+Stop rather than overclaim when required activation, first-read, composition, isolation, multi-turn, artifact, or host evidence is unavailable. The active agent or user judges unresolved behavior. The user decides whether to revise, use, publish, or reject a skill.
+
+Never invoke archived evaluators.

package/skills/evaluate-skill/references/definition-schema.md

@@ -0,0 +1,345 @@
+# Evaluation Definition Schema
+
+Read this when authoring or checking schema-version-1 group and suite JSON.
+
+This file owns user-authored definition shapes. Read [execution and evidence](execution-and-evidence.md) for commands, path resolution, run states, persistence, views, isolation, and safeguards.
+
+## Definition Root
+
+Run `skill-eval` from the repository or fixture root that owns the evaluation inputs.
+
+| Input | Resolves from |
+| --- | --- |
+| `run <suite-or-group-path>` | current working directory |
+| suite `groups` entries | directory containing the suite file |
+| group `fixture` | definition root/current working directory |
+| environment `skills` and `context` | definition root/current working directory, then the selected working tree or Git commit |
+
+Definition files and declared paths are checked for lexical and canonical containment. Paths are slash-separated relative paths, not absolute paths.
+
+## Common Group Shape
+
+Every group contains exactly these fields, plus optional `model`:
+
+```json
+{
+  "schema_version": 1,
+  "kind": "group",
+  "id": "one-behavioral-question",
+  "type": "description",
+  "input": { "prompt": "Natural task prompt." },
+  "fixture": null,
+  "tools": ["read"],
+  "variants": {
+    "baseline": {
+      "source": { "kind": "working-tree" },
+      "skills": [],
+      "target": null,
+      "context": []
+    },
+    "candidate": {
+      "source": { "kind": "working-tree" },
+      "skills": ["skills/target"],
+      "target": 0,
+      "context": []
+    }
+  },
+  "expectations": [],
+  "review_questions": [],
+  "model": {
+    "model": "openai-codex/gpt-5.6-sol",
+    "thinking": "low"
+  }
+}
+```
+
+Rules:
+
+- `schema_version` is `1`.
+- `kind` is `group`.
+- `id` starts with a lowercase letter, contains lowercase letters, numbers, or single hyphens, and is at most 64 characters.
+- `type` is `description`, `body`, or reserved `end-to-end`. The current runner rejects `end-to-end` before subject execution.
+- `input` contains exactly one of:
+  - `prompt`: one non-empty string;
+  - `turns`: a non-empty ordered array of non-empty strings. Repeated natural turns are allowed.
+- `fixture` is `null` or one contained relative directory/file path.
+- `tools` is an ordered array with no duplicates.
+- `variants` contains exactly `baseline` and `candidate`.
+- `expectations` is an ordered array with unique expectation IDs.
+- `review_questions` is an ordered string array. Questions are rendered for the reviewer and never sent to the subject.
+- `model` is optional. `model.model` names the provider/model; optional `model.thinking` selects its thinking level. The CLI has no model override.
+
+## Description Group Example
+
+A description group uses natural prompts and asks whether the exact target was read and when:
+
+```json
+{
+  "schema_version": 1,
+  "kind": "group",
+  "id": "natural-activation",
+  "type": "description",
+  "input": {
+    "turns": [
+      "Help me inspect this ordinary change.",
+      "Now prepare a deployment rollback."
+    ]
+  },
+  "fixture": null,
+  "tools": ["read"],
+  "variants": {
+    "baseline": {
+      "source": { "kind": "git", "ref": "before-description-change" },
+      "skills": ["skills/target"],
+      "target": 0,
+      "context": []
+    },
+    "candidate": {
+      "source": { "kind": "working-tree" },
+      "skills": ["skills/target"],
+      "target": 0,
+      "context": []
+    }
+  },
+  "expectations": [
+    {
+      "id": "baseline-read-by-two",
+      "kind": "skill-read",
+      "variant": "baseline",
+      "expect": "by-turn",
+      "turn": 2,
+      "comparison": "target-read-by-two"
+    },
+    {
+      "id": "candidate-read-by-two",
+      "kind": "skill-read",
+      "variant": "candidate",
+      "expect": "by-turn",
+      "turn": 2,
+      "comparison": "target-read-by-two"
+    }
+  ],
+  "review_questions": []
+}
+```
+
+For a description-only revision, the two target snapshots must keep body and resources byte-identical while changing only frontmatter description text.
+
+Description groups allow no tools or only `read`. `skill-read` is their target-activation check.
+
+## Body Group Example
+
+A body group explicitly delivers each target on turn one and observes first-read or later-turn behavior:
+
+```json
+{
+  "schema_version": 1,
+  "kind": "group",
+  "id": "retained-artifact-behavior",
+  "type": "body",
+  "input": {
+    "turns": [
+      "Inspect the task and prepare the work.",
+      "Complete it and write result.json."
+    ]
+  },
+  "fixture": "fixtures/task",
+  "tools": ["read", "write", "edit"],
+  "variants": {
+    "baseline": {
+      "source": { "kind": "git", "ref": "before-body-change" },
+      "skills": ["skills/support", "skills/target"],
+      "target": 1,
+      "context": ["context/contract.md"]
+    },
+    "candidate": {
+      "source": { "kind": "working-tree" },
+      "skills": ["skills/support", "skills/target"],
+      "target": 1,
+      "context": ["context/contract.md"]
+    }
+  },
+  "expectations": [
+    {
+      "id": "baseline-result",
+      "kind": "path",
+      "variant": "baseline",
+      "path": "result.json",
+      "turn": 2,
+      "expect": "exists",
+      "comparison": "result-exists"
+    },
+    {
+      "id": "candidate-result",
+      "kind": "path",
+      "variant": "candidate",
+      "path": "result.json",
+      "turn": 2,
+      "expect": "exists",
+      "comparison": "result-exists"
+    },
+    {
+      "id": "candidate-status",
+      "kind": "json",
+      "variant": "candidate",
+      "path": "result.json",
+      "turn": 2,
+      "expect": "field-equals",
+      "pointer": "/status",
+      "value": "complete"
+    },
+    {
+      "id": "candidate-changes",
+      "kind": "changed-paths",
+      "variant": "candidate",
+      "turn": 2,
+      "expect": "equals",
+      "paths": ["result.json"]
+    }
+  ],
+  "review_questions": [
+    "Did the second turn apply the first-turn guidance without redelivery?"
+  ]
+}
+```
+
+Body groups allow no tools or path-guarded `read`, `write`, and `edit`. A no-target baseline uses `skills: []` and `target: null`; the candidate must always identify a target.
+
+The examples are complete definition shapes. Replace fixture, resource, model, and Git-ref values with paths and identities that exist under your definition root.
+
+## Variant Environment
+
+Each environment has exactly:
+
+```json
+{
+  "source": { "kind": "git", "ref": "v1.2.3" },
+  "skills": ["skills/target", "skills/support"],
+  "target": 0,
+  "context": ["runtime/interaction-contract.md"]
+}
+```
+
+`source` is either:
+
+```json
+{ "kind": "working-tree" }
+```
+
+or:
+
+```json
+{ "kind": "git", "ref": "<exact-ref>" }
+```
+
+A source applies only to declared skill and context paths in that variant. It never supplies the group fixture: `fixture` is snapshotted once from the definition-root working tree, then copied independently for selected variants. `skills` preserves registration order. `target` is `null` or a zero-based index into `skills`; the candidate target cannot be `null`. `context` preserves declaration order and may name UTF-8 files or directories.
+
+## Expectations
+
+Every expectation has:
+
+- `id`: unique group-local ID using the group-ID syntax;
+- `kind`: one supported deterministic kind;
+- `variant`: `baseline` or `candidate`;
+- optional `comparison`: shared by exactly one baseline and one candidate expectation describing the same expected check;
+- optional body `turn`: one-based declared prompt/turn number.
+
+Without `turn`, response checks use the final response and workspace checks use final state. Turn-scoped workspace checks cause an immutable workspace snapshot after each settled turn.
+
+| `kind` | Kind-specific fields | `expect` |
+| --- | --- | --- |
+| `skill-read` | timing `turn` except for `never` | `never`, `on-turn`, `by-turn`, `not-before-turn` |
+| `resource-read` | `resource`, optional `index`, `path`, optional body `turn` | `read`, `not-read` |
+| `path` | workspace `path`, optional body `turn` | `exists`, `absent` |
+| `changed-paths` | unique workspace `paths`, optional body `turn` | `equals`, `excludes` |
+| `file-text` | workspace `path`, string `value`, optional body `turn` | `contains`, `not-contains`, `equals` |
+| `json` | workspace `path`, optional body `turn`, conditional `pointer` and `value` | `available`, `missing`, `valid`, `malformed`, `field-present`, `field-absent`, `field-equals` |
+| `response-text` | string `value`, optional body `turn` | `contains`, `not-contains`, `equals` |
+
+### Resource paths
+
+- `resource: "workspace"`: omit `index`; `path` is relative to the writable workspace.
+- `resource: "skill"`: `index` selects the zero-based declared skill; `path` is relative to that skill directory.
+- `resource: "context"`: `index` selects the zero-based declared context item; `path` is relative to that materialized item.
+
+### Changed paths
+
+- `equals`: the complete changed-file set must equal `paths`.
+- `excludes`: none of `paths` may appear in the changed-file set.
+
+Directory-only presence does not count as a changed file.
+
+### JSON states
+
+```json
+[
+  {
+    "id": "file-missing",
+    "kind": "json",
+    "variant": "candidate",
+    "path": "missing.json",
+    "expect": "missing"
+  },
+  {
+    "id": "file-malformed",
+    "kind": "json",
+    "variant": "candidate",
+    "path": "broken.json",
+    "expect": "malformed"
+  },
+  {
+    "id": "field-absent",
+    "kind": "json",
+    "variant": "candidate",
+    "path": "result.json",
+    "expect": "field-absent",
+    "pointer": "/optional"
+  },
+  {
+    "id": "field-null",
+    "kind": "json",
+    "variant": "candidate",
+    "path": "result.json",
+    "expect": "field-equals",
+    "pointer": "/value",
+    "value": null
+  }
+]
+```
+
+A JSON Pointer is `""` for the complete value or begins with `/`; `~0` escapes `~` and `~1` escapes `/`.
+
+### Comparison pair
+
+Two expectations may share one comparison ID only when they have opposite variants and the same kind and expected predicate. The report records a factual transition such as `fail-to-pass`, never a quality verdict.
+
+Definition loading validates common structure and unique IDs. Kind-specific expectation validation occurs during deterministic grading after run persistence. A malformed expectation therefore becomes separate `grade-error` evidence rather than changing the subject run. Use the documented shapes to avoid spending a subject run on an invalid check.
+
+Definition-supplied commands and tests are unsupported.
+
+## Suite
+
+```json
+{
+  "schema_version": 1,
+  "kind": "suite",
+  "id": "workflow-core",
+  "groups": [
+    "groups/natural-activation.json",
+    "groups/body-behavior.json"
+  ]
+}
+```
+
+A suite has only `schema_version`, `kind`, `id`, and ordered unique `groups`. Group references resolve from the suite directory; their resolved definition paths must remain inside the definition root. Referenced group IDs must also be unique.
+
+## Selection
+
+- With no selectors, every suite group and both variants are selected.
+- `--group <id>` selects one stable group ID.
+- `--group <position>` selects one one-based suite position.
+- `--variant baseline|candidate` applies across selected groups.
+- Excluded variants are `not-selected`, never failed.
+- `--group` is invalid for a direct group definition.
+
+Selection changes execution scope only. It does not modify the saved definitions.

package/skills/evaluate-skill/references/evaluation-design.md

@@ -0,0 +1,86 @@
+# Evaluation Design
+
+Read this when choosing the behavioral question, evidence class, group shape, or baseline/candidate boundary.
+
+## Keep Roles Distinct
+
+- **Subject:** performs the declared task under one variant.
+- **Evaluator:** isolates subjects and preserves canonical evidence.
+- **Deterministic grader:** derives fixed mechanical facts after run persistence.
+- **Reviewer:** the active agent or user judges unresolved meaning.
+- **Author:** revises one measured pressure point.
+- **User:** decides whether to revise, use, publish, or reject the skill.
+
+The evaluator does not launch an automatic semantic grader or own readiness, promotion, or production status.
+
+## Map Claims To Evidence
+
+| Claim | Required evidence |
+| --- | --- |
+| Description routes the earliest useful prompt | Natural activation |
+| Body works with guaranteed context | Explicit body delivery |
+| Nearby prompt is not hijacked | Natural activation plus behavioral output |
+| Declared dependencies compose | Exact ordered composition |
+| Guidance remains useful later | Multi-turn evidence |
+| Files or structured state match | Artifact outcome |
+| Behavior holds on several hosts | The same group semantics on every named host |
+
+Record declaration, materialization, delivery, observed reads, behavior, artifacts, and derived grades separately. A read does not prove compliance, and correct behavior does not prove which skill caused it.
+
+## Choose The Smallest Group Shape
+
+- **Description prompt:** natural activation and exact read timing.
+- **Explicit body task:** first-read instructions and behavior without activation ambiguity.
+- **Fixture task:** files or repository state matter.
+- **Stateful turns:** ordered conversation and later behavior matter.
+- **Saved-result review:** stored runs already answer the question; inspect them instead of rerunning.
+- **Suite:** independent questions need one ordered serial invocation.
+
+Keep description and body questions separate unless the integrated path is itself the question.
+
+## Fix The Variants
+
+Every group has exactly:
+
+- `baseline`: no target for a new skill, or the exact previous snapshot for a revision;
+- `candidate`: the new or updated snapshot.
+
+For a description-only revision, keep body and resources byte-identical. Freeze prompts or turns, fixture, tools, model, thinking, other skills, context, and criteria across variants.
+
+## Design Common Questions
+
+### Description routing
+
+Use the earliest natural prompt where the skill should become useful. For a nearby prompt, predeclare whether success means non-trigger or safe behavior after activation.
+
+### First-read body
+
+Explicitly deliver the exact body with only guaranteed context. Ambient package context cannot repair a missing dependency.
+
+### Composition
+
+Materialize exact ordered skills and context. Vary only the target snapshot. Standalone behavior should not receive a hidden base stack.
+
+### Retained use
+
+Use declared turns in one persistent subject process. Repeated explicit delivery does not prove retained use.
+
+### Artifact outcome
+
+Grade filesystem state, changed paths, file content, or JSON before relying on the final response. Preserve turn-scoped workspace evidence when later turns may change earlier state.
+
+## Boundary Examples
+
+Saved complete evidence already contains the required run, grade, and artifacts:
+
+> Use `view` and ordinary file reads. Do not rerun merely to demonstrate the process.
+
+An explicitly delivered body produces the right answer, but the natural prompt never reads the target:
+
+> The body group supports first-read behavior. The description group still fails activation; body success cannot repair it.
+
+## Apply Real Pressure
+
+A useful group creates a real temptation to violate the rule, keeps criteria outside the prompt, exposes deterministic evidence where possible, and distinguishes baseline behavior from the candidate.
+
+If both variants pass, the pressure may be weak or the baseline sufficient. If both fail, classify the skill, fixture, host, dependency, or criterion before editing.

package/skills/evaluate-skill/references/execution-and-evidence.md

@@ -0,0 +1,85 @@
+# Execution And Evidence
+
+Read this when operating `run|view`, resolving paths, interpreting states, or reasoning about Pi execution, isolation, persistence, cancellation, and safeguards.
+
+## Command And Path Contract
+
+Run commands from the repository or fixture root that owns the definitions:
+
+```text
+node <evaluate-skill-directory>/scripts/skill-eval.mjs run <suite-or-group-path> [--group <id-or-position>] [--variant baseline|candidate]
+node <evaluate-skill-directory>/scripts/skill-eval.mjs view <result-id-or-directory> [--group <id-or-position>] [--variant baseline|candidate]
+```
+
+- The current working directory is the definition root and result root.
+- The `run` target resolves from that directory.
+- Suite group references resolve relative to the suite file.
+- Fixture, skill, and context declarations resolve from the definition root.
+- Results are stored under `<cwd>/.skill-eval/runs/<result-id>`.
+- A bare `view` target is tried first as a stored result ID, then as a path from the working directory.
+- An absolute or path-like `view` target resolves as a directory path.
+
+Examples:
+
+```text
+skill-eval run .skill-eval/my-skill/suite.json
+skill-eval run .skill-eval/my-skill/suite.json --variant candidate
+skill-eval view 20260720173209-a3649b8b
+skill-eval view 20260720173209-a3649b8b --group 2 --variant candidate
+skill-eval view /absolute/path/to/result
+```
+
+With no selectors, `run` or `view` selects every suite group and both variants. `--group` is invalid for a direct group definition/result.
+
+## Current Execution Boundary
+
+`run` executes description and body groups. `end-to-end` is a reserved definition type and is rejected before subject execution. Description groups allow no tools or `read`; body groups allow no tools or path-guarded `read`, `write`, and `edit`. `bash` and definition-supplied commands are unsupported.
+
+Use fresh JSON-mode execution for one-shot descriptions. Use one persistent RPC process per selected variant for ordered description turns and all body groups. RPC correlates responses, waits for `agent_settled`, disables automatic retry and compaction, preserves directly observed partial-turn evidence, and cleans the process tree.
+
+A body target is matched to the exact snapshotted `SKILL.md` and explicitly delivered on turn one. Later turns remain unchanged. Description groups use natural prompts and never explicit target delivery.
+
+## Isolation And Resources
+
+For each selected variant:
+
+- snapshot exact declared skills and context;
+- snapshot the group fixture once from the definition-root working tree—never from a variant Git source—then create an independent writable copy;
+- preserve skill order and target index;
+- replace ambient instructions with evaluator-owned declared context;
+- keep criteria and review questions outside the subject prompt;
+- allow reads only from workspace and declared immutable resources;
+- allow writes and edits only inside the workspace;
+- reject traversal, symlink escape, unsupported Git entries, and invalid UTF-8;
+- verify immutable resource fingerprints after execution.
+
+Working-tree sources snapshot current paths. Git sources resolve one exact commit and record both the declared ref and resolved identity.
+
+## Persistence And States
+
+Each selected run is persisted before its counterpart. Grade and group evidence are persisted before later groups.
+
+Run states are `complete`, `invalid`, `infrastructure-failed`, `cancelled`, and `not-selected`. Group and batch states are `complete`, `partially-complete`, `invalid` where applicable, and `cancelled`.
+
+- Failed deterministic checks are ordinary complete behavioral evidence and exit zero when no infrastructure/grade failure exists.
+- Variant-local invalidity or infrastructure failure preserves evidence and does not stop safe queued work.
+- Shared fixture failure invalidates the group.
+- Thrown grading or recoverable grade/group publication failure becomes explicit `grade-error` fallback evidence.
+- If a run or required fallback cannot be preserved, queued work stops and no completed summary is published.
+- Cancellation starts no queued subject and preserves observed diagnostics.
+
+Invalidity, infrastructure failure, cancellation, or `grade-error` makes the final command exit nonzero after safe queued work finishes.
+
+## Views And Raw Evidence
+
+Views can render a complete result, all baseline or candidate variants, one group, or one group/variant. Grade appears before selected run evidence. The displayed absolute result path anchors result-relative artifact and workspace paths.
+
+Path cells escape literal backslashes before tab, carriage return, and newline. Variant views exclude expectation-owned errors from the other variant while retaining comparison, group, and system errors.
+
+Use ordinary file tools for raw `run.json`, events, transcript, final response, stderr, workspace, definition, grade, and group artifacts. Views remove transport noise; they do not replace canonical evidence.
+
+## Safeguards And Limits
+
+Normal completion follows settlement. Path guards, no-progress detection, cancellation, process-tree cleanup, and very high emergency ceilings stop runaway or unsafe infrastructure. Do not impose ordinary guessed turn, token, spend, output, or short time caps.
+
+When an unsupported operation changes the question, reject it or run a clearly separate direct comparison with explicit limits. Never invoke archived evaluators as a fallback.

package/skills/evaluate-skill/references/review-and-revision.md

@@ -0,0 +1,51 @@
+# Review And Revision
+
+Read this after canonical evidence and deterministic grades exist, when evidence conflicts, meaning still needs judgment, or a revision/rerun boundary must be chosen.
+
+## Use The Strongest Evidence
+
+1. Filesystem state, typed workspace manifests, diffs, and changed paths.
+2. Structured events, tool activity, usage, process results, logs, and saved reports.
+3. Final response.
+4. Full transcript when earlier surfaces cannot answer the question.
+5. Subject self-assessment.
+
+Lower-priority evidence cannot repair a contradiction above it. If the response claims success but a required file is absent, preserve both facts and grade the file observation.
+
+## Keep Deterministic Facts Separate
+
+Built-in checks cover exact reads, typed paths, changed paths, file or response text, JSON states, valid turn scope, and factual transitions. Missing evidence remains unavailable. A failed check remains behavioral evidence; it does not relabel a complete run as infrastructure failure.
+
+The active agent or user may judge reasoning quality, authority preservation, architectural fitness, recommendation quality, or semantic completeness. Record cited evidence, uncertainty, and limits outside the canonical run and deterministic grade. Do not turn that judgment into evaluator-owned readiness state.
+
+## Diagnose Before Editing
+
+Classify the failed boundary:
+
+- activation timing;
+- description language unavailable before body read;
+- first-read body comprehension;
+- undeclared, undelivered, unread, or ambient-only dependency;
+- normal guidance hidden behind an unclear resource boundary;
+- nearby behavior that hijacks the task;
+- retained-use or multi-turn failure;
+- wording, placement, example, or stop-condition pressure;
+- fixture, environment, isolation, host, or deterministic-check failure.
+
+Do not add broad prose before identifying the failed boundary.
+
+## Revise One Pressure Point
+
+Change one measured point when possible: description cues, first-read wording, rule placement, dependency declaration, resource boundary, example, stop condition, or the group when evidence proves the evaluation is wrong.
+
+Keep unrelated instructions and fixed criteria stable. If the criterion changes, the old result no longer answers the same question.
+
+## Rerun The Complete Group
+
+After a measured skill change or resolved infrastructure cause, run the complete fixed group with both variants. Do not rerun only the preferred variant, reuse a settled control as a new sample, adopt partial evidence as comparable, or rerun merely to erase a failure.
+
+For variance, use independent complete invocations and keep every result visible.
+
+## Report
+
+Report the failed boundary and evidence, exact revision or evaluation correction, criteria that stayed fixed, old and new result paths, and remaining unsupported claims. The user decides the next authoring or use action.