@hassangameryt/freeflow 0.7.3 → 0.9.0

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

@@ -1,385 +0,0 @@
-# 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` 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.
-- `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.
-- `runtime` is optional. When omitted, the group runs under a plain `pi` host with no declared extensions. When present, it declares the host, ordered extension bundles, and string environment overrides.
-
-## 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?"
-  ]
-}
-```
-
-Description groups allow no tools or only built-in `read`. Body groups allow built-in `read`, `write`, and `edit`, plus custom tools declared by a runtime extension bundle. Native `bash`, `powershell`, `grep`, `find`, and `ls` tools are unsupported. A no-target baseline or runtime-only group may use `skills: []` and `target: null`; a candidate that declares skills must identify its 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.
-
-## Runtime Profile
-
-A runtime profile is shared by both baseline and candidate variants. It changes the host environment, not the skill target:
-
-```json
-{
-  "runtime": {
-    "host": "pi",
-    "session": false,
-    "extensions": [
-      {
-        "entry": "extensions/probe.mjs",
-        "resources": ["extensions"]
-      }
-    ],
-    "environment": {
-      "literal": {
-        "PROBE_MODE": "injection-test"
-      },
-      "inherit": []
-    }
-  }
-}
-```
-
-`host` is `pi` or `piflow`; the evaluator maps it to the corresponding installed host command and records the selected host. `session` controls whether the variant receives an isolated persistent session directory; it defaults to `false` in omitted runtime profiles. A runtime may declare zero or more bundles. Each bundle has an entry file and one or more directory resources copied under their original relative paths, so sibling imports and multi-tree extensions remain intact. Bundle bytes are snapshotted once and copied identically to both variants.
-
-`environment.literal` contains non-secret string configuration and is recorded in run evidence. `environment.inherit` names parent-process variables whose values are passed to the child but never persisted; other parent variables are not passed. Missing inherited variables invalidate the variant. The evaluator supplies only a small host-runtime baseline such as `PATH` and `HOME`. Launch-control and loader keys are rejected from inherited values, literal and inherited names must not overlap, and secret-like literal keys are rejected.
-
-Extensions are trusted executable inputs, not OS-sandboxed code. The evaluator proves declared identity and post-run immutability, but extension code retains its host permissions.
-
-When a group declares `context-text` expectations, the evaluator loads its base isolation guard first, then declared bundles, then a non-mutating final observer. The observer records two per-turn surfaces: the chained `before_agent_start` system prompt and each provider-neutral `context` message projection. `context-text` expectations select `surface: "system-prompt"` or `surface: "provider-context"` and may select `request: "first"`, `"last"`, or a positive request number. Groups without context assertions do not create context-observation artifacts.
-
-A custom tool name is allowed in `group.tools` only when the runtime declares an extension bundle. The evaluator remains extension-neutral: it does not interpret feature names or configuration schemas. Put feature configuration in the ordinary group fixture or runtime environment, and test combinations as separate suite groups.
-
-## Variant Environment
-
-Each environment has exactly:
-
-```json
-{
-  "source": { "kind": "git", "ref": "v1.2.3" },
-  "skills": ["skills/target", "skills/support"],
-  "target": 0,
-  "context": ["context/base-guidance.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` |
-| `tool-call` | string `tool`, optional body `turn`, optional `argumentContains`/`argumentNotContains` arrays | `called`, `succeeded`, `failed`, `not-called` |
-| `context-text` | string `value`, optional `surface` (`system-prompt` or `provider-context`), optional `request`, optional body `turn` | `contains`, `not-contains`, `equals` |
-
-For `tool-call` with `expect: "not-called"`, omitted argument filters require zero calls to the named tool. Supplied filters scope the absence check to calls matching those argument predicates.
-
-### 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

@@ -1,112 +0,0 @@
-# Evaluation Design
-
-Read this before choosing or materially changing the behavioral question, evidence class, group shape, pressure, 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:** uses Write Skill to revise one measured pressure point.
-- **User:** decides whether to revise, use, publish, or reject the skill.
-
-The evaluator does not revise the skill, 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 across named hosts | The same group semantics on every named host |
-
-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 body behavior without activation ambiguity.
-- **Fixture task:** files or repository state matter.
-- **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:
-
-- `baseline`;
-- `candidate`.
-
-For a new skill, baseline has no target.
-
-For a revision, baseline names an exact immutable previous package. If no exact baseline exists, return to Write Skill before revision.
-
-For a description-only revision, body and resources remain byte-identical.
-
-Freeze prompts or turns, fixture, tools, model, thinking, other skills, context, runtime, and criteria across variants.
-
-## Design Common Questions
-
-### Description 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 target body with only guaranteed context. Ambient package context cannot repair a hidden dependency.
-
-### Dependency composition
-
-Materialize exact ordered skills and context. Vary only the target snapshot. Do not provide a hidden base stack.
-
-### Retained use
-
-Use ordered turns in one persistent subject process. Repeated body delivery does not prove retained use.
-
-### Artifact outcome
-
-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.
-
-## Apply Real Pressure
-
-A useful group:
-
-- 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.
-
-If both variants pass, the pressure may be weak or the baseline sufficient.
-
-If both fail, classify skill, fixture, dependency, environment, host, isolation, or criterion before editing.
-
-## Reuse Existing Evidence
-
-When saved canonical evidence already answers the fixed question, inspect it through views and raw artifacts. Do not rerun merely to demonstrate process.
-
-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

@@ -1,90 +0,0 @@
-# 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. 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.
-
-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, context, and the shared runtime bundle resources;
-- copy the shared runtime bundles identically into the variant and verify their fingerprints before and after execution;
-- 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;
-- preserve runtime host, session mode, and extension order;
-- preserve runtime bundle and provider-context observation evidence when requested;
-- 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, context observations, and group artifacts. Views remove transport noise; they do not replace canonical evidence. Tool-call grades distinguish attempted, succeeded, failed, and not-called outcomes.
-
-## 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

@@ -1,92 +0,0 @@
-# Review And Revision
-
-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
-
-Prefer, in order:
-
-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 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:
-
-- reasoning quality;
-- authority preservation;
-- architectural fitness;
-- recommendation quality;
-- semantic completeness.
-
-Keep semantic judgment, cited evidence, uncertainty, and limits outside canonical run and deterministic grade state.
-
-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 the wrong resource boundary;
-- nearby behavior that hijacks the task;
-- retained-use or multi-turn 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.
-
-## Return Revision To Write Skill
-
-When evidence supports a skill change:
-
-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).
-
-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 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 rather than repeated preferred variants.
-
-## Report
-
-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.