@skill-harness/core 0.5.0 → 0.7.0

package/dist/seeded.js

@@ -160,13 +160,37 @@ export function capDiff(diff, maxBytes = DIFF_MAX_BYTES) {
  */
 export async function runSeeded(scenario, opts) {
     const repo = opts.cwd;
-    const harnessOut = await opts.adapter.run({
+    const req = {
         skillDir: opts.skillDir,
         model: opts.model,
         mode: opts.mode,
         turns: scenario.turns,
         cwd: repo,
-    });
+        // Resolved against the spec dir, exactly like fixtures and post-tests.
+        extensions: scenario.extensions?.map((e) => resolve(opts.specDir, e)),
+    };
+    // 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 harnessOut;
+    if (opts.trace) {
+        if (!opts.adapter.runStructured) {
+            throw new Error(`scenario \`${opts.trace.scenarioId}\` declares \`assert.trace\`, but the \`${opts.adapter.name}\` adapter` +
+                ` cannot produce execution traces — the gate would have no evidence to read.`);
+        }
+        const structured = await opts.adapter.runStructured({
+            ...req,
+            scenarioId: opts.trace.scenarioId,
+            rep: opts.trace.rep,
+        });
+        harnessOut = structured.transcript;
+        traces = structured.traces;
+    }
+    else {
+        harnessOut = await opts.adapter.run(req);
+    }
     const parts = [harnessOut, "", "=== SEEDED GATES ==="];
     let gateFailure = null;
     const runVitest = opts.runVitest ??
@@ -189,7 +213,7 @@ 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);
+        return finish(parts, gateFailure, diff, traces);
     }
     // 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
@@ -257,7 +281,7 @@ export async function runSeeded(scenario, opts) {
                 parts.push(`  post_test: ERROR (${msg})`);
                 if (!gateFailure)
                     gateFailure = msg;
-                return finish(parts, gateFailure, diff);
+                return finish(parts, gateFailure, diff, traces);
             }
             const v = await runVitest([POST_TEST_BASE], repo);
             const out = `${v.stdout}\n${v.stderr}`;
@@ -306,7 +330,7 @@ export async function runSeeded(scenario, opts) {
                 gateFailure = problem;
         }
     }
