@skill-harness/core 0.2.1 → 0.3.1

package/dist/sources.d.ts

@@ -0,0 +1,115 @@
+import type { Scenario } from "./spec.js";
+/**
+ * What a run measured, as a map of `key -> sha256`, recorded in results.yaml so
+ * lint can prove a published result still describes the current inputs.
+ *
+ * A run measures more than the skill text. It measures the SKILL.md, any agent
+ * file, **the scenario definition itself** (turns, checklist, gates) and **the
+ * fixture** the scenario starts from. Hashing only the first two — which is what
+ * shipped through 0.2.1 — meant editing a checklist or swapping a fixture left
+ * every published result looking current.
+ *
+ * ## Key scheme
+ *
+ * | key | means |
+ * |---|---|
+ * | `SKILL.md` | the skill text, resolved against the skill dir |
+ * | `scenario:<id>` | the semantic content of one scenario in the spec |
+ * | `fixture:<path>` | every file under one fixture dir |
+ * | anything else | a file path resolved against the spec's dir (`system_prompt_file`) |
+ *
+ * Separation from bare-path keys is conventional, not guaranteed: `scenario:A1`
+ * is a legal POSIX filename, so nothing stops someone naming an agent file that.
+ * In practice `system_prompt_file` and `post_test` values are ordinary relative
+ * paths, and a `<name>:` prefix is reserved for this scheme. Old results carrying
+ * only bare-path keys keep resolving exactly as before.
+ *
+ * ## Why per-scenario, not one hash of specification.yaml
+ *
+ * Hashing the whole spec file would mark **every** historical run stale the
+ * moment a spec grows by one scenario — the precise noise `lint`'s scenario-set
+ * check already exists to prevent ("a spec reshape must not consistency-flag
+ * every historical run"). A per-scenario digest says what actually changed:
+ * editing A1's checklist marks A1 stale and leaves A2 alone; appending a new
+ * scenario marks nothing stale, because nothing already measured changed.
+ *
+ * It also ignores formatting: the digest is built from the *parsed* scenario, so
+ * reindenting the YAML or reordering scenarios is correctly a no-op, while
+ * changing a single checklist word is correctly a change.
+ */
+export declare const SCENARIO_PREFIX = "scenario:";
+export declare const FIXTURE_PREFIX = "fixture:";
+/**
+ * Recorded in place of a hash when a source existed but could not be read.
+ *
+ * Omitting it instead — which is what an early version did — is the worst
+ * available option: `lint` only ever iterates the keys a run recorded, so a
+ * source dropped at record time is never compared again for the life of that
+ * result. A fixture briefly unreadable during a run could then be replaced
+ * wholesale and `lint` would still report 0 findings, which is verbatim the miss
+ * this module was written to close.
+ *
+ * Not valid sha256 hex, so it can never equal a real digest and always surfaces.
+ */
+export declare const UNREADABLE = "unreadable";
+/** sha256 of a file, or null when it doesn't exist / isn't readable. */
+export declare function fileSha256(path: string): string | null;
+/**
+ * Stable sha256 over a directory tree: every file's relative path (POSIX-slashed,
+ * sorted) and contents. Null if the directory is missing or unreadable.
+ *
+ * Sorting is what makes it stable — readdir order is filesystem-dependent, so an
+ * unsorted walk would produce different digests for identical trees on different
+ * machines and turn CI into a staleness alarm. Paths are hashed alongside
+ * contents so that renaming a fixture file is a change, and separators are
+ * normalised so a Linux-recorded hash still matches on Windows.
+ */
+export declare function dirSha256(dir: string): string | null;
+/**
+ * A scenario's semantic digest: everything that changes what the scenario
+ * measures, and nothing that doesn't.
+ *
+ * Built from the parsed scenario rather than its YAML text, so formatting is
+ * irrelevant. `critical` is included because it changes whether the scenario can
+ * block a ship; `title` is included because it is what a reader of the scorecard
+ * believes was tested.
+ */
+export declare function scenarioDigest(s: Scenario): string;
+/**
+ * The fixture path a scenario actually runs in, or undefined.
+ *
+ * The EFFECTIVE workspace fixture, which is not always `scenario.fixture`: an
+ * inline scenario with `env.workspace: fixture:PATH` sets `workspace.fixture`
+ * and leaves `scenario.fixture` unset. Exported and shared with lint, which
+ * needs the identical rule — a second copy of this expression is how the hashed
+ * set and the checked set drift apart.
+ */
+export declare function effectiveFixture(s: Scenario): string | undefined;
+export interface SourceContext {
+    skillDir: string;
+    specDir: string;
+    scenarios: Scenario[];
+}
+/**
+ * Hash every source this run measures: SKILL.md, each distinct
+ * `system_prompt_file`, each scenario's definition, and each distinct fixture
+ * tree. Entries that can't be read are omitted — a missing source is lint's
+ * problem to report, not run's to crash on.
+ */
+export declare function sourceHashes(ctx: SourceContext): Record<string, string>;
+/**
+ * The current hash for a recorded key, or null when the source is gone.
+ *
+ * `undefined` is distinct from `null` and means "not comparable": the key names a
+ * scenario the spec no longer has. That is a spec *reshape*, not staleness — the
+ * same stance lint's scenario-set check already takes — so the caller stays quiet
+ * rather than reporting a removed scenario as a stale measurement.
+ *
+ * Sharing this resolver with `sourceHashes` is what keeps recording and checking
+ * from drifting: a new key kind is defined once, for both sides.
+ */
+export declare function currentHashFor(key: string, ctx: SourceContext): string | null | undefined;
+/** Human label for a recorded key, used in lint messages. */
+export declare function describeSourceKey(key: string): string;
+/** The scenario id a key belongs to, for per-scenario lint findings. Undefined for skill-wide keys. */
+export declare function scenarioIdForKey(key: string, scenarios: Scenario[]): string | undefined;

