@skill-harness/core 0.7.0 → 0.9.0

package/dist/sandbox.js

@@ -0,0 +1,12 @@
+export async function withSandbox(backend, request, run) {
+    const session = await backend.prepare(request);
+    try {
+        const value = await run(session);
+        const diff = await session.captureDiff();
+        return { value, diff, backend: backend.name, containment: backend.containment };
+    }
+    finally {
+        await session.cleanup();
+    }
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/score.d.ts

@@ -22,12 +22,14 @@ export interface ScoreResult {
     criticalFails: number;
     bSeriesFails: number;
     suspectCount: number;
+    errorCount: number;
     note: string;
 }
 export declare function letterFor(pct: number): string;
 /**
  * Score a set of green-mode verdicts against the ship bar. A scenario PASSes only
- * on verdict PASS; FAIL and ERROR both count against it. A `suspect` verdict (an
+ * on verdict PASS; FAIL is behavioral, while ERROR/JUDGE-AMBIGUOUS are excluded as
+ * infrastructure/indeterminate and independently block SHIP. A `suspect` verdict (an
  * unresolved judge misfire) is excluded from both `passed` and `total` — it is
  * untrustworthy, neither a pass nor a fail — and any suspect count blocks SHIP
  * until an author override resolves it. SHIP otherwise requires: enough total

package/dist/score.js

@@ -11,7 +11,8 @@ export function letterFor(pct) {
 }
 /**
  * Score a set of green-mode verdicts against the ship bar. A scenario PASSes only
- * on verdict PASS; FAIL and ERROR both count against it. A `suspect` verdict (an
+ * on verdict PASS; FAIL is behavioral, while ERROR/JUDGE-AMBIGUOUS are excluded as
+ * infrastructure/indeterminate and independently block SHIP. A `suspect` verdict (an
  * unresolved judge misfire) is excluded from both `passed` and `total` — it is
  * untrustworthy, neither a pass nor a fail — and any suspect count blocks SHIP
  * until an author override resolves it. SHIP otherwise requires: enough total
@@ -25,11 +26,16 @@ export function score(verdicts, input) {
     let criticalFails = 0;
     let bSeriesFails = 0;
     let suspectCount = 0;
+    let errorCount = 0;
     for (const v of verdicts) {
         if (v.suspect) {
             suspectCount++;
             continue; // untrustworthy: neither pass nor fail
         }
+        if (v.verdict === "ERROR" || v.verdict === "JUDGE-AMBIGUOUS") {
+            errorCount++;
+            continue; // infrastructure/indeterminate: neither behavioral pass nor fail
+        }
         total++;
         if (v.verdict === "PASS") {
             passed++;
@@ -42,21 +48,30 @@ export function score(verdicts, input) {
     }
     const pct = total > 0 ? Math.round((passed * 100) / total) : 0;
     const letter = letterFor(pct);
-    const ship = total >= shipBar.total &&
+    const validBar = Number.isInteger(shipBar.total) && shipBar.total >= 1 && Number.isInteger(shipBar.min_pass) && shipBar.min_pass >= 1 && shipBar.min_pass <= shipBar.total;
+    const ship = validBar &&
+        total >= shipBar.total &&
         passed >= shipBar.min_pass &&
         (!shipBar.no_critical_fail || criticalFails === 0) &&
         bSeriesFails === 0 &&
-        suspectCount === 0;
+        suspectCount === 0 &&
+        errorCount === 0;
     let note = "";
-    if (suspectCount > 0) {
+    if (!validBar) {
+        note = "invalid ship bar: total/min_pass must be positive integers with min_pass <= total";
+    }
+    else if (suspectCount > 0) {
         note = `${suspectCount} suspect: re-judge/resolve`;
     }
+    else if (errorCount > 0) {
+        note = `${errorCount} infrastructure error${errorCount === 1 ? "" : "s"}: retry/repair evidence`;
+    }
     else if (criticalFails > 0) {
         note = `gated: ${criticalFails} critical fail${criticalFails === 1 ? "" : "s"}`;
     }
     else if (bSeriesFails > 0) {
         note = `gated: ${bSeriesFails} B-series fail${bSeriesFails === 1 ? "" : "s"}`;
     }
-    return { passed, total, pct, letter, ship, criticalFails, bSeriesFails, suspectCount, note };
+    return { passed, total, pct, letter, ship, criticalFails, bSeriesFails, suspectCount, errorCount, note };
 }
 //# sourceMappingURL=score.js.map

package/dist/seeded.d.ts

@@ -1,5 +1,6 @@
 import type { Scenario } from "./spec.js";
 import type { ExecutionTraceV1 } from "./capture-trace-types.js";
+import type { TrajectoryEventV1 } from "./trajectory-gates.js";
 import type { HarnessAdapter, ModelRef, RunMode } from "./adapters/types.js";
 import { type ExecResult } from "./util/exec.js";
 interface SeededOpts {
@@ -42,9 +43,14 @@ export type VitestRun = ExecResult;
 export interface SeededOutcome {
     transcript: string;
     gateFailure: string | null;
+    gateError: string | null;
     diff: string;
-    /** One per turn; empty unless the scenario declared `assert.trace`. */
+    /** One per turn; empty unless structured execution was requested. */
     traces: ExecutionTraceV1[];
+    /** Adapter-neutral workflow/tool events for assert.trajectory. */
+    events: TrajectoryEventV1[];
+    /** Required native sources that could not be read or normalized. */
+    eventErrors: string[];
 }
 /**
  * The added/removed lines of a unified diff — what the model actually *changed*,

package/dist/seeded.js

@@ -168,12 +168,15 @@ export async function runSeeded(scenario, opts) {
         cwd: repo,
         // Resolved against the spec dir, exactly like fixtures and post-tests.
         extensions: scenario.extensions?.map((e) => resolve(opts.specDir, e)),
+        eventSources: scenario.eventSources,
     };
     // A trace-gated seeded scenario runs through the structured path so the tool
     // calls are recorded; everything downstream (gates, diff, transcript) is
     // identical, because the rebuilt transcript is what print mode would have
     // emitted anyway.
     let traces = [];
+    let events = [];
+    let eventErrors = [];
     let harnessOut;
     if (opts.trace) {
         if (!opts.adapter.runStructured) {
@@ -187,12 +190,15 @@ export async function runSeeded(scenario, opts) {
         });
         harnessOut = structured.transcript;
         traces = structured.traces;
+        events = structured.events ?? [];
+        eventErrors = structured.eventErrors ?? [];
     }
     else {
         harnessOut = await opts.adapter.run(req);
     }
     const parts = [harnessOut, "", "=== SEEDED GATES ==="];
     let gateFailure = null;
+    let gateError = null;
     const runVitest = opts.runVitest ??
         ((args, cwd) => exec("npx", ["vitest", "run", ...args], { cwd, timeoutMs: VITEST_TIMEOUT_MS }));
     // `exec` never throws on a non-zero exit and, on timeout, SIGKILLs the child and
@@ -213,7 +219,8 @@ export async function runSeeded(scenario, opts) {
             (gitFailure.stderr.trim() ? `: ${gitFailure.stderr.trim().split("\n")[0]}` : "");
         parts.push(`  staged diff: ERROR (${msg})`);
         gateFailure = msg;
-        return finish(parts, gateFailure, diff, traces);
+        gateError = msg;
+        return finish(parts, gateFailure, gateError, diff, traces, events, eventErrors);
     }
     // BOTH needle gates read the changed lines only, never context. A unified diff
     // carries three lines of context per hunk, so an untouched symbol near the edit
@@ -241,10 +248,14 @@ export async function runSeeded(scenario, opts) {
             ? `  vitest run: ERROR (timed out after ${VITEST_TIMEOUT_MS}ms — infrastructure, not model behavior)`
             : `  vitest run: ${passed ? "PASS" : `FAIL (exit ${v.code})`}`);
         parts.push(indent(bothStreams(v)));
-        if (!passed && !gateFailure) {
-            gateFailure = killed
+        if (!passed) {
+            const problem = killed
                 ? `vitest timed out after ${VITEST_TIMEOUT_MS}ms — infrastructure, not model behavior`
                 : `vitest failed (exit ${v.code})`;
+            if (!gateFailure)
+                gateFailure = problem;
+            if (killed)
+                gateError = problem;
         }
     }
     const postTest = scenario.assert?.post_test;
@@ -263,6 +274,7 @@ export async function runSeeded(scenario, opts) {
             parts.push(`  post_test: ERROR (${msg})`);
             if (!gateFailure)
                 gateFailure = msg;
+            gateError = msg;
         }
         else {
             // `.test` is part of the name we build, never taken from the source: extname()
@@ -281,7 +293,8 @@ export async function runSeeded(scenario, opts) {
                 parts.push(`  post_test: ERROR (${msg})`);
                 if (!gateFailure)
                     gateFailure = msg;
-                return finish(parts, gateFailure, diff, traces);
+                gateError = msg;
+                return finish(parts, gateFailure, gateError, diff, traces, events, eventErrors);
             }
             const v = await runVitest([POST_TEST_BASE], repo);
             const out = `${v.stdout}\n${v.stderr}`;
@@ -300,13 +313,17 @@ export async function runSeeded(scenario, opts) {
             const notCollected = /^\s*No test files found/im.test(out);
             const killed = v.code === null;
             let problem = null;
+            let problemIsError = false;
             if (killed) {
+                problemIsError = true;
                 problem = `post_test ${JSON.stringify(postTest)} timed out after ${VITEST_TIMEOUT_MS}ms — infrastructure, not model behavior`;
             }
             else if (notCollected) {
+                problemIsError = true;
                 problem = `post_test ${JSON.stringify(postTest)} was never collected by vitest — spec/fixture error, not model behavior`;
             }
             else if (tally === null) {
+                problemIsError = true;
                 problem = `post_test ${JSON.stringify(postTest)} produced no parseable vitest summary (exit ${v.code}) — cannot confirm it ran`;
             }
             else if (v.code !== 0 || tally.failed > 0) {
@@ -317,20 +334,24 @@ export async function runSeeded(scenario, opts) {
                 problem = `post_test ${JSON.stringify(postTest)} failed (exit ${v.code})`;
             }
             else if (tally.skipped > 0 || tally.todo > 0) {
+                problemIsError = true;
                 problem = `post_test ${JSON.stringify(postTest)} has ${tally.skipped + tally.todo} skipped/todo test(s) — a hidden gate must actually run; spec error, not model behavior`;
             }
             else if (tally.passed === 0) {
+                problemIsError = true;
                 problem = `post_test ${JSON.stringify(postTest)} ran no assertions — spec error, not model behavior`;
             }
             parts.push(problem === null
                 ? `  post_test ${JSON.stringify(postTest)}: PASS (${tally.passed} assertion-bearing test(s))`
-                : `  post_test ${JSON.stringify(postTest)}: ${v.code === 0 && !killed ? "ERROR" : "FAIL"} (${problem})`);
+                : `  post_test ${JSON.stringify(postTest)}: ${problemIsError ? "ERROR" : "FAIL"} (${problem})`);
             parts.push(indent(bothStreams(v)));
             if (problem && !gateFailure)
                 gateFailure = problem;
+            if (problem && problemIsError)
+                gateError = problem;
         }
     }
-    return finish(parts, gateFailure, diff, traces);
+    return finish(parts, gateFailure, gateError, diff, traces, events, eventErrors);
 }
 function git(cwd, args) {
     return exec("git", args, { cwd, timeoutMs: 30_000 });
@@ -364,13 +385,13 @@ function bothStreams(v) {
     return o || e;
 }
 /** Append the staged diff and return the outcome. Every exit path goes through here, so the judge always sees the same sections in the same order. */