-    return finish(parts, gateFailure, diff);
+    return finish(parts, gateFailure, diff, traces);
 }
 function git(cwd, args) {
     return exec("git", args, { cwd, timeoutMs: 30_000 });
@@ -340,13 +364,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) {
+function finish(parts, gateFailure, diff, traces = []) {
     // 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 };
+    return { transcript: parts.join("\n"), gateFailure, diff, traces };
 }
 /**
  * Parse vitest's `Tests  N passed | M skipped (T)` summary line.

package/dist/sources.d.ts

@@ -172,5 +172,31 @@ export declare function describeSourceKey(key: string): string;
  * in place. Naming the actual remedy is what converts that into a free command.
  */
 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";
+/**
+ * Every recorded key whose drift could change THIS scenario's verdict — excluding the
+ * two skill-wide ones (`SKILL.md`, `rubric:__persona`), which callers handle
+ * separately because they move every scenario at once.
+ *
+ * Written for run-over-run comparison (see stability.ts): "did these two runs ask this
+ * scenario the same question, judged by the same rubric?" is answerable from the
+ * recorded hashes, and only if you know which keys belong to the scenario. Derived
+ * from the spec rather than from the key strings, because the path-shaped keys
+ * (`system_prompt_file`, `post_test`) carry no scenario id at all.
+ *
+ * `policy:<id>` is deliberately NOT here. Its `reps`/`pass_threshold` half is already
+ * compared as an *aggregation* shape (1 draw vs a majority of 3 is the comparison a
+ * hash cannot express), and its `critical` half changes whether a verdict can block a
+ * ship, never what the verdict is. Including it would report a critical-set edit as
+ * "these runs measured different things", which is false.
+ *
+ * Both key generations are returned: 0.4.0+ runs carry the split facet keys, older
+ * ones the combined `scenario:<id>`. A caller comparing two runs must not treat a
+ * combined digest and a split one as comparable — they hash different byte layouts —
+ * so it compares only keys BOTH runs recorded, and treats "no shared key" as
+ * unverifiable rather than unchanged.
+ */
+export declare function scenarioSourceKeys(s: Scenario): 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

@@ -167,24 +167,50 @@ function walk(dir, prefix = "") {
  * transcripts are actually invalid.
  */
 function facets(s) {
-    const { id, title, critical, mode, turns, checklist, fixture, assert, workspace, remote, systemPromptFile, reps, passThreshold, ...restScenario } = s;
+    const { id, title, critical, mode, turns, checklist, fixture, assert, traceAssert, workspace, remote, systemPromptFile, extensions, reps, passThreshold, covers: _coversIsMetadata, ...restScenario } = s;
     const _scenarioExhaustive = restScenario;
     void _scenarioExhaustive;
+    // `covers` is destructured into a discard on purpose, and this comment is the
+    // decision the guard demanded: it belongs to NO digest. It records which
+    // instruction sections a scenario is declared to exercise, which changes what
+    // `--affected` selects next time — not what any past run measured. Bucketing it
+    // anywhere would charge a re-run (or at best a re-score) for editing a label,
+    // which is the exact trap the facet split was built to remove.
+    void _coversIsMetadata;
     const { vitest, diff_contains, diff_excludes, post_test, ...restAssert } = assert ?? {};
     const _assertExhaustive = restAssert;
     void _assertExhaustive;
-    const hasGates = diff_contains !== undefined || diff_excludes !== undefined;
+    // `traceAssert` is a GATE, not stimulus: it is evaluated against a trace the run
+    // 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;
     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
         // diff. (`post_test`'s CONTENTS get their own file-path key, hashed separately.)
+        // `extensions` is STIMULUS, not a gate — note the asymmetry with `traceAssert`
+        // below. Changing which extensions load changes what the model can DO, so the
+        // old transcripts describe a different agent and only a re-run can answer.
+        // Changing an assertion only changes what we conclude from evidence already on
+        // disk, which `regate` can redo for free.
+        // APPENDED CONDITIONALLY, never as a fixed slot. This tuple is positional and
+        // its hash is stored in every published results.yaml, so adding an
+        // unconditional element re-hashes every scenario that never used the field —
+        // measured: 62 real lint findings became 261 across the reference corpus, all of
+        // them demanding paid re-runs for scenarios nobody had edited.
         stimulus: JSON.stringify([
             id, mode, turns, workspace, remote, systemPromptFile ?? null,
             fixture ?? null, vitest ?? null, post_test ?? null,
+            ...(extensions ? [extensions] : []),
         ]),
         rubric: JSON.stringify([id, title, checklist]),
         policy: JSON.stringify([id, critical, reps ?? null, passThreshold ?? null]),
-        gates: hasGates ? JSON.stringify([id, diff_contains ?? null, diff_excludes ?? null]) : 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] : [])])
+            : null,
     };
 }
 function sha(canonical) {
@@ -281,6 +307,15 @@ export function sourceHashes(ctx) {
         if (s.systemPromptFile && !(s.systemPromptFile in hashes)) {
             hashes[s.systemPromptFile] = fileSha256(resolve(ctx.specDir, s.systemPromptFile)) ?? UNREADABLE;
         }
+        // Extension CONTENTS, not just the paths the stimulus digest already covers.
+        // An orchestration scenario's subagent tool lives in these files: editing one
+        // changes what the model could do without changing a single character of the
+        // spec, which is precisely the drift the staleness gate exists to catch.
+        for (const ext of s.extensions ?? []) {
+            if (ext in hashes)
+                continue;
+            hashes[ext] = fileSha256(resolve(ctx.specDir, ext)) ?? 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
@@ -390,6 +425,50 @@ export function remedyForKey(key) {
     }
     return "re-run"; // stimulus:, SKILL.md, fixture:, agent files, post_test contents
 }
+/** The skill-text key. Skill-wide: it belongs to every scenario at once. */
+export const SKILL_KEY = "SKILL.md";
+/**
+ * Every recorded key whose drift could change THIS scenario's verdict — excluding the
+ * two skill-wide ones (`SKILL.md`, `rubric:__persona`), which callers handle
+ * separately because they move every scenario at once.
+ *
+ * Written for run-over-run comparison (see stability.ts): "did these two runs ask this
+ * scenario the same question, judged by the same rubric?" is answerable from the
+ * recorded hashes, and only if you know which keys belong to the scenario. Derived
+ * from the spec rather than from the key strings, because the path-shaped keys
+ * (`system_prompt_file`, `post_test`) carry no scenario id at all.
+ *
+ * `policy:<id>` is deliberately NOT here. Its `reps`/`pass_threshold` half is already
+ * compared as an *aggregation* shape (1 draw vs a majority of 3 is the comparison a
+ * hash cannot express), and its `critical` half changes whether a verdict can block a
+ * ship, never what the verdict is. Including it would report a critical-set edit as
+ * "these runs measured different things", which is false.
+ *
+ * Both key generations are returned: 0.4.0+ runs carry the split facet keys, older
+ * ones the combined `scenario:<id>`. A caller comparing two runs must not treat a
+ * combined digest and a split one as comparable — they hash different byte layouts —
+ * so it compares only keys BOTH runs recorded, and treats "no shared key" as
+ * unverifiable rather than unchanged.
+ */
+export function scenarioSourceKeys(s) {
+    const keys = [
+        STIMULUS_PREFIX + s.id,
+        RUBRIC_PREFIX + s.id,
+        SCENARIO_PREFIX + s.id, // legacy combined (pre-0.4.0 runs)
+    ];
+    if (gatesDigest(s) !== null)
+        keys.push(GATES_PREFIX + s.id);
+    if (s.systemPromptFile)
+        keys.push(s.systemPromptFile); // the agent file IS the stimulus
+    for (const ext of s.extensions ?? [])
+        keys.push(ext); // an edited extension is new stimulus
+    if (s.assert?.post_test)
+        keys.push(s.assert.post_test); // its contents are the gate
+    const fx = effectiveFixture(s);
+    if (fx)
+        keys.push(FIXTURE_PREFIX + fx);
+    return keys;
+}
 /** The scenario id a key belongs to, for per-scenario lint findings. Undefined for skill-wide keys. */
 export function scenarioIdForKey(key, scenarios) {
     if (key === PERSONA_KEY)

package/dist/spec-write.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The single choke point for appending a scenario to an existing
+ * `specification.yaml`.
+ *
+ * Two callers need this — `add-test` and capture promotion — and a second
+ * implementation is how they would drift into disagreeing about what a valid
+ * write is. Everything here is deliberately append-shaped: a spec is
+ * hand-authored and full of comments, and a round trip through
+ * `yaml.load`/`yaml.dump` would silently reformat it and drop every comment the
+ * author wrote. So the existing bytes are never re-serialized — the new block is
+ * concatenated onto them and the *result* is validated before anything is
+ * written.
+ */
+/** Thrown when the spec on disk moved between the caller reading it and writing. */
+export declare class ConcurrentSpecModification extends Error {
+    constructor(specPath: string);
+}
+/** Thrown when the scenario being appended collides with one already in the spec. */
+export declare class DuplicateScenarioId extends Error {
+    constructor(id: string, specPath: string);
+}
+/** SHA-256 of spec text. Callers hold one across a read→confirm→write cycle. */
+export declare function specSha256(text: string): string;
+/**
+ * Render one scenario as a YAML block that can be concatenated onto a spec.
+ *
+ * Dumps `{ scenarios: [scenario] }` and strips the top-level key, leaving the
+ * correctly-indented list item. Going through `yaml.dump` rather than string
+ * templating is what makes arbitrary user text — quotes, colons, newlines,
+ * leading dashes — safe to embed.
+ */
+export declare function renderScenarioBlock(scenario: Record<string, unknown>): string;
+export interface AppendScenarioOptions {
+    specPath: string;
+    /** Plain object in spec field order; serialized by `renderScenarioBlock`. */
+    scenario: Record<string, unknown>;
+    /**
+     * SHA-256 the caller last saw. When supplied and the file no longer matches,
+     * the append is refused rather than layered onto someone else's edit.
+     */
+    baseSha256?: string;
+}
+export interface AppendScenarioResult {
+    id: string;
+    /** SHA-256 of the spec AFTER the append — the caller's new baseline. */
+    sha256: string;
+    /** The block that was appended, for preview/echo. */
+    block: string;
+}
+/**
+ * Validate and atomically append a scenario.
+ *
+ * Order matters and is load-bearing: read → detect concurrent modification →
+ * reject duplicate id → build → **validate the merged text** → write. The
+ * validation is on the merged result, not the block alone, because a block that
+ * parses in isolation can still break the file it lands in.
+ *
+ * The write is temp-file-plus-rename rather than `appendFileSync`. An append
+ * interrupted partway through leaves a syntactically broken spec on disk; a
+ * rename either happened or did not.
+ */
+export declare function appendScenario(opts: AppendScenarioOptions): AppendScenarioResult;

package/dist/spec-write.js

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import yaml from "js-yaml";
+import { parseSpec } from "./spec.js";
+/**
+ * The single choke point for appending a scenario to an existing
+ * `specification.yaml`.
+ *
+ * Two callers need this — `add-test` and capture promotion — and a second
+ * implementation is how they would drift into disagreeing about what a valid
+ * write is. Everything here is deliberately append-shaped: a spec is
+ * hand-authored and full of comments, and a round trip through
+ * `yaml.load`/`yaml.dump` would silently reformat it and drop every comment the
+ * author wrote. So the existing bytes are never re-serialized — the new block is
+ * concatenated onto them and the *result* is validated before anything is
+ * written.
+ */
+/** Thrown when the spec on disk moved between the caller reading it and writing. */
+export class ConcurrentSpecModification extends Error {
+    constructor(specPath) {
+        super(`${specPath} changed on disk since it was read — refusing to append. ` +
+            `Re-read the spec and retry; appending now would validate against a file that no longer exists.`);
+        this.name = "ConcurrentSpecModification";
+    }
+}
+/** Thrown when the scenario being appended collides with one already in the spec. */
+export class DuplicateScenarioId extends Error {
+    constructor(id, specPath) {
+        super(`scenario id \`${id}\` already exists in ${specPath}`);
+        this.name = "DuplicateScenarioId";
+    }
+}
+/** SHA-256 of spec text. Callers hold one across a read→confirm→write cycle. */
+export function specSha256(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/**
+ * Render one scenario as a YAML block that can be concatenated onto a spec.
+ *
+ * Dumps `{ scenarios: [scenario] }` and strips the top-level key, leaving the
+ * correctly-indented list item. Going through `yaml.dump` rather than string
+ * templating is what makes arbitrary user text — quotes, colons, newlines,
+ * leading dashes — safe to embed.
+ */
+export function renderScenarioBlock(scenario) {
+    const dumped = yaml.dump({ scenarios: [scenario] }, { lineWidth: -1, noRefs: true });
+    return "\n" + dumped.replace(/^scenarios:\n/, "");
+}
+/**
+ * Validate and atomically append a scenario.
+ *
+ * Order matters and is load-bearing: read → detect concurrent modification →
+ * reject duplicate id → build → **validate the merged text** → write. The
+ * validation is on the merged result, not the block alone, because a block that
+ * parses in isolation can still break the file it lands in.
+ *
+ * The write is temp-file-plus-rename rather than `appendFileSync`. An append
+ * interrupted partway through leaves a syntactically broken spec on disk; a
+ * rename either happened or did not.
+ */
+export function appendScenario(opts) {
+    const { specPath, scenario, baseSha256 } = opts;
+    const current = readFileSync(specPath, "utf8");
+    if (baseSha256 !== undefined && specSha256(current) !== baseSha256) {
+        throw new ConcurrentSpecModification(specPath);
+    }
+    const id = scenario.id;
+    if (typeof id !== "string" || id.trim() === "") {
+        throw new Error("scenario needs a non-empty string `id`");
+    }
+    const existing = parseSpec(current, specPath);
+    if (existing.scenarios.some((s) => s.id === id)) {
+        throw new DuplicateScenarioId(id, specPath);
+    }
+    const block = renderScenarioBlock(scenario);
+    const merged = current + block;
+    parseSpec(merged, specPath); // throws if the append broke the spec
+    atomicWrite(specPath, merged);
+    return { id, sha256: specSha256(merged), block };
+}
+/**
+ * Write via a sibling temp file and rename.
+ *
+ * Sibling, not `/tmp`: `rename(2)` is only atomic within a filesystem, and a
+ * cross-device rename would silently degrade to copy-then-delete — exactly the
+ * torn write this exists to prevent.
+ */
+function atomicWrite(path, text) {
+    const tmp = join(dirname(path), `.${Date.now()}-${process.pid}.specwrite.tmp`);
+    try {
+        writeFileSync(tmp, text, "utf8");
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // Best effort: the original file is untouched either way, and masking the
+            // real failure with a cleanup error would hide why the write failed.
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=spec-write.js.map

package/dist/spec.d.ts

@@ -1,4 +1,5 @@
 import type { WorkspaceKind } from "./workspace.js";
+import { type TraceAssert } from "./trace-gates.js";
 export type ScenarioMode = "inline" | "seeded";
 export interface SeededAssert {
     vitest?: boolean;
@@ -28,9 +29,37 @@ export interface Scenario {
     checklist: string[];
     fixture?: string;
     assert?: SeededAssert;
+    /**
+     * Objective assertions over the execution trace.
+     *
+     * Deliberately NOT part of `SeededAssert`: the other gates read a staged git
+     * diff and are meaningless without a fixture, while a trace exists for any run.
+     * Declaring it opts the scenario into structured (`--mode json`) execution.
+     */
+    traceAssert?: TraceAssert;
     workspace: WorkspaceKind;
     remote: boolean;
     systemPromptFile?: string;
+    /**
+     * `env.extensions`: pi extension files to load, resolved relative to the spec dir.
+     *
+     * Loading is CLOSED, not additive — the adapter passes `--no-extensions` plus one
+     * `--extension` per entry, so exactly these load and nothing discovered does.
+     * (Measured on pi 0.83.0: that flag pair isolates even under `-a` project-local
+     * trust.) Without it, whatever the developer happened to have installed would
+     * silently become part of the test.
+     */
+    extensions?: string[];
+    /**
+     * `covers`: instruction sections this scenario is declared to exercise, e.g.
+     * `SKILL.md#core-principle`.
+     *
+     * METADATA. It stales nothing — see `sources.ts`, where it is deliberately in
+     * no digest. A `covers` edit changes which tests `--affected` selects, not what
+     * any past run measured, so charging a re-run for it would be the exact
+     * "pay tokens to fix a label" trap the facet split exists to remove.
+     */
+    covers?: string[];
     reps?: number;
     passThreshold?: number;
 }

package/dist/spec.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import yaml from "js-yaml";
+import { parseTraceAssert } from "./trace-gates.js";
 /** Thrown on any validation failure. Message always carries the spec file path. */
 export class SpecError extends Error {
     constructor(message, file) {
@@ -54,6 +55,34 @@ function resolveWorkspace(env, mode, fixture, id, file) {
     }
     throw new SpecError(`scenario \`${id}\` env.workspace must be none | empty-git | fixture:<path>`, file);
 }
+/**
+ * Resolve `env.extensions` into a list of paths.
+ *
+ * Incompatible with `system_prompt_file` by construction: that flag REPLACES the
+ * system prompt to test a subagent definition in isolation, while an
+ * orchestration scenario tests the PARENT that delegates to one. Allowing both
+ * would silently test neither — the parent's instructions would be gone.
+ */
+function resolveExtensions(env, hasSystemPrompt, id, file) {
+    const raw = env && typeof env === "object" ? env.extensions : undefined;
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new SpecError(`scenario \`${id}\` env.extensions must be a non-empty list of paths`, file);
+    }
+    const paths = raw.map((p, i) => {
+        if (typeof p !== "string" || p.trim() === "") {
+            throw new SpecError(`scenario \`${id}\` env.extensions[${i}] must be a non-empty path`, file);
+        }
+        return p.trim();
+    });
+    if (hasSystemPrompt) {
+        throw new SpecError(`scenario \`${id}\` sets both env.extensions and system_prompt_file — ` +
+            `system_prompt_file replaces the system prompt to test a subagent in isolation, ` +
+            `while env.extensions tests the parent that delegates to one. Pick one.`, file);
+    }
+    return paths;
+}
 /**
  * Resolve `env.remote`. A remote needs a repo to attach to, so it is only meaningful
  * with empty-git or a fixture — asking for one on a bare cwd is an authoring mistake,
@@ -144,6 +173,12 @@ export function parseSpec(text, file) {
             workspace: "none",
             remote: false,
         };
+        // `assert.trace` is legal for inline AND seeded scenarios — it reads the
+        // execution trace, which every run produces, not a staged diff.
+        const rawAssert = s.assert;
+        if (rawAssert?.trace !== undefined) {
+            scenario.traceAssert = parseTraceAssert(rawAssert.trace, `${file}: scenario \`${id}\``);
+        }
         if (mode === "seeded") {
             if (typeof s.fixture !== "string" || s.fixture.length === 0) {
                 throw new SpecError(`seeded scenario \`${id}\` requires a \`fixture\` path`, file);
@@ -208,6 +243,26 @@ export function parseSpec(text, file) {
             }
             scenario.systemPromptFile = s.system_prompt_file.trim();
         }
+        if (s.covers !== undefined) {
+            if (!isStringArray(s.covers) || s.covers.length === 0) {
+                throw new SpecError(`scenario \`${id}\` \`covers\` must be a non-empty list of strings`, file);
+            }
+            const bad = s.covers.find((c) => c.trim() === "");
+            if (bad !== undefined)
+                throw new SpecError(`scenario \`${id}\` \`covers\` has an empty entry`, file);
+            scenario.covers = s.covers.map((c) => c.trim());
+        }
+        // `unchanged_paths` is checked against the workspace's git state, so a scenario
+        // with no repo has nothing to observe. Refused here — free and offline — rather
+        // than at run time, because the alternative shipped for a while: the assertion
+        // silently passed against an empty change list and reported a green safety gate.
+        if (scenario.traceAssert?.unchanged_paths?.length && scenario.workspace === "none") {
+            throw new SpecError(`scenario \`${id}\` declares \`assert.trace.unchanged_paths\` but has no workspace to observe — ` +
+                `set \`env.workspace: empty-git\` or \`fixture:<path>\`, or drop the assertion. ` +
+                `A path policy with nothing to compare against would pass unconditionally.`, file);
+        }
+        // After system_prompt_file, so the incompatibility check sees the resolved value.
+        scenario.extensions = resolveExtensions(s.env, scenario.systemPromptFile !== undefined, id, file);
         if (s.reps !== undefined) {
             if (typeof s.reps !== "number" || !Number.isInteger(s.reps) || s.reps < 1) {
                 throw new SpecError(`scenario \`${id}\` \`reps\` must be a positive integer`, file);