package/dist/sources.js

@@ -0,0 +1,253 @@
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+/**
+ * What a run measured, as a map of `key -> sha256`, recorded in results.yaml so
+ * lint can prove a published result still describes the current inputs.
+ *
+ * A run measures more than the skill text. It measures the SKILL.md, any agent
+ * file, **the scenario definition itself** (turns, checklist, gates) and **the
+ * fixture** the scenario starts from. Hashing only the first two — which is what
+ * shipped through 0.2.1 — meant editing a checklist or swapping a fixture left
+ * every published result looking current.
+ *
+ * ## Key scheme
+ *
+ * | key | means |
+ * |---|---|
+ * | `SKILL.md` | the skill text, resolved against the skill dir |
+ * | `scenario:<id>` | the semantic content of one scenario in the spec |
+ * | `fixture:<path>` | every file under one fixture dir |
+ * | anything else | a file path resolved against the spec's dir (`system_prompt_file`) |
+ *
+ * Separation from bare-path keys is conventional, not guaranteed: `scenario:A1`
+ * is a legal POSIX filename, so nothing stops someone naming an agent file that.
+ * In practice `system_prompt_file` and `post_test` values are ordinary relative
+ * paths, and a `<name>:` prefix is reserved for this scheme. Old results carrying
+ * only bare-path keys keep resolving exactly as before.
+ *
+ * ## Why per-scenario, not one hash of specification.yaml
+ *
+ * Hashing the whole spec file would mark **every** historical run stale the
+ * moment a spec grows by one scenario — the precise noise `lint`'s scenario-set
+ * check already exists to prevent ("a spec reshape must not consistency-flag
+ * every historical run"). A per-scenario digest says what actually changed:
+ * editing A1's checklist marks A1 stale and leaves A2 alone; appending a new
+ * scenario marks nothing stale, because nothing already measured changed.
+ *
+ * It also ignores formatting: the digest is built from the *parsed* scenario, so
+ * reindenting the YAML or reordering scenarios is correctly a no-op, while
+ * changing a single checklist word is correctly a change.
+ */
+export const SCENARIO_PREFIX = "scenario:";
+export const FIXTURE_PREFIX = "fixture:";
+/**
+ * Recorded in place of a hash when a source existed but could not be read.
+ *
+ * Omitting it instead — which is what an early version did — is the worst
+ * available option: `lint` only ever iterates the keys a run recorded, so a
+ * source dropped at record time is never compared again for the life of that
+ * result. A fixture briefly unreadable during a run could then be replaced
+ * wholesale and `lint` would still report 0 findings, which is verbatim the miss
+ * this module was written to close.
+ *
+ * Not valid sha256 hex, so it can never equal a real digest and always surfaces.
+ */
+export const UNREADABLE = "unreadable";
+/** sha256 of a file, or null when it doesn't exist / isn't readable. */
+export function fileSha256(path) {
+    try {
+        return createHash("sha256").update(readFileSync(path)).digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Stable sha256 over a directory tree: every file's relative path (POSIX-slashed,
+ * sorted) and contents. Null if the directory is missing or unreadable.
+ *
+ * Sorting is what makes it stable — readdir order is filesystem-dependent, so an
+ * unsorted walk would produce different digests for identical trees on different
+ * machines and turn CI into a staleness alarm. Paths are hashed alongside
+ * contents so that renaming a fixture file is a change, and separators are
+ * normalised so a Linux-recorded hash still matches on Windows.
+ */
+export function dirSha256(dir) {
+    let files;
+    try {
+        files = walk(dir).sort();
+    }
+    catch {
+        return null;
+    }
+    const h = createHash("sha256");
+    for (const rel of files) {
+        h.update(rel);
+        h.update("\0");
+        try {
+            h.update(readFileSync(join(dir, rel)));
+        }
+        catch {
+            return null; // a file that vanished mid-walk makes the whole digest untrustworthy
+        }
+        h.update("\0");
+    }
+    return h.digest("hex");
+}
+/** Relative POSIX paths of every file under `dir`, recursively. Throws if `dir` is unreadable. */
+function walk(dir, prefix = "") {
+    const out = [];
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${e.name}` : e.name;
+        if (e.isDirectory()) {
+            out.push(...walk(join(dir, e.name), rel));
+        }
+        else if (e.isFile()) {
+            out.push(rel);
+        }
+        // symlinks/sockets/etc. are deliberately skipped: a fixture is plain files,
+        // and following links could hash something outside the fixture entirely.
+    }
+    return out;
+}
+/**
+ * A scenario's semantic digest: everything that changes what the scenario
+ * measures, and nothing that doesn't.
+ *
+ * Built from the parsed scenario rather than its YAML text, so formatting is
+ * irrelevant. `critical` is included because it changes whether the scenario can
+ * block a ship; `title` is included because it is what a reader of the scorecard
+ * believes was tested.
+ */
+export function scenarioDigest(s) {
+    // Destructured, with the remainder pinned to `Record<string, never>`, so that
+    // adding a field to `Scenario` or `SeededAssert` FAILS THE BUILD here instead of
+    // silently escaping the digest. A field nobody remembered to add is a permanent
+    // staleness blind spot — edit it and every published result still looks current,
+    // which is precisely the bug this module exists to kill. This PR added two
+    // SeededAssert fields and remembered both; that only proves the discipline works
+    // while someone is looking, so the compiler now does the looking.
+    const { id, title, critical, mode, turns, checklist, fixture, assert, workspace, remote, systemPromptFile, reps, passThreshold, ...restScenario } = s;
+    const _scenarioExhaustive = restScenario;
+    void _scenarioExhaustive;
+    const { vitest, diff_contains, diff_excludes, post_test, ...restAssert } = assert ?? {};
+    const _assertExhaustive = restAssert;
+    void _assertExhaustive;
+    const canonical = JSON.stringify([
+        id,
+        title,
+        critical,
+        mode,
+        turns,
+        checklist,
+        fixture ?? null,
+        assert ? [vitest ?? null, diff_contains ?? null, diff_excludes ?? null, post_test ?? null] : null,
+        workspace,
+        remote,
+        systemPromptFile ?? null,
+        reps ?? null,
+        passThreshold ?? null,
+    ]);
+    return createHash("sha256").update(canonical).digest("hex");
+}
+/** Absolute path a fixture key refers to. Fixtures resolve against the spec's dir, like workspace.ts. */
+function fixtureAbs(specDir, fixture) {
+    return isAbsolute(fixture) ? fixture : resolve(specDir, fixture);
+}
+/**
+ * The fixture path a scenario actually runs in, or undefined.
+ *
+ * The EFFECTIVE workspace fixture, which is not always `scenario.fixture`: an
+ * inline scenario with `env.workspace: fixture:PATH` sets `workspace.fixture`
+ * and leaves `scenario.fixture` unset. Exported and shared with lint, which
+ * needs the identical rule — a second copy of this expression is how the hashed
+ * set and the checked set drift apart.
+ */
+export function effectiveFixture(s) {
+    return typeof s.workspace === "object" && s.workspace !== null ? s.workspace.fixture : undefined;
+}
+/**
+ * Hash every source this run measures: SKILL.md, each distinct
+ * `system_prompt_file`, each scenario's definition, and each distinct fixture
+ * tree. Entries that can't be read are omitted — a missing source is lint's
+ * problem to report, not run's to crash on.
+ */
+export function sourceHashes(ctx) {
+    const hashes = {};
+    // UNREADABLE rather than omission on every branch below: a source we failed to
+    // hash must stay visible to lint, not vanish from the record. See UNREADABLE.
+    hashes["SKILL.md"] = fileSha256(resolve(ctx.skillDir, "SKILL.md")) ?? UNREADABLE;
+    for (const s of ctx.scenarios) {
+        hashes[SCENARIO_PREFIX + s.id] = scenarioDigest(s);
+        if (s.systemPromptFile && !(s.systemPromptFile in hashes)) {
+            hashes[s.systemPromptFile] = fileSha256(resolve(ctx.specDir, s.systemPromptFile)) ?? UNREADABLE;
+        }
+        // The post-test IS the gate on a post_test scenario, and it lives outside the
+        // fixture tree by convention (`fixture: fixtures/A1`, `post_test: post/A1.test.ts`),
+        // so neither the fixture digest nor the scenario digest — which holds only the
+        // path string — covers its contents. Tightening an assertion in it changes what
+        // the scorecard measured; without this it would change nothing lint can see.
+        const pt = s.assert?.post_test;
+        if (pt && !(pt in hashes)) {
+            hashes[pt] = fileSha256(isAbsolute(pt) ? pt : resolve(ctx.specDir, pt)) ?? UNREADABLE;
+        }
+        const fx = effectiveFixture(s);
+        if (fx && !(FIXTURE_PREFIX + fx in hashes)) {
+            hashes[FIXTURE_PREFIX + fx] = dirSha256(fixtureAbs(ctx.specDir, fx)) ?? UNREADABLE;
+        }
+    }
+    return hashes;
+}
+/**
+ * The current hash for a recorded key, or null when the source is gone.
+ *
+ * `undefined` is distinct from `null` and means "not comparable": the key names a
+ * scenario the spec no longer has. That is a spec *reshape*, not staleness — the
+ * same stance lint's scenario-set check already takes — so the caller stays quiet
+ * rather than reporting a removed scenario as a stale measurement.
+ *
+ * Sharing this resolver with `sourceHashes` is what keeps recording and checking
+ * from drifting: a new key kind is defined once, for both sides.
+ */
+export function currentHashFor(key, ctx) {
+    if (key === "SKILL.md")
+        return fileSha256(resolve(ctx.skillDir, "SKILL.md"));
+    if (key.startsWith(SCENARIO_PREFIX)) {
+        const id = key.slice(SCENARIO_PREFIX.length);
+        const s = ctx.scenarios.find((x) => x.id === id);
+        return s ? scenarioDigest(s) : undefined; // removed → reshape, not stale
+    }
+    if (key.startsWith(FIXTURE_PREFIX)) {
+        return dirSha256(fixtureAbs(ctx.specDir, key.slice(FIXTURE_PREFIX.length)));
+    }
+    // A prefixed key this version doesn't know is written by a NEWER skill-harness.
+    // Falling through to the path branch would resolve `agent:foo` as a filename,
+    // find nothing, and report a confident "agent:foo no longer exists" — a wrong
+    // finding about a source that is fine. Not comparable is the honest answer.
+    if (/^[a-z][a-z0-9-]*:/.test(key))
+        return undefined;
+    return fileSha256(resolve(ctx.specDir, key)); // system_prompt_file, post_test
+}
+/** Human label for a recorded key, used in lint messages. */
+export function describeSourceKey(key) {
+    if (key.startsWith(SCENARIO_PREFIX))
+        return `scenario \`${key.slice(SCENARIO_PREFIX.length)}\``;
+    if (key.startsWith(FIXTURE_PREFIX))
+        return `fixture \`${key.slice(FIXTURE_PREFIX.length)}\``;
+    return key;
+}
+/** The scenario id a key belongs to, for per-scenario lint findings. Undefined for skill-wide keys. */
+export function scenarioIdForKey(key, scenarios) {
+    if (key.startsWith(SCENARIO_PREFIX))
+        return key.slice(SCENARIO_PREFIX.length);
+    if (key.startsWith(FIXTURE_PREFIX)) {
+        const fx = key.slice(FIXTURE_PREFIX.length);
+        const owners = scenarios.filter((s) => effectiveFixture(s) === fx);
+        // Only attribute a shared fixture to a scenario when exactly one owns it —
+        // naming an arbitrary one of several would misdirect the re-run.
+        return owners.length === 1 ? owners[0].id : undefined;
+    }
+    return undefined;
+}
+//# sourceMappingURL=sources.js.map

package/dist/spec.d.ts

@@ -3,6 +3,21 @@ export type ScenarioMode = "inline" | "seeded";
 export interface SeededAssert {
     vitest?: boolean;
     diff_contains?: string[];
+    /**
+     * Needles that must NOT appear in the staged diff. The negative twin of
+     * diff_contains: it makes a scope-discipline requirement ("fix sliceRange, do
+     * not touch lastIndex") objective instead of something the judge has to infer
+     * from the model's prose.
+     */
+    diff_excludes?: string[];
+    /**
+     * A test file copied into the workspace AFTER the agent finishes, then run.
+     * The model never sees it, so it cannot write code shaped to pass it — this
+     * checks the behavior the task actually required. Orthogonal to `vitest`,
+     * which runs the model's OWN tests and therefore grades a claim the model
+     * gets to make about itself.
+     */
+    post_test?: string;
 }
 export interface Scenario {
     id: string;

package/dist/spec.js

@@ -158,8 +158,39 @@ export function parseSpec(text, file) {
                     if (!isStringArray(a.diff_contains)) {
                         throw new SpecError(`seeded scenario \`${id}\` \`assert.diff_contains\` must be strings`, file);
                     }
+                    if (a.diff_contains.some((n) => n === "")) {
+                        // Every string contains "", so an empty positive needle makes the gate
+                        // pass on ANY diff, including an empty one. This is the more dangerous
+                        // twin of the diff_excludes check below: that one fails forever and gets
+                        // investigated, this one passes forever and nobody ever looks.
+                        throw new SpecError(`seeded scenario \`${id}\` \`assert.diff_contains\` contains an empty string — it would match every diff, so the gate could never fail`, file);
+                    }
                     assertObj.diff_contains = a.diff_contains;
                 }
+                if (a.diff_excludes !== undefined) {
+                    if (!isStringArray(a.diff_excludes)) {
+                        throw new SpecError(`seeded scenario \`${id}\` \`assert.diff_excludes\` must be strings`, file);
+                    }
+                    if (a.diff_excludes.some((n) => n === "")) {
+                        // "" is in every string, so the gate could never pass — and the failure
+                        // would read as a mysterious diff problem rather than a spec typo.
+                        throw new SpecError(`seeded scenario \`${id}\` \`assert.diff_excludes\` contains an empty string — it would match every diff`, file);
+                    }
+                    assertObj.diff_excludes = a.diff_excludes;
+                }
+                // A needle required AND forbidden can never pass. Catching it here turns a
+                // scenario that always fails for an invisible reason into an authoring error.
+                const both = (assertObj.diff_contains ?? []).filter((n) => (assertObj.diff_excludes ?? []).includes(n));
+                if (both.length > 0) {
+                    throw new SpecError(`seeded scenario \`${id}\` lists ${both.map((n) => JSON.stringify(n)).join(", ")} in both ` +
+                        `\`assert.diff_contains\` and \`assert.diff_excludes\` — the gate could never pass`, file);
+                }
+                if (a.post_test !== undefined) {
+                    if (typeof a.post_test !== "string" || !a.post_test.trim()) {
+                        throw new SpecError(`seeded scenario \`${id}\` \`assert.post_test\` must be a non-empty path`, file);
+                    }
+                    assertObj.post_test = a.post_test.trim();
+                }
                 scenario.assert = assertObj;
             }
         }