-function finish(parts, gateFailure, diff, traces = []) {
+function finish(parts, gateFailure, gateError, diff, traces = [], events = [], eventErrors = []) {
     // The code itself, last — the gates above only prove that keywords appeared.
     // Without this section a seeded checklist item about what the code *does* is
     // graded from the model's own description of its work.
     parts.push("", "=== STAGED DIFF ===");
     parts.push(diff.trim() === "" ? "  (empty — the model left no staged changes)" : capDiff(diff));
-    return { transcript: parts.join("\n"), gateFailure, diff, traces };
+    return { transcript: parts.join("\n"), gateFailure, gateError, diff, traces, events, eventErrors };
 }
 /**
  * Parse vitest's `Tests  N passed | M skipped (T)` summary line.

package/dist/sources.d.ts

@@ -174,6 +174,56 @@ export declare function describeSourceKey(key: string): string;
 export declare function remedyForKey(key: string): string;
 /** The skill-text key. Skill-wide: it belongs to every scenario at once. */
 export declare const SKILL_KEY = "SKILL.md";
+/**
+ * The model-visible digests of the two prompt documents a run delivers: the skill text
+ * and any `system_prompt_file`. They measure what the model RECEIVES, where the bare
+ * keys above (`SKILL.md`, `<agent path>`) measure the file's raw bytes.
+ *
+ * | key | contents |
+ * |---|---|
+ * | `skill:prompt` | SKILL.md's body + its model-visible frontmatter |
+ * | `prompt:<path>` | the same, for one `system_prompt_file` |
+ *
+ * Both are prefixed, so a skill-harness OLDER than this one reads them through
+ * `currentHashFor`'s unknown-prefix guard and reports "not comparable" rather than a
+ * confident wrong finding about a source that is fine.
+ */
+export declare const SKILL_PROMPT_KEY = "skill:prompt";
+export declare const PROMPT_PREFIX = "prompt:";
+/**
+ * The digest of a prompt document: its body verbatim, plus every frontmatter field the
+ * model can actually receive.
+ *
+ * The gate exists to protect published claims, so "the current text" has to mean the text
+ * the model was given. Hashing the raw bytes — which is what shipped through 0.7.0 —
+ * charged a full re-run for edits no graded run could observe: measured on the reference
+ * corpus, adding one `allowed-tools:` key to seven SKILL.md files with byte-identical
+ * bodies took lint from 2 findings to 22, and 20 of those demanded paid re-waves.
+ *
+ * Versioned in the hashed tuple (`prompt-doc/1`) because this is a stored-hash format: if
+ * the rule for "model-visible" ever changes, the tag changes with it and old digests stay
+ * legible as what they were.
+ */
+export declare function promptDocDigest(text: string): string;
+/** `promptDocDigest` of a file, or null when it doesn't exist / isn't readable. */
+export declare function promptDocDigestOfFile(path: string): string | null;
+/**
+ * True when `key` is a raw-bytes key whose model-visible counterpart THIS RUN also
+ * recorded — in which case the counterpart is the honest comparison and the raw-bytes one
+ * must be skipped.
+ *
+ * Both keys keep being written, and this is why: an older skill-harness reading a newer
+ * results.yaml still finds the bare `SKILL.md` key and keeps checking it, and `restamp`
+ * needs the raw-bytes hash as the proof it upgrades from. Superseding at COMPARISON time
+ * rather than dropping the key at record time is what buys both.
+ *
+ * `UNREADABLE` on EITHER side supersedes nothing. If the counterpart is unreadable there
+ * is nothing better to compare against; and if the raw-bytes key itself is unreadable, the
+ * run never verified that document at all — a fact lint must keep reporting, since the
+ * one thing this module refuses to do is let an unhashed source drop out of checking for
+ * the life of a result.
+ */
+export declare function isSupersededKey(key: string, recorded: Record<string, string>): boolean;
 /**
  * Every recorded key whose drift could change THIS scenario's verdict — excluding the
  * two skill-wide ones (`SKILL.md`, `rubric:__persona`), which callers handle

package/dist/sources.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { readFileSync, readdirSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
+import yaml from "js-yaml";
 /**
  * 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.
@@ -167,7 +168,7 @@ function walk(dir, prefix = "") {
  * transcripts are actually invalid.
  */
 function facets(s) {
-    const { id, title, critical, mode, turns, checklist, fixture, assert, traceAssert, workspace, remote, systemPromptFile, extensions, reps, passThreshold, covers: _coversIsMetadata, ...restScenario } = s;
+    const { id, title, critical, mode, turns, checklist, fixture, assert, traceAssert, trajectoryAssert, workspace, remote, systemPromptFile, extensions, eventSources, reps, passThreshold, covers: _coversIsMetadata, ...restScenario } = s;
     const _scenarioExhaustive = restScenario;
     void _scenarioExhaustive;
     // `covers` is destructured into a discard on purpose, and this comment is the
@@ -184,7 +185,7 @@ function facets(s) {
     // already saved, so `regate` (free) can re-answer it without re-running the model.
     // Note the asymmetry with `env.extensions` in Phase 3, which IS stimulus — one
     // changes what gets executed, the other only what we conclude from it.
-    const hasGates = diff_contains !== undefined || diff_excludes !== undefined || traceAssert !== undefined;
+    const hasGates = diff_contains !== undefined || diff_excludes !== undefined || traceAssert !== undefined || trajectoryAssert !== undefined;
     return {
         // `vitest` and the `post_test` PATH are stimulus, not gates: both change what the
         // run executes in the workspace, and neither can be re-evaluated from a saved
@@ -203,13 +204,21 @@ function facets(s) {
             id, mode, turns, workspace, remote, systemPromptFile ?? null,
             fixture ?? null, vitest ?? null, post_test ?? null,
             ...(extensions ? [extensions] : []),
+            // Event-source paths choose which native ledgers are captured. A saved
+            // normalized artifact cannot answer for a source that was never collected,
+            // so changing this is stimulus and needs a re-run.
+            ...(eventSources ? [eventSources] : []),
         ]),
         rubric: JSON.stringify([id, title, checklist]),
         policy: JSON.stringify([id, critical, reps ?? null, passThreshold ?? null]),
         // Same rule as `stimulus` above: conditional, so a needle-gated scenario that
         // declares no trace assertions keeps the digest it was published with.
         gates: hasGates
-            ? JSON.stringify([id, diff_contains ?? null, diff_excludes ?? null, ...(traceAssert ? [traceAssert] : [])])
+            ? JSON.stringify([
+                id, diff_contains ?? null, diff_excludes ?? null,
+                ...(traceAssert ? [traceAssert] : []),
+                ...(trajectoryAssert ? [trajectoryAssert] : []),
+            ])
             : null,
     };
 }
@@ -292,7 +301,12 @@ 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;
+    // Two digests of one file, and both are load-bearing. `SKILL.md` is the raw bytes,
+    // kept so an older skill-harness reading this record still has the key it knows and so
+    // `restamp` has a proof to upgrade from; `skill:prompt` is the text the model actually
+    // receives, and is the one lint compares (see `isSupersededKey`).
+    hashes[SKILL_KEY] = fileSha256(resolve(ctx.skillDir, "SKILL.md")) ?? UNREADABLE;
+    hashes[SKILL_PROMPT_KEY] = promptDocDigestOfFile(resolve(ctx.skillDir, "SKILL.md")) ?? UNREADABLE;
     hashes[PERSONA_KEY] = personaDigest(ctx.judgePersona);
     for (const s of ctx.scenarios) {
         // Split, not combined: each facet's drift has a different cheapest remedy, and a
@@ -304,8 +318,13 @@ export function sourceHashes(ctx) {
         const gates = gatesDigest(s);
         if (gates !== null)
             hashes[GATES_PREFIX + s.id] = gates;
+        // An agent file is a prompt document too, delivered with `--append-system-prompt`,
+        // and its `tools:` header is read by the harness rather than the model — so it gets
+        // the same pair of digests, for the same reasons, as SKILL.md above.
         if (s.systemPromptFile && !(s.systemPromptFile in hashes)) {
-            hashes[s.systemPromptFile] = fileSha256(resolve(ctx.specDir, s.systemPromptFile)) ?? UNREADABLE;
+            const abs = resolve(ctx.specDir, s.systemPromptFile);
+            hashes[s.systemPromptFile] = fileSha256(abs) ?? UNREADABLE;
+            hashes[PROMPT_PREFIX + s.systemPromptFile] = promptDocDigestOfFile(abs) ?? UNREADABLE;
         }
         // Extension CONTENTS, not just the paths the stimulus digest already covers.
         // An orchestration scenario's subagent tool lives in these files: editing one
@@ -344,8 +363,16 @@ export function sourceHashes(ctx) {
  * from drifting: a new key kind is defined once, for both sides.
  */
 export function currentHashFor(key, ctx) {
-    if (key === "SKILL.md")
+    if (key === SKILL_KEY)
         return fileSha256(resolve(ctx.skillDir, "SKILL.md"));
+    if (key === SKILL_PROMPT_KEY)
+        return promptDocDigestOfFile(resolve(ctx.skillDir, "SKILL.md"));
+    // Before the unknown-prefix guard below, which would otherwise swallow these as keys
+    // from a newer skill-harness. A deleted agent file must still resolve to null ("gone"),
+    // not undefined ("not comparable").
+    if (key.startsWith(PROMPT_PREFIX)) {
+        return promptDocDigestOfFile(resolve(ctx.specDir, key.slice(PROMPT_PREFIX.length)));
+    }
     if (key === PERSONA_KEY)
         return personaDigest(ctx.judgePersona);
     // Facet keys, and the legacy combined key, all resolve per scenario id. A removed
@@ -383,6 +410,13 @@ export function currentHashFor(key, ctx) {
 export function describeSourceKey(key) {
     if (key === PERSONA_KEY)
         return "the judge persona";
+    // Deliberately the same label as the raw-bytes key: only one of the pair is ever
+    // compared (see `isSupersededKey`), and a reader of a lint finding cares which FILE
+    // moved, not which of two digests of it was the one consulted.
+    if (key === SKILL_PROMPT_KEY)
+        return SKILL_KEY;
+    if (key.startsWith(PROMPT_PREFIX))
+        return key.slice(PROMPT_PREFIX.length);
     if (key.startsWith(STIMULUS_PREFIX))
         return `the stimulus for \`${key.slice(STIMULUS_PREFIX.length)}\``;
     if (key.startsWith(RUBRIC_PREFIX))
@@ -427,6 +461,149 @@ export function remedyForKey(key) {
 }
 /** The skill-text key. Skill-wide: it belongs to every scenario at once. */
 export const SKILL_KEY = "SKILL.md";
+/**
+ * The model-visible digests of the two prompt documents a run delivers: the skill text
+ * and any `system_prompt_file`. They measure what the model RECEIVES, where the bare
+ * keys above (`SKILL.md`, `<agent path>`) measure the file's raw bytes.
+ *
+ * | key | contents |
+ * |---|---|
+ * | `skill:prompt` | SKILL.md's body + its model-visible frontmatter |
+ * | `prompt:<path>` | the same, for one `system_prompt_file` |
+ *
+ * Both are prefixed, so a skill-harness OLDER than this one reads them through
+ * `currentHashFor`'s unknown-prefix guard and reports "not comparable" rather than a
+ * confident wrong finding about a source that is fine.
+ */
+export const SKILL_PROMPT_KEY = "skill:prompt";
+export const PROMPT_PREFIX = "prompt:";
+/**
+ * Frontmatter keys the model never receives: capability declarations the HARNESS
+ * consumes to build a tool allowlist.
+ *
+ * Why a denylist and not an allowlist of "body + description". An allowlist makes the
+ * safe-looking choice the dangerous one: the day a harness starts putting some new
+ * frontmatter key in context, every published number silently stops being protected and
+ * nothing says so. A denylist fails the other way — a newly-invented inert key charges
+ * one unnecessary re-run until it is named here, which is a one-line patch and a visible
+ * complaint. This module already takes that side everywhere else (see `UNREADABLE`, and
+ * the unknown-prefix guard in `currentHashFor`): a blind spot is the worst outcome, and
+ * a false alarm is merely expensive.
+ *
+ * `tools` and `allowed-tools` are the two spellings of the same ceiling in the reference
+ * corpus. Both are read by pi/pi-daddy to build a `--tools` allowlist; neither is ever
+ * rendered into the model's context.
+ */
+const CAPABILITY_KEYS = new Set(["allowed-tools", "tools"]);
+/** Opening `---` on line 1 only — a `---` further down is a horizontal rule. */
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+/** A prompt document split into its frontmatter text (null when it has none) and its body. */
+function splitPromptDoc(text) {
+    const m = FRONTMATTER_RE.exec(text);
+    // Unterminated frontmatter falls through to "all body", the same call
+    // instruction-coverage.ts makes: treat the whole file as content rather than lose it.
+    return m ? { frontmatter: m[1], body: text.slice(m[0].length) } : { frontmatter: null, body: text };
+}
+/**
+ * Parsed YAML in a stable shape: object keys sorted, string scalars trimmed.
+ *
+ * Trimmed because YAML block style is not stimulus — `description: >` clips a trailing
+ * newline that `description: <text>` does not, so an author refolding a paragraph the
+ * model receives identically would otherwise be charged a re-run.
+ */
+function canonicalValue(v) {
+    if (typeof v === "string")
+        return v.trim();
+    if (Array.isArray(v))
+        return v.map(canonicalValue);
+    if (v && typeof v === "object") {
+        return Object.entries(v)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, val]) => [k, canonicalValue(val)]);
+    }
+    return v;
+}
+/**
+ * The frontmatter a run can observe, canonically. Built from the PARSED YAML for the
+ * same reason the scenario digests are built from the parsed scenario: reindenting or
+ * reordering keys changes no stimulus and must not read as a change.
+ *
+ * Unparseable frontmatter is hashed VERBATIM rather than dropped. Dropping it would mean
+ * a file whose frontmatter is malformed quietly loses that half of its protection — and
+ * a malformed header is exactly when an author is most likely to be mid-edit.
+ */
+function modelVisibleFrontmatter(fm) {
+    if (fm === null)
+        return null;
+    let parsed;
+    try {
+        parsed = yaml.load(fm);
+    }
+    catch {
+        return ["unparsed", fm];
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return ["unparsed", fm];
+    return [
+        "parsed",
+        Object.entries(parsed)
+            .filter(([k]) => !CAPABILITY_KEYS.has(k))
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => [k, canonicalValue(v)]),
+    ];
+}
+/**
+ * The digest of a prompt document: its body verbatim, plus every frontmatter field the
+ * model can actually receive.
+ *
+ * The gate exists to protect published claims, so "the current text" has to mean the text
+ * the model was given. Hashing the raw bytes — which is what shipped through 0.7.0 —
+ * charged a full re-run for edits no graded run could observe: measured on the reference
+ * corpus, adding one `allowed-tools:` key to seven SKILL.md files with byte-identical
+ * bodies took lint from 2 findings to 22, and 20 of those demanded paid re-waves.
+ *
+ * Versioned in the hashed tuple (`prompt-doc/1`) because this is a stored-hash format: if
+ * the rule for "model-visible" ever changes, the tag changes with it and old digests stay
+ * legible as what they were.
+ */
+export function promptDocDigest(text) {
+    const { frontmatter, body } = splitPromptDoc(text);
+    return sha(JSON.stringify(["prompt-doc/1", modelVisibleFrontmatter(frontmatter), body]));
+}
+/** `promptDocDigest` of a file, or null when it doesn't exist / isn't readable. */
+export function promptDocDigestOfFile(path) {
+    try {
+        return promptDocDigest(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when `key` is a raw-bytes key whose model-visible counterpart THIS RUN also
+ * recorded — in which case the counterpart is the honest comparison and the raw-bytes one
+ * must be skipped.
+ *
+ * Both keys keep being written, and this is why: an older skill-harness reading a newer
+ * results.yaml still finds the bare `SKILL.md` key and keeps checking it, and `restamp`
+ * needs the raw-bytes hash as the proof it upgrades from. Superseding at COMPARISON time
+ * rather than dropping the key at record time is what buys both.
+ *
+ * `UNREADABLE` on EITHER side supersedes nothing. If the counterpart is unreadable there
+ * is nothing better to compare against; and if the raw-bytes key itself is unreadable, the
+ * run never verified that document at all — a fact lint must keep reporting, since the
+ * one thing this module refuses to do is let an unhashed source drop out of checking for
+ * the life of a result.
+ */
+export function isSupersededKey(key, recorded) {
+    if (key === SKILL_PROMPT_KEY || key.startsWith(PROMPT_PREFIX))
+        return false;
+    if (recorded[key] === UNREADABLE)
+        return false;
+    const upgraded = key === SKILL_KEY ? SKILL_PROMPT_KEY : PROMPT_PREFIX + key;
+    const v = recorded[upgraded];
+    return v !== undefined && v !== UNREADABLE;
+}
 /**
  * Every recorded key whose drift could change THIS scenario's verdict — excluding the
  * two skill-wide ones (`SKILL.md`, `rubric:__persona`), which callers handle
@@ -458,8 +635,10 @@ export function scenarioSourceKeys(s) {
     ];
     if (gatesDigest(s) !== null)
         keys.push(GATES_PREFIX + s.id);
-    if (s.systemPromptFile)
+    if (s.systemPromptFile) {
         keys.push(s.systemPromptFile); // the agent file IS the stimulus
+        keys.push(PROMPT_PREFIX + s.systemPromptFile); // ...as the model receives it
+    }
     for (const ext of s.extensions ?? [])
         keys.push(ext); // an edited extension is new stimulus
     if (s.assert?.post_test)

package/dist/spec.d.ts

@@ -1,5 +1,6 @@
 import type { WorkspaceKind } from "./workspace.js";
 import { type TraceAssert } from "./trace-gates.js";
+import { type TrajectoryAssert } from "./trajectory-gates.js";
 export type ScenarioMode = "inline" | "seeded";
 export interface SeededAssert {
     vitest?: boolean;
@@ -20,6 +21,14 @@ export interface SeededAssert {
      */
     post_test?: string;
 }
+export interface TrajectoryEventSource {
+    /** Native format adapter registered by the harness adapter. */
+    adapter: "normalized-v1" | "principal-assurance-v1" | "pi-daddy-v1";
+    /** Workspace-relative file/glob. Never an absolute path or traversal. */
+    path: string;
+    /** Missing evidence is an error by default; false is for optional supplemental ledgers. */
+    required: boolean;
+}
 export interface Scenario {
     id: string;
     title: string;
@@ -37,6 +46,10 @@ export interface Scenario {
      * Declaring it opts the scenario into structured (`--mode json`) execution.
      */
     traceAssert?: TraceAssert;
+    /** Objective assertions over adapter-neutral, versioned workflow events. */
+    trajectoryAssert?: TrajectoryAssert;
+    /** Native event/ledger files the harness normalizes after execution. */
+    eventSources?: TrajectoryEventSource[];
     workspace: WorkspaceKind;
     remote: boolean;
     systemPromptFile?: string;
@@ -69,6 +82,8 @@ export interface ShipBar {
     no_critical_fail: boolean;
 }
 export interface Spec {
+    /** Specification schema. Omitted YAML is read as v1 for 0.8 compatibility. */
+    schema?: 1;
     skill: string;
     judge_persona: string;
     ship_bar: ShipBar;