@hassangameryt/freeflow 0.6.0 → 0.7.1

package/skills/evaluate-skill/SKILL.md

@@ -5,71 +5,126 @@ 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.
+Determine whether an exact skill package 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.
+- `baseline`: no target skill for a new skill, or one exact immutable previous package for a revision;
+- `candidate`: one exact new or updated package.
 
-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.
+The **subject** performs the declared task under one variant. The **evaluator** isolates subjects and preserves canonical evidence. The **deterministic grader** derives fixed mechanical facts after run persistence. A **suite** runs an ordered set of independent groups.
 
-Inline examples teach the subject. They are candidate content, not evaluation evidence. Keep criteria and expected outcomes outside natural prompts.
+Evaluate Skill does not author or revise skills, decide semantic quality, claim readiness, or choose publication. [Write Skill](../write-skill/SKILL.md) owns package preservation and revision. The active agent or user judges unresolved meaning. The user decides whether to revise, use, publish, or reject the skill.
 
-## Route First
+Inline examples teach the subject and are part of the candidate intervention. They are not independent evaluation evidence. Keep deterministic criteria and review questions outside natural subject prompts.
 
-- 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.
+## Route From Existing Evidence First
 
-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.
+Before proposing a run or revision:
 
-## Name One Question
+- inspect adequate saved evidence;
+- reuse an existing group unchanged when it still preserves the question, pressure, variants, and fixed criteria;
+- use saved views and raw artifact reads when a complete result already answers the question;
+- preserve partial infrastructure evidence without converting unavailable behavior into pass or fail;
+- do not mutate canonical evidence or erase an unfavorable result.
 
-Separate the behavior being examined:
+For a draft-only request, use Write Skill. Do not fabricate behavioral evidence.
 
-- **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?
+A revision comparison requires an exact immutable baseline identity. If none exists, return to Write Skill to preserve the complete current package before revision. Evaluate Skill consumes baseline and candidate identities; it does not create a baseline by editing the package it is evaluating.
+
+## Name One Behavioral Question
+
+Name the exact claim and observing mechanism before choosing the group shape.
+
+Evidence classes include:
+
+- **Description activation:** did a natural prompt cause the exact target to be read, and when?
+- **First-read body behavior:** did explicit body delivery guide the subject using 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?
+- **Retained use:** did guidance remain useful on later declared turns without redelivery?
+- **Artifact outcome:** did files, structured state, events, and responses match fixed criteria?
+- **Cross-host behavior:** did the same behavioral question hold on every named host?
+
+One evidence class does not prove another.
+
+```text
+successful read
+≠ behavioral compliance
+
+explicit body delivery
+≠ natural activation
+
+one turn
+≠ retained use
+
+ambient installation
+≠ declared composition
+
+correct behavior
+≠ proof that the target caused it
+```
+
+Read [Evaluation Design](references/evaluation-design.md) before choosing or materially changing the question, evidence class, group shape, pressure, or baseline/candidate boundary.
+
+## Design The Smallest Valid Comparison
+
+Before subject output exists:
+
+1. fix one behavioral question;
+2. fix deterministic expectations and review questions;
+3. preserve the earliest natural prompt or strongest pressure capable of distinguishing behavior;
+4. declare exact baseline and candidate identities;
+5. keep prompt or turns, fixture, tools, model, thinking, other skills, context, runtime, and criteria fixed except for the target difference;
+6. run one group or an ordered suite serially;
+7. inspect canonical evidence and deterministic facts before judging meaning;
+8. classify the failed boundary before proposing revision;
+9. return one measured revision target to Write Skill;
+10. rerun the complete fixed group with both variants after a behavioral change.
+
+For a new skill:
+
+```text
+baseline: no target skill
+candidate: exact candidate package
+```
 
-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.
+For a revision:
 
-Read [evaluation design](references/evaluation-design.md) when choosing the question, evidence class, group shape, or variant boundary.
+```text
+baseline: exact previous package
+candidate: exact revised package
+```
 
-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.
+For a description-only revision, keep body, references, scripts, and other resources byte-identical.
 
-Two common boundary examples:
+If both variants pass, the pressure may be weak or the baseline already sufficient. If both fail, distinguish skill, fixture, dependency, environment, host, isolation, and criterion failures before revising instructions.
 
-- 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.
+## Declare The Complete Environment
 
-## Use The Smallest Valid Loop
+Use the exact [Evaluation Definition Schema](references/evaluation-definition-schema.md) when authoring or checking group and suite JSON.
 
-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.
+Declare:
 