package/dist/workspace.d.ts

@@ -6,6 +6,34 @@ export interface Workspace {
     cwd: string;
     cleanup(): void;
 }
+export declare const MARKERS: string[];
+/**
+ * Top-level directories in a fixture that claim to be markers but aren't one.
+ *
+ * A misspelled marker (`_uncommited/`) used to be copied into the baseline commit as a
+ * literal directory: the tree came up clean, the scenario silently measured the opposite
+ * of its intent, and nothing reported it. Any top-level `_name/` is therefore treated as
+ * a marker claim and must be a real one.
+ *
+ * The predicate is `_` followed by a LETTER, so `__tests__` and `__pycache__` — ordinary
+ * directories a fixture may legitimately contain — are not marker claims, and neither are
+ * oddities like `_2fa/` or `_-tmp/`, which no marker could plausibly be mistaken for.
+ * Nested `pkg/_staged/` is likewise ordinary content: markers are top-level only.
+ *
+ * Exported so `lint` can report the same set this module refuses to run. If the two
+ * disagreed, lint would hand out a clean bill of health for a fixture the runtime then
+ * rejects — which is worse than not checking at all.
+ */
+export declare function unknownMarkerDirs(src: string): string[];
+/**
+ * The known marker a misspelling was probably reaching for, or null.
+ *
+ * Case-insensitive within an edit distance of 2 — enough for `_uncommited` (one
+ * dropped `t`), `_Staged` (case) and `_uncommmitted` (doubled letter), while
+ * `_fixtures` or `_helpers` correctly suggest nothing rather than a confident
+ * wrong guess.
+ */
+export declare function suggestMarker(name: string): string | null;
 /**
  * Create an isolated temp-dir working directory for one scenario. `none` is an
  * empty dir (no git); `empty-git` initialises a clean repo; `{ fixture }` copies

package/dist/workspace.js

@@ -13,21 +13,64 @@ const GIT_TIMEOUT_MS = 30_000;
  */
 const UNCOMMITTED_DIR = "_uncommitted";
 const STAGED_DIR = "_staged";
-const MARKERS = [STAGED_DIR, UNCOMMITTED_DIR];
+export const MARKERS = [STAGED_DIR, UNCOMMITTED_DIR];
 /**
+ * Top-level directories in a fixture that claim to be markers but aren't one.
+ *
  * A misspelled marker (`_uncommited/`) used to be copied into the baseline commit as a
  * literal directory: the tree came up clean, the scenario silently measured the opposite
  * of its intent, and nothing reported it. Any top-level `_name/` is therefore treated as
  * a marker claim and must be a real one.
  *
- * Only a SINGLE leading underscore counts, so `__tests__` and `__pycache__` — ordinary
- * directories a fixture may legitimately contain — are not marker claims. Nested
- * `pkg/_staged/` is likewise ordinary content: markers are top-level only.
+ * The predicate is `_` followed by a LETTER, so `__tests__` and `__pycache__` — ordinary
+ * directories a fixture may legitimately contain — are not marker claims, and neither are
+ * oddities like `_2fa/` or `_-tmp/`, which no marker could plausibly be mistaken for.
+ * Nested `pkg/_staged/` is likewise ordinary content: markers are top-level only.
+ *
+ * Exported so `lint` can report the same set this module refuses to run. If the two
+ * disagreed, lint would hand out a clean bill of health for a fixture the runtime then
+ * rejects — which is worse than not checking at all.
  */
-function assertKnownMarkers(src) {
-    const suspects = readdirSync(src, { withFileTypes: true })
+export function unknownMarkerDirs(src) {
+    return readdirSync(src, { withFileTypes: true })
         .filter((e) => e.isDirectory() && /^_[A-Za-z]/.test(e.name) && !MARKERS.includes(e.name))
-        .map((e) => e.name);
+        .map((e) => e.name)
+        .sort();
+}
+/**
+ * The known marker a misspelling was probably reaching for, or null.
+ *
+ * Case-insensitive within an edit distance of 2 — enough for `_uncommited` (one
+ * dropped `t`), `_Staged` (case) and `_uncommmitted` (doubled letter), while
+ * `_fixtures` or `_helpers` correctly suggest nothing rather than a confident
+ * wrong guess.
+ */
+export function suggestMarker(name) {
+    let best = null;
+    let bestDistance = 3;
+    for (const m of MARKERS) {
+        const d = editDistance(name.toLowerCase(), m.toLowerCase());
+        if (d < bestDistance) {
+            bestDistance = d;
+            best = m;
+        }
+    }
+    return best;
+}
+/** Levenshtein distance, iterative single-row. */
+function editDistance(a, b) {
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const curr = [i];
+        for (let j = 1; j <= b.length; j++) {
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = curr;
+    }
+    return prev[b.length];
+}
+function assertKnownMarkers(src) {
+    const suspects = unknownMarkerDirs(src);
     if (suspects.length > 0) {
         throw new Error(`fixture ${src}: unknown marker director${suspects.length > 1 ? "ies" : "y"} ` +
             `${suspects.map((s) => `\`${s}/\``).join(", ")} — known markers are ` +

package/package.json

@@ -1,19 +1,45 @@
 {
     "name": "@skill-harness/core",
-    "version": "0.2.1",
+    "version": "0.3.1",
     "description": "skill-harness engine — spec, discover, run, LLM-judge grade, score, results (internal API)",
     "type": "module",
     "license": "MIT",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
-    "exports": { ".": "./dist/index.js" },
-    "keywords": ["agent-skills", "skill", "llm", "testing", "eval", "grading", "pi", "ci", "harness"],
-    "files": ["dist/**/*.js", "dist/**/*.d.ts", "LICENSE", "README.md"],
-    "repository": { "type": "git", "url": "git+https://github.com/mojomanyana/skill-harness.git" },
-    "publishConfig": { "access": "public" },
-    "engines": { "node": ">=20" },
+    "exports": {
+        ".": "./dist/index.js"
+    },
+    "keywords": [
+        "agent-skills",
+        "skill",
+        "llm",
+        "testing",
+        "eval",
+        "grading",
+        "pi",
+        "ci",
+        "harness"
+    ],
+    "files": [
+        "dist/**/*.js",
+        "dist/**/*.d.ts",
+        "LICENSE",
+        "README.md"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/mojomanyana/skill-harness.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "engines": {
+        "node": ">=20"
+    },
     "scripts": {
         "prepack": "cp ../../LICENSE ./LICENSE"
     },
-    "dependencies": { "js-yaml": "^4.1.0" }
+    "dependencies": {
+        "js-yaml": "^4.1.0"
+    }
 }