-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.
+- prompt or ordered turns;
+- fixture;
+- exact ordered skill packages and target index;
+- working-tree or Git source identity;
+- context resources;
+- tools;
+- model and thinking;
+- runtime host and extension bundles when needed;
+- literal and inherited environment sources;
+- deterministic expectations and comparison IDs;
+- review questions.
 
-## Declare The Definition
+Snapshot every declared subject resource. Ambient installation is not declared composition.
 
-Use the exact [Evaluation Definition Schema](references/evaluation-definition-schema.md) for group, environment, expectation, suite, and selector shapes.
+Criteria and review questions remain outside the subject prompt.
 
-Declare the prompt or turns, fixture, exact ordered skills and target, working-tree or Git source, runtime host/session mode and ordered extension bundles when needed, literal/inherited environment sources, 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 Preserve Canonical Evidence
 
-## Run And View
+Before operating the evaluator, resolving paths, interpreting states, or reasoning about host execution, read [Execution and Evidence](references/execution-and-evidence.md).
 
 Use the canonical [skill evaluator](scripts/skill-eval.mjs):
 
@@ -78,28 +133,87 @@ node <evaluate-skill-directory>/scripts/skill-eval.mjs run <suite-or-group-path>
 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.
+Run from the definition root.
+
+With no selectors, run or view every suite group and both variants. Selectors narrow execution or viewing scope; they do not modify definitions.
+
+Canonical results live under:
+
+```text
+<definition-root>/.skill-eval/runs/<result-id>
+```
+
+A view is a projection of saved evidence, not its canonical source. Use ordinary file tools when exact run, event, transcript, response, stderr, workspace, definition, grade, context-observation, or group artifacts matter.
+
+Do not invoke archived evaluators.
+
+## Derive Facts Without Inventing Meaning
 
-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.
+Append deterministic grades only after canonical run evidence exists.
 
-Pi is the direct subject process; a runtime profile may select the compatible `piflow` command as an explicit host variant. 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. Declared extension bundles may provide non-native custom tools in body groups and context injections; description groups remain limited to no tools or `read`. Native `bash`, `powershell`, `grep`, `find`, and `ls` tools, definition-supplied command execution, and end-to-end execution are unsupported.
+Deterministic checks may establish exact facts such as:
 
-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.
+- skill or resource reads;
+- file and path state;
+- changed paths;
+- file or response text;
+- JSON validity or values;
+- tool-call outcomes and argument predicates;
+- context text at a selected surface, request, and turn;
+- factual baseline-to-candidate transitions.
 
-## Grade And Inspect Facts
+A failed check remains ordinary behavioral evidence. It does not turn a valid subject run into infrastructure failure.
 
-Append deterministic grades only after canonical run evidence exists. A grade is derived evidence and never mutates or invalidates a run.
+Missing evidence remains unavailable.
 
-Supported checks cover exact skill/resource reads, typed paths, changed paths, file/response text, explicit JSON states, tool-call outcomes and argument predicates, system-prompt or provider-context text by selected request and turn, 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.
+Malformed expectations or grading failures produce separate `grade-error` evidence and do not rewrite canonical run evidence.
 
-Prefer generated grade-first views for routine inspection. Use ordinary file tools for raw run, event, transcript, response, stderr, workspace, definition, grade, context-observation, and group artifacts. A view may remove repeated transport structure; it must not hide evidence required by the question.
+A transition such as `fail-to-pass` is a factual comparison. It does not mean bad-to-good, not-ready-to-ready, or rejected-to-promotable.
 
-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.
+## Review Meaning After Evidence Exists
+
+After canonical evidence and deterministic grades exist, read [Review and Revision](references/review-and-revision.md) when:
+
+- evidence conflicts;
+- semantic meaning remains unresolved;
+- the failed boundary must be classified;
+- a revision target must be selected;
+- rerun scope is uncertain.
+
+The evaluator does not launch an automatic semantic grader.
+
+The active agent or user may judge reasoning quality, authority preservation, architectural fitness, recommendation quality, or semantic completeness. Keep that judgment, cited evidence, uncertainty, and limits outside canonical run and grade state.
+
+## Return Revision To The Author
+
+When evidence supports a candidate change:
+
+1. identify the exact failed boundary;
+2. preserve the canonical result path and relevant evidence;
+3. state one measured revision target;
+4. keep unrelated instructions and criteria stable;
+5. return revision to Write Skill;
+6. rerun the complete fixed group with both variants after the change.
+
+Do not edit the skill from Evaluate Skill.
+
+If the evaluation definition or criterion is wrong, preserve the old result and state that it no longer answers the revised question. Do not reinterpret it as evidence for the new question.
 
 ## 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.
+Report:
+
+- what ran;
+- exact baseline and candidate identities;
+- selected groups and variants;
+- deterministic results;
+- infrastructure failures, cancellation, or unavailable evidence;
+- viewed scope;
+- canonical result paths;
+- what the evidence proves;
+- what it does not prove;
+- any supported failed boundary or revision target.
 
-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.
+Stop rather than overclaim when required activation, first-read, composition, retained-use, isolation, artifact, or host evidence is unavailable.
 
-Never invoke archived evaluators.
+The active agent or user judges unresolved behavior. The user decides whether to revise, use, publish, or reject the skill.

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

@@ -58,7 +58,7 @@ 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.
+- `type` is `description` or `body`.
 - `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.
@@ -252,7 +252,7 @@ Each environment has exactly:
   "source": { "kind": "git", "ref": "v1.2.3" },
   "skills": ["skills/target", "skills/support"],
   "target": 0,
-  "context": ["runtime/prompts/interaction-contract.md"]
+  "context": ["context/base-guidance.md"]
 }
 ```
 

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

@@ -1,6 +1,6 @@
 # Evaluation Design
 
-Read this when choosing the behavioral question, evidence class, group shape, or baseline/candidate boundary.
+Read this before choosing or materially changing the behavioral question, evidence class, group shape, pressure, or baseline/candidate boundary.
 
 ## Keep Roles Distinct
 
@@ -8,10 +8,10 @@ Read this when choosing the behavioral question, evidence class, group shape, or
 - **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.
+- **Author:** uses Write Skill to revise 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.
+The evaluator does not revise the skill, launch an automatic semantic grader, or own readiness, promotion, or production status.
 
 ## Map Claims To Evidence
 
@@ -23,64 +23,90 @@ The evaluator does not launch an automatic semantic grader or own readiness, pro
 | 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 |
+| Behavior holds across named 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.
+Record separately:
+
+- declaration;
+- resource materialization;
+- delivery;
+- observed reads;
+- behavior;
+- artifacts;
+- derived grades;
+- later semantic judgment.
+
+A read does not prove compliance. 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.
+- **Explicit body task:** first-read body 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.
+- **Stateful turns:** ordered conversation and retained use matter.
+- **Saved-result review:** canonical evidence already answers the question.
+- **Suite:** several independent questions require one ordered serial invocation.
+
+Keep activation and body behavior separate unless their integrated interaction is the exact question and the current runner supports that observing boundary.
+
+## Fix Exact Variants
+
+Every group contains exactly:
 
-Keep description and body questions separate unless the integrated path is itself the question.
+- `baseline`;
+- `candidate`.
 
-## Fix The Variants
+For a new skill, baseline has no target.
 
-Every group has exactly:
+For a revision, baseline names an exact immutable previous package. If no exact baseline exists, return to Write Skill before revision.
 
-- `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, body and resources remain byte-identical.
 
-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.
+Freeze prompts or turns, fixture, tools, model, thinking, other skills, context, runtime, and criteria across variants.
 
 ## Design Common Questions
 
-### Description routing
+### Description activation
 
-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.
+Use the earliest natural prompt where the target 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.
+Explicitly deliver the exact target body with only guaranteed context. Ambient package context cannot repair a hidden dependency.
 
-### Composition
+### Dependency composition
 
-Materialize exact ordered skills and context. Vary only the target snapshot. Standalone behavior should not receive a hidden base stack.
+Materialize exact ordered skills and context. Vary only the target snapshot. Do not provide a hidden base stack.
 
 ### Retained use
 
-Use declared turns in one persistent subject process. Repeated explicit delivery does not prove retained use.
+Use ordered turns in one persistent subject process. Repeated body 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.
+Grade files, changed paths, structured state, and events before relying on the final response. Preserve turn-scoped workspace evidence when later turns may change earlier state.
 
-## Boundary Examples
+## Apply Real Pressure
 
-Saved complete evidence already contains the required run, grade, and artifacts:
+A useful group:
 
-> Use `view` and ordinary file reads. Do not rerun merely to demonstrate the process.
+- creates a natural temptation to violate the intended behavior;
+- keeps criteria and review questions outside the prompt;
+- exposes deterministic evidence where possible;
+- distinguishes baseline from candidate behavior;
+- remains realistic enough that passing behavior is useful.
 
-An explicitly delivered body produces the right answer, but the natural prompt never reads the target:
+If both variants pass, the pressure may be weak or the baseline sufficient.
 
-> The body group supports first-read behavior. The description group still fails activation; body success cannot repair it.
+If both fail, classify skill, fixture, dependency, environment, host, isolation, or criterion before editing.
 
-## Apply Real Pressure
+## Reuse Existing Evidence
 
-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.
+When saved canonical evidence already answers the fixed question, inspect it through views and raw artifacts. Do not rerun merely to demonstrate process.
 
-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.
+An explicitly delivered body may support first-read behavior while a natural prompt still fails activation. Preserve both conclusions; one does not repair the other.

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

@@ -33,7 +33,7 @@ With no selectors, `run` or `view` selects every suite group and both variants.
 
 ## 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`, plus non-native custom tools supplied by a declared runtime extension bundle. Native `bash`, `powershell`, `grep`, `find`, and `ls` tools and definition-supplied commands are unsupported.
+`run` executes description and body groups. Unsupported group types are rejected before subject execution. Description groups allow no tools or `read`; body groups allow no tools or path-guarded `read`, `write`, and `edit`, plus non-native custom tools supplied by a declared runtime extension bundle. Native `bash`, `powershell`, `grep`, `find`, and `ls` tools and definition-supplied commands are unsupported.
 
 A runtime profile selects the installed `pi` or `piflow` host, whether the variant uses an isolated persistent session directory, zero or more ordered extension bundles, and declarative environment sources. Literal values are non-secret configuration; only explicitly inherited parent variables are passed to the child without being persisted, alongside a small host-runtime baseline. Missing inherited variables invalidate the variant. Launch-control and loader keys are rejected from inherited values, and literal and inherited names must not overlap. For body runs, delivery remains `unavailable` until target setup succeeds; `natural-prompt` or `explicit-skill-command` records a prompt attempt. When a group declares context assertions, the evaluator launches the base guard first, declared extensions second, and a final non-mutating observer last. The observer records both the effective `before_agent_start` system prompt and each provider-neutral `context` message projection; it does not replace or sanitize extension injections after the base guard has established evaluator-owned isolation.
 

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

@@ -1,51 +1,92 @@
 # 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.
+Read this after canonical evidence and deterministic grades exist, when evidence conflicts, meaning remains unresolved, the failed boundary must be classified, or revision and rerun scope 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.
+Prefer, in order:
 
-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.
+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 stronger surfaces cannot answer the question;
+5. subject self-assessment.
+
+Lower-priority evidence cannot repair a contradiction above it.
+
+If a response claims success but a required file is absent, preserve both facts and judge from the stronger artifact evidence.
 
 ## 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.
+Built-in checks establish exact observable facts. Missing evidence remains unavailable. A failed check remains behavioral evidence and does not relabel a complete run as infrastructure failure.
+
+The active agent or user may judge:
 
-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.
+- reasoning quality;
+- authority preservation;
+- architectural fitness;
+- recommendation quality;
+- semantic completeness.
 
-## Diagnose Before Editing
+Keep semantic judgment, cited evidence, uncertainty, and limits outside canonical run and deterministic grade state.
 
-Classify the failed boundary:
+Do not turn semantic judgment into evaluator-owned readiness or promotion status.
+
+## Diagnose The Failed Boundary
+
+Classify before revising:
 
 - 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;
+- normal guidance hidden behind the wrong 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.
+- wording, placement, example, repetition, or stop-condition pressure;
+- fixture, environment, isolation, host, runner, or deterministic-check failure.
+
+Do not add broad prose before identifying which boundary failed.
 
-Do not add broad prose before identifying the failed boundary.
+## Return Revision To Write Skill
 
-## Revise One Pressure Point
+When evidence supports a skill change:
 
-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.
+1. name the exact failed boundary;
+2. cite the canonical evidence;
+3. identify one measured pressure point;
+4. preserve unrelated instructions and fixed criteria;
+5. return the revision target to [Write Skill](../../write-skill/SKILL.md).
 
-Keep unrelated instructions and fixed criteria stable. If the criterion changes, the old result no longer answers the same question.
+Write Skill owns package revision.
+
+Evaluate Skill does not edit the skill or replace its baseline while evaluating it.
+
+When evidence proves the group, fixture, or criterion is wrong, revise the evaluation instead. Preserve the old result and state that it no longer answers the revised 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.
+After a measured skill revision or resolved infrastructure cause:
+
+- rerun the complete fixed group;
+- run both baseline and candidate;
+- keep every result visible;
+- do not reuse an earlier baseline run as a fresh counterpart;
+- do not rerun only the preferred variant;
+- do not use partial evidence as a comparable full result;
+- do not rerun merely to erase failure.
 
-For variance, use independent complete invocations and keep every result visible.
+For variance, use independent complete invocations rather than repeated preferred variants.
 
 ## 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.
+Report:
+
+- failed boundary and evidence;
+- exact skill revision or evaluation correction;
+- criteria that remained fixed;
+- old and new result paths;
+- deterministic transitions;
+- remaining unsupported claims.
+
+The user decides whether to revise further, use, publish, or reject the skill.