wicked-garden 12.43.0 → 12.44.0

package/.claude-plugin/marketplace.json

@@ -1 +1 @@
-{"name": "wicked-garden", "owner": {"name": "Mike Parcewski"}, "plugins": [{"name": "wicked-garden", "source": "./", "description": "Your coding agent already plans and swarms \u2014 Wicked Garden is the curated toolkit for what it can't: proof-not-claims gates, code links grep can't see, deterministic refactor, cross-session memory, real multi-model second opinions. Don't fight the harness; fill its gaps. The gate needs wicked-vault (a self-contained infra peer, installed directly) and re-derives through garden's built-in engine; estate/bus are opt-in layers (wicked-testing and wicked-brain are retired \u2014 QE ships in-catalog as the qe domain, memory lives in wicked-estate).", "version": "12.43.0"}], "version": "12.43.0"}
+{"name": "wicked-garden", "owner": {"name": "Mike Parcewski"}, "plugins": [{"name": "wicked-garden", "source": "./", "description": "Your coding agent already plans and swarms \u2014 Wicked Garden is the curated toolkit for what it can't: proof-not-claims gates, code links grep can't see, deterministic refactor, cross-session memory, real multi-model second opinions. Don't fight the harness; fill its gaps. The gate needs wicked-vault (a self-contained infra peer, installed directly) and re-derives through garden's built-in engine; estate/bus are opt-in layers (wicked-testing and wicked-brain are retired \u2014 QE ships in-catalog as the qe domain, memory lives in wicked-estate).", "version": "12.44.0"}], "version": "12.44.0"}

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-garden",
-  "version": "12.43.0",
+  "version": "12.44.0",
   "description": "Your coding agent's harness already plans and swarms; Wicked Garden is the curated toolkit for what it can't do alone. Proof, not claims \u2014 gates re-derive 'done' through the internal loom engine (fail-closed, independently attested via wicked-vault), so a self-asserted pass can't lie its way green. Relationships grep can't see \u2014 the wicked-estate code graph + injected bus/dispatch/capability/archetype edges power blast-radius & lineage. Plus deterministic multi-file refactor (wicked-patch), cross-session memory + knowledge (the mem domain over wicked-estate), real multi-model second opinions (jam:council), portable expertise as on-demand skill-refs, and evidence-gated testing (the in-catalog qe domain). It reads the shape of your work to apply the right rigor \u2014 steering, not a pipeline \u2014 then gets out of the way. The compiler stamps a self-contained evidence gate into any repo that runs with no wicked-garden installed. Don't fight the harness; fill its gaps. The evidence gate requires wicked-vault, a self-contained infra peer wicked-garden installs directly; wicked-bus is an opt-in layer \u2014 install what you'll use, the toolkit works without the rest.",
   "wicked_vault_version": "^0.5.0",
   "wicked_ledger_version": "^0.4.0",

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [12.44.0] — 2026-10-08
+
+### Added
+- **`mcp-scaffold`: the `openapi` and `install` actions (DES-mcp-server-workflow rev 2, slice 2 of 2).** `scripts/mcp/openapi.py` turns an OpenAPI 3 document into the server's `tools.json` through wicked-crew's conversion service — `POST /api/v1/mcp/servers/preview` with `{name, kind: "rest", url, openapiUrl | openapi, operations?}` at `--crew-url`, else `$WICKED_CREW_URL`, else `http://127.0.0.1:7701` — writing `{"source": {specUrl|specFile, baseUrl, convertedAt}, "tools": [{name, description, inputSchema, annotations, class, rest}], "skipped": [...]}` and setting `baseUrl` in `mcp-server.config.json`; it refuses to overwrite generated tools, never sends a `secret`/`auth` key, exits 1 carrying the daemon's refusal and exits 2 when no daemon answers ("write the tools by hand (branch B)") — it never invents tools. `scripts/mcp/install.py` installs or updates the built server for running, idempotent by the config's `key`: it locates the one `mcp-server.config.json` (`--from-run` under `$WICKED_TREE`, or `--dir`), builds and stages `dist/` + manifests into `<root>/<key>/next/` (`~/.wicked/mcp-servers` unless `--install-root`/`$WICKED_MCP_INSTALL_ROOT`; `--from-npm <pkg>@<ver>` installs a published package instead), smokes it with `probe.py --env <SERVER>_TOKEN` (a failure naming that variable is `pending_credential`, disclosed; any other failure exits 1 with `current/` untouched), swaps `current/` → `previous/` and `next/` → `current/` so the command `node <root>/<key>/current/dist/server.js` never changes, registers it in crew's MCP registry with `auth: {ref: "env:<SERVER>_TOKEN"}` — the one-secret contract: a reference the daemon resolves, never a value (`secret_missing` → `registered: false` with both remedies; no daemon → the reason; an existing key → `registered: "updated"`), writes the operator's CLI MCP configs only through `wicked-installer mcp upsert` (an installer without the verb is reported as skipped), and records `<root>/<key>/installed.json` `{key, version, source, command, args, envNames, installedAt, registered, smoke}`. `--uninstall <key>` deletes the registration, the CLI entries and the root. Exit 0 staged, 1 staging/smoke/registry failure, 2 bad arguments. The skill gains both actions, the `mcp-server` workflow's per-phase guide (scope, source-discovery, design, build, install) and the "Use when" phrases; the core router row is now `scaffold · openapi · probe · install`. Tests: `tests/mcp/test_mcp_openapi.py`, `tests/mcp/test_mcp_install.py` (stub `npm` and `wicked-installer` on PATH, a local http.server as the daemon, a real smoke probe).
+- **`mcp-scaffold`: a TypeScript server template, now the default (`scaffold.py --lang typescript`; DES-mcp-server-workflow rev 2, slice 1 of 2).** `skills/mcp-scaffold/assets/typescript/` is a whole project: fastmcp 4 on Node >= 22, loglayer (OpenTelemetry plugin, redaction by name, a console transport bound to stderr — stdout carries protocol frames only — and a request-scoped child logger through `AsyncLocalStorage`), OpenTelemetry through `@opentelemetry/sdk-node` (spans `mcp.tool.call` and `http.client.request`, instruments `mcp.tool.calls`/`mcp.tool.duration`/`mcp.tool.errors`; the OTLP trace, metric and log exporters are armed only when `OTEL_EXPORTER_OTLP_ENDPOINT` is set, otherwise nothing leaves the process), and authentication on every tool (`canAccess`; httpStream refuses a request without `MCP_SERVER_BEARER` with 401). The server reads ONE secret, `<SERVER>_TOKEN` (bearer token, API key, basic password or OAuth2 client secret, as the scheme says) — the one variable crew's broker and registry inject — and fails at startup naming it; every non-secret parameter lives in the committed `mcp-server.config.json` (`key`, `version`, `transport`, `baseUrl`, `auth`, `rateLimitPerMin`). `defineTool` wraps each tool in the span, the child logger, the instruments and a per-tool token bucket; `src/tools/generated.ts` registers every `tools.json` entry (the conversion service's output) with annotations derived from its class, calling `src/rest.ts`, which pins scheme/host/port/base path, sends allowlisted arguments only, never follows a redirect, refuses auth and hop-by-hop headers from arguments and retries 429/5xx for read tools only. `npm test` builds and runs a stdio conformance smoke (initialize, tools/list, tools/call; a missing secret exits non-zero naming the variable; httpStream 401) and a per-tool contract-test shape. Every `.ts` file starts with an SPDX line. `scaffold.py` copies the directory stamping the name, its env prefix and the year; `--out` may be an existing directory, but every file it would write must be absent — it refuses naming the first collision and writes nothing. `node` and `python` stay as the dependency-free one-file templates. `probe.py --env NAME` passes exactly that variable through to the server (never printed) and, on a failure, reports only which of those names the server's stderr mentioned (`stderrNames`). The skill gains the skeleton's contract and a "Steering this server follows" checklist (MCPS-1001…1007, sourced from wicked-core's `governance/packs/mcp-server`). Tests: `tests/mcp/test_mcp_scaffold.py` (default lang, stamping, SPDX, no secret values, scaffold into a populated dir, collision refusal, `--env` passthrough; the npm install/build/lint/test/probe end-to-end behind `WICKED_GARDEN_E2E_NPM=1`).
+
+### Changed
+- **Governed-worker floor: foreground evidence, tool debris under the notes root, verdict scope (wicked-garden#1229, #1223).** New **C6**: no turn ends with tasks pending — the done-when recipe runs in order in the foreground with each command and exit code pasted; "running in the background" is never a closing line (three creator attempts in run ad5a4ca7 ended that way, F35). New **C7**: reporter output, coverage, screenshots, logs and scratch files go under the unit's notes root (`$WICKED_NOTES_ROOT` or the path the brief names), never in the repository — pass the tool's output flag or delete the file before the turn ends (S17b left a 2.3 MB `.vitest/json/output.json` in the worktree; crew's deliver skip-list, wicked-crew#861, is the backstop). **C2** now reads: a failure called pre-existing cites its run on the base tree (command + exit code) or it is a failure. New **E3**: every verdict item is in scope unless a human ruling strikes it by name (companion to wicked-core#760). Provenance rows added; `tests/test_governed_worker_rules.py` pins the text.
+
+### Fixed
+- **Walkthrough: the `lint` action the `walkthrough_plan` pin calls now exists, and `record` reads the storyline the author wrote (wicked-garden#1231, the garden half of wicked-core#753).** The engine pins `walkthrough_plan` to `"${WICKED_GARDEN_ROOT}/scripts/wicked-garden" run scripts/demo/walkthrough.mjs lint --root "${WICKED_EVIDENCE_ROOT}"`, but `walkthrough.mjs` accepted only `record|seal` and exited 2 with usage — so every walkthrough was denied, storyline or not. `lint --root <author dir>` (new `scripts/demo/walkthrough-lint.mjs`, DES-walkthrough-proof §4.5) imports `<author dir>/storyline.mjs`, prints `{ok, storyline, chapters, checks, findings: [{rule, where, detail}]}` and exits 0 only with no finding (1 with any, 2 on a usage error; `--root` defaults to `$WICKED_EVIDENCE_ROOT`). It refuses: a missing or unloadable storyline; an empty plan; `baseUrl` other than `"fixture"`; a `fixture.start` that is not a plain argv, runs inline code (`-e`, `-c`, `--eval`, ...), names an absolute path or `..`, or (with `--tree <dir>`) a script the tree does not hold; a secret-shaped `fixture.env` name; a chapter without `proves` step ids (with `--steps a,b`, ids outside the plan), without a `locator` (on_screen) check, without a `probe`/`artifact` (state) check, or without a `join` (cross_check) of the two; a walkthrough without a `guard` (must_not_happen) check; unknown check kinds, a locator without a selector, a probe not in `fixture.probes`, an artifact path escaping `DATA_DIR`, a join not naming two earlier checks; a `verify` that is not `jq_pred` or that `jq` rejects; and a check with no `negative` sample or whose verifier PASSES one of its samples (a tautology; run through `jq -e` exactly as the vault does, failing closed without `jq`). `record` took its storyline from `<dirname(WICKED_EVIDENCE_ROOT)>/author/<WICKED_RUN_UNIT>/` — the unit **ordinal** — so a storyline written where the engine said was reported "storyline not found"; it now reads `--storyline`, else `$WICKED_WALKTHROUGH_AUTHOR/storyline.mjs` (the author dir wicked-core's `record_launch` hands it), and with neither refuses `storyline_refused` naming both. The demo skill gains a walkthrough-author section and `refs/walkthrough-author.md` (where the file goes, every rule id, a passing example the tests lint). Tests: `tests/demo/test_walkthrough_lint.py` (27: a clean pass, the exact pinned launcher command, one per rule, the documented example, a storyline that throws while read still gets a report), `tests/demo/test_walkthrough.py` (4: the author dir is read with an ordinal `WICKED_RUN_UNIT`, a missing author storyline names its path, no source refuses by name, the unjailed result lists the author storyline's chapters). The record tool does not yet re-run the lint before recording (§4.4 step 1); that follows separately.
+- **`mcp-scaffold` TypeScript template: the conformance smoke no longer times out on a loaded host.** Loading fastmcp and the OpenTelemetry SDK can take well over 10 s when the machine is busy; the stdio exchange now waits up to 60 s, the httpStream readiness poll up to 60 s, `testTimeout` is 90 s, and the npm end-to-end test (`WICKED_GARDEN_E2E_NPM=1`) probes with `--timeout 30`.
+- **CI no longer installs the retired `wicked-loom` package; the trust-spine tests need only node + wicked-vault (closes the wicked-garden#1132 residual).** Loom runs in-process (`scripts/loom/`, absorbed from wicked-loom), but `.github/workflows/test.yml` still ran `npm i -g wicked-vault wicked-loom` and `tests/qe/test_prove.py` / `tests/e2e/test_e2e_gate_cli.py` skipped (or, under `WICKED_REQUIRE_E2E=1`, failed) unless a `wicked-loom` binary was on PATH — and then pinned `WICKED_LOOM_BIN` to it, so CI exercised the deprecated external binary instead of the in-process gate garden ships. The tests now require node + a resolvable vault only, pass `WICKED_LOOM_BIN` through only when the caller set it, and CI installs `wicked-vault` alone. `docs/cross-cli-skill-format.md` no longer describes the deleted cross-CLI baseline or its `--write-baseline` flag, and the repo's agent guide (`.claude/CLAUDE.md`) no longer calls wicked-loom a required peer. Proof: `WICKED_REQUIRE_E2E=1 python3 -m pytest tests/qe/test_prove.py tests/e2e/test_e2e_gate_cli.py` → 17 passed with only `wicked-vault` on PATH.
+
 ## [12.43.0] — 2026-10-05
 
 ### Fixed
@@ -980,7 +994,8 @@ through `v9.2.18`. Major themes across that span:
 
 For each of those releases, see the corresponding tag in git history.
 
-[Unreleased]: https://github.com/mikeparcewski/wicked-garden/compare/v12.43.0...HEAD
+[Unreleased]: https://github.com/mikeparcewski/wicked-garden/compare/v12.44.0...HEAD
+[12.44.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.43.0...v12.44.0
 [12.43.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.42.0...v12.43.0
 [12.42.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.41.0...v12.42.0
 [12.41.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.40.0...v12.41.0

package/docs/cross-cli-skill-format.md

@@ -4,8 +4,8 @@ wicked-garden is installed into Claude Code, Codex, OpenCode, Pi and Antigravity
 parties and snapshotted by wicked-crew for every seat. Only Claude Code reads Claude Code's
 plugin frontmatter — so a skill's identity, dispatch shape and prose must not depend on it.
 This page is the format; `scripts/_skill_meta.py` is its one reader; the lint
-(`tests/test_skill_portability.py`) enforces it; `tests/cross_cli_baseline.json` lists what
-still has to be translated (12.37.x batches; the strict release deletes the baseline).
+(`tests/test_skill_portability.py`) enforces it, strictly: the 12.37.x translation batches are
+done and the baseline they burned down was deleted (B18), so every hit fails.
 
 ## Frontmatter: the closed key set
 
@@ -75,8 +75,8 @@ generically instead.
 
 ## Products and size
 
-`wicked-testing`, `wicked-brain`, `wicked-signals` are retired and `wicked-loom` is being replaced — the skill TEXT retires the `wicked-loom` reference ahead of the peer itself (`wicked-loom` stays the prove gate's CI peer in `test.yml` / `tests/qe/test_prove.py` until the prove/loom-cutover seam removes it; DES-L6 B6 / review F3) —
-by the in-process gate — name their successors (the `qe` domain, wicked-estate through the `mem` /
+`wicked-testing`, `wicked-brain`, `wicked-signals` are retired and `wicked-loom` was replaced (CI no longer installs it; DES-L6 B6 / review F3)
+by the in-process gate (`scripts/loom/`) — name their successors (the `qe` domain, wicked-estate through the `mem` /
 `search` skills, the built-in gate) or mark the line `<!-- historical -->` (`retired-product-ref`).
 A SKILL.md stays under 500 lines and 24 KiB (`skill-too-large`; `scripts/ci/validate.py` applies
 the same bound to routers and modules); detail goes in `refs/`. Skill-relative paths, the
@@ -84,9 +84,7 @@ the same bound to routers and modules); detail goes in `refs/`. Skill-relative p
 
 ## Tooling
 
-- `python3 tests/test_skill_portability.py` — the report (0 violations, 0 stale baseline entries).
-- `python3 tests/test_skill_portability.py --write-baseline` — regenerate the baseline **at B0
-  only**; afterwards the file only shrinks (a batch deletes the entries it translated; a stale entry
-  fails CI; B18 deletes the file).
+- `python3 tests/test_skill_portability.py` — the report (0 violations). There is no baseline: it
+  was deleted at B18 and `test_cross_cli_baseline_is_gone` fails if one comes back.
 - `python3 scripts/ci/validate.py && python3 scripts/_validate_registry.py` — the release gate,
   role-aware.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-garden",
-  "version": "12.43.0",
+  "version": "12.44.0",
   "type": "module",
   "description": "Curated toolkit for what AI coding agents can't do alone: evidence-gated work, codegraph relationships, deterministic multi-file refactor, multi-model second opinions, and cross-session memory. Installs as a Claude Code plugin.",
   "keywords": [

package/scripts/demo/walkthrough-lint.mjs

@@ -0,0 +1,248 @@
+// Walkthrough storyline lint (DES-walkthrough-proof §4.5; wicked-garden#1231).
+//
+//   wicked-garden run scripts/demo/walkthrough.mjs lint --root <author dir> [--storyline <path>]
+//                                                       [--tree <dir>] [--steps <id,id,...>]
+//
+// The `walkthrough_plan` step's pinned validator runs this against the author dir the engine hands it
+// (wicked-core `WALKTHROUGH_LINT_SCRIPT`: `--root "${WICKED_EVIDENCE_ROOT}"`, where that root is
+// `<evidence root>/author/<plan step>`). It reads `<root>/storyline.mjs`, prints one JSON object
+// `{ok, storyline, chapters, checks, findings: [{rule, where, detail}]}` on stdout and exits 0 only when
+// there is no finding; 1 when there is at least one; 2 on a usage error.
+//
+// A check's `kind` is the record tool's collector (`runCollector` in walkthrough.mjs). The DES's check
+// classes map onto them: locator = on_screen, probe/artifact = saved_state/events/side_effects/output,
+// guard = must_not_happen, join = cross_check.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+export const CHECK_CLASS = Object.freeze({
+  __proto__: null,
+  locator: "on_screen",
+  probe: "state",
+  artifact: "state",
+  guard: "must_not_happen",
+  join: "cross_check",
+});
+
+/** The verifier the record tool hands the vault for a check (kept in step with walkthrough.mjs verifierForCheck). */
+export function defaultVerifier(kind) {
+  switch (kind) {
+    case "locator": return { kind: "jq_pred", params: { expr: ".inner_text != null" } };
+    case "probe": return { kind: "jq_pred", params: { expr: ".raw.exit_code == 0" } };
+    case "artifact": return { kind: "jq_pred", params: { expr: ".sha256 != null" } };
+    case "guard": return { kind: "jq_pred", params: { expr: "(.foreign_writes | length) == 0 and ((.console_errors // []) | length) == 0" } };
+    case "join": return { kind: "jq_pred", params: { expr: ".joined | to_entries | all(.value != null)" } };
+    default: return null;
+  }
+}
+
+const SEGMENT_KEY = /^[a-z0-9][a-z0-9-]*$/;
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const PLAIN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+// Env names a storyline may not hand the fixture: credentials never reach the jailed app (§7).
+const SECRET_ENV = /(SECRET|TOKEN|PASSWORD|PASSWD|PASSPHRASE|API_?KEY|ACCESS_?KEY|PRIVATE_?KEY|CREDENTIAL|AUTH)/i;
+// Inline-code flags: `node -e`, `python -c`, `sh -c`, ... — the fixture must be a script the tree declares.
+const INLINE_FLAGS = new Set(["-e", "-c", "--eval", "-p", "--print", "--command"]);
+const SCRIPT_LIKE = /\.(?:m?js|cjs|ts|mts|py|sh|rb|pl)$/i;
+
+/** The first line of a thrown value's message; never throws itself (a storyline can throw anything). */
+function why(e) {
+  try { return String(e?.message ?? e).split("\n")[0]; } catch { return "the storyline threw a value that cannot be read"; }
+}
+
+function hasDotDot(p) { return /(?:^|[\\/])\.\.(?:[\\/]|$)/.test(p); }
+
+/**
+ * Lint a loaded storyline object. Pure apart from running `jq` for the negative samples.
+ * @param {object} story the storyline's default export
+ * @param {{tree?: string|null, steps?: string[]|null, jq?: string}} opts
+ * @returns {{findings: {rule: string, where: string, detail: string}[], chapters: number, checks: number}}
+ */
+export function lintStoryline(story, { tree = null, steps = null, jq = "jq" } = {}) {
+  const findings = [];
+  const add = (rule, where, detail) => findings.push({ rule, where, detail });
+
+  if (!story || typeof story !== "object") {
+    add("storyline_shape", "default export", "the storyline's default export must be an object");
+    return { findings, chapters: 0, checks: 0 };
+  }
+
+  // ---- baseUrl + fixture ------------------------------------------------------------------------------
+  if (story.baseUrl !== "fixture") {
+    add("base_url", "baseUrl", `baseUrl must be "fixture" (the record tool films the fixture it starts), got ${JSON.stringify(story.baseUrl)}`);
+  }
+  const fixture = story.fixture;
+  if (!fixture || typeof fixture !== "object") {
+    add("fixture_start", "fixture", "fixture is required: { start: [argv], ready, probes?, env? }");
+  } else {
+    const start = fixture.start;
+    if (!Array.isArray(start) || start.length === 0 || !start.every((a) => typeof a === "string" && a.length > 0)) {
+      add("fixture_start", "fixture.start", "fixture.start must be a non-empty argv array of strings (no shell)");
+    } else {
+      for (const arg of start.slice(1)) {
+        if (INLINE_FLAGS.has(arg)) add("fixture_start", "fixture.start", `inline code (${arg}) is refused: start a script the tree declares`);
+      }
+      for (const arg of start) {
+        if (path.isAbsolute(arg) || /^[A-Za-z]:[\\/]/.test(arg)) add("fixture_start", "fixture.start", `${JSON.stringify(arg)} is an absolute path; the fixture runs from app/ (the tree)`);
+        else if (hasDotDot(arg)) add("fixture_start", "fixture.start", `${JSON.stringify(arg)} leaves app/ (the tree)`);
+      }
+      if (tree) {
+        for (const arg of start.slice(1)) {
+          if (arg.startsWith("-") || path.isAbsolute(arg) || hasDotDot(arg)) continue;
+          if (!(arg.includes("/") || SCRIPT_LIKE.test(arg))) continue;
+          if (!fs.existsSync(path.join(tree, arg))) add("fixture_start", "fixture.start", `${JSON.stringify(arg)} is not in the tree (${tree})`);
+        }
+      }
+    }
+    if (fixture.env !== undefined) {
+      if (!fixture.env || typeof fixture.env !== "object" || Array.isArray(fixture.env)) {
+        add("fixture_env", "fixture.env", "fixture.env must be an object of name: value");
+      } else {
+        for (const name of Object.keys(fixture.env)) {
+          if (SECRET_ENV.test(name)) add("secret_env", `fixture.env.${name}`, "a secret-shaped env name is refused: no credential reaches the jailed app");
+        }
+      }
+    }
+    if (fixture.probes !== undefined && (!fixture.probes || typeof fixture.probes !== "object" || Array.isArray(fixture.probes))) {
+      add("fixture_probes", "fixture.probes", "fixture.probes must be an object of name: argv");
+    }
+  }
+  const probes = fixture && typeof fixture.probes === "object" && fixture.probes ? fixture.probes : {};
+
+  // ---- segments ---------------------------------------------------------------------------------------
+  const segments = Array.isArray(story.segments) ? story.segments : null;
+  if (!segments) {
+    add("segments", "segments", "segments must be an array");
+    return { findings, chapters: 0, checks: 0 };
+  }
+  const chapters = segments.filter((s) => s && !s.intro);
+  if (chapters.length === 0) add("segments", "segments", "the storyline has no chapter (an empty plan proves nothing)");
+
+  const seenKeys = new Set();
+  let checkCount = 0;
+  let mustNotHappen = 0;
+
+  segments.forEach((seg, i) => {
+    const where = `segments[${i}]${seg && typeof seg.key === "string" ? ` (${seg.key})` : ""}`;
+    if (!seg || typeof seg !== "object") { add("segment_shape", where, "a segment must be an object"); return; }
+    if (!SEGMENT_KEY.test(String(seg.key ?? ""))) add("segment_key", where, `key ${JSON.stringify(seg.key)}: lowercase letters, digits and hyphens only`);
+    else if (seenKeys.has(seg.key)) add("segment_key", where, `key ${JSON.stringify(seg.key)} is used twice`);
+    seenKeys.add(seg.key);
+    if (typeof seg.run !== "function") add("segment_run", where, "run(ctx) must be a function");
+    if (seg.intro) return;
+
+    // proves: plan step ids
+    if (!Array.isArray(seg.proves) || seg.proves.length === 0) {
+      add("proves", where, "proves[] must name at least one plan step id");
+    } else {
+      for (const id of seg.proves) {
+        if (typeof id !== "string" || !PLAIN_ID.test(id)) add("proves", where, `proves id ${JSON.stringify(id)} is not a plain step id`);
+        else if (steps && !steps.includes(id)) add("proves", where, `proves id ${JSON.stringify(id)} is not a step of the plan (${steps.join(", ")})`);
+      }
+    }
+
+    const checks = Array.isArray(seg.checks) ? seg.checks : null;
+    if (!checks || checks.length === 0) { add("chapter_checks", where, "a chapter needs checks[]"); return; }
+    const byId = new Map();
+    const classes = { on_screen: [], state: [], must_not_happen: [], cross_check: [] };
+
+    checks.forEach((c, j) => {
+      const cw = `${where}.checks[${j}]${c && typeof c.id === "string" ? ` (${c.id})` : ""}`;
+      if (!c || typeof c !== "object") { add("check_shape", cw, "a check must be an object"); return; }
+      checkCount += 1;
+      if (!SAFE_ID.test(String(c.id ?? ""))) add("check_id", cw, `id ${JSON.stringify(c.id)}: letters, digits, '.', '_' and '-' only`);
+      else if (byId.has(c.id)) add("check_id", cw, `id ${JSON.stringify(c.id)} is used twice in this chapter`);
+      const cls = typeof c.kind === "string" && Object.hasOwn(CHECK_CLASS, c.kind) ? CHECK_CLASS[c.kind] : null;
+      if (!cls) { add("check_kind", cw, `kind ${JSON.stringify(c.kind)} is not one of ${Object.keys(CHECK_CLASS).join(", ")}`); return; }
+      classes[cls].push(c.id);
+      if (cls === "must_not_happen") mustNotHappen += 1;
+
+      // Collector inputs
+      if (c.kind === "locator" && (typeof c.selector !== "string" || !c.selector.trim())) add("check_selector", cw, "a locator check needs a selector");
+      if (c.kind === "probe") {
+        if (typeof c.name !== "string" || !c.name) add("check_probe", cw, "a probe check needs name (a key of fixture.probes)");
+        else if (!Object.prototype.hasOwnProperty.call(probes, c.name)) add("check_probe", cw, `probe ${JSON.stringify(c.name)} is not in fixture.probes`);
+        if (c.parse !== undefined && !["json", "jsonl", "sqlite-json", "text"].includes(c.parse)) add("check_probe", cw, `parse ${JSON.stringify(c.parse)} is not json | jsonl | sqlite-json | text`);
+      }
+      if (c.kind === "artifact") {
+        const p = c.path;
+        if (typeof p !== "string" || !p) add("check_artifact", cw, "an artifact check needs path (relative to DATA_DIR)");
+        else if (path.isAbsolute(p) || hasDotDot(p)) add("check_artifact", cw, `artifact path ${JSON.stringify(p)} escapes DATA_DIR`);
+      }
+      if (c.kind === "join") {
+        const src = Array.isArray(c.sources) ? c.sources : [];
+        if (src.length < 2) add("check_join", cw, "a join needs sources[] naming at least two earlier checks");
+        for (const s of src) if (!byId.has(s)) add("check_join", cw, `source ${JSON.stringify(s)} is not an earlier check of this chapter`);
+      }
+
+      // Verifier + negative samples (S3): the verifier must FAIL on every sample.
+      const verifier = c.verify === undefined ? defaultVerifier(c.kind) : c.verify;
+      const expr = verifier?.params?.expr;
+      if (!verifier || verifier.kind !== "jq_pred" || typeof expr !== "string" || !expr.trim()) {
+        add("check_verify", cw, "verify must be { kind: \"jq_pred\", params: { expr } } — the one verifier the record tool hands the vault");
+      } else {
+        const negs = c.negative;
+        if (!Array.isArray(negs) || negs.length === 0) {
+          add("negative_missing", cw, "every check needs at least one negative sample (a capture its verifier must FAIL)");
+        } else {
+          negs.forEach((sample, k) => {
+            const r = spawnSync(jq, ["-e", expr], { input: JSON.stringify(sample), encoding: "utf8", timeout: 10_000 });
+            if (r.error) add("negative_unverified", `${cw}.negative[${k}]`, `jq could not run (${r.error.code ?? r.error.message}); the lint fails closed`);
+            else if (r.status === 0) add("negative_passes", `${cw}.negative[${k}]`, `the verifier \`${expr}\` PASSES this sample, so the check cannot fail (a tautology)`);
+            else if (r.status !== 1 && r.status !== 4) add("check_verify", cw, `jq rejected \`${expr}\` (exit ${r.status}): ${(r.stderr || "").trim().slice(0, 200)}`);
+          });
+        }
+      }
+      byId.set(c.id, c);
+    });
+
+    if (classes.on_screen.length === 0) add("chapter_on_screen", where, "a chapter needs at least one on_screen check (kind: locator)");
+    if (classes.state.length === 0) add("chapter_state", where, "a chapter needs at least one saved_state/events/side_effects/output check (kind: probe or artifact)");
+    if (classes.on_screen.length && classes.state.length) {
+      const joined = checks.some((c) => c?.kind === "join" && Array.isArray(c.sources)
+        && c.sources.some((s) => classes.on_screen.includes(s)) && c.sources.some((s) => classes.state.includes(s)));
+      if (!joined) add("chapter_cross_check", where, "a chapter with on_screen and state checks needs a join (cross_check) whose sources include one of each");
+    }
+  });
+
+  if (chapters.length && mustNotHappen === 0) add("must_not_happen", "segments", "the walkthrough needs at least one must_not_happen check (kind: guard)");
+
+  return { findings, chapters: chapters.length, checks: checkCount };
+}
+
+/** The `lint` action: resolve, import and lint the storyline; print the report; return the exit code. */
+export async function lintAction({ root, storyline, tree, steps }) {
+  const storyPath = storyline ? path.resolve(storyline) : root ? path.join(path.resolve(root), "storyline.mjs") : null;
+  const report = (findings, extra = {}) => {
+    const out = { ok: findings.length === 0, storyline: storyPath, chapters: 0, checks: 0, ...extra, findings };
+    process.stdout.write(JSON.stringify(out) + "\n");
+    for (const f of findings) process.stderr.write(`lint: ${f.rule} at ${f.where}: ${f.detail}\n`);
+    return findings.length === 0 ? 0 : 1;
+  };
+  if (!storyPath) {
+    process.stderr.write("usage: walkthrough.mjs lint --root <author dir> [--storyline <path>] [--tree <dir>] [--steps <id,...>]\n");
+    return 2;
+  }
+  let st;
+  try { st = fs.statSync(storyPath); } catch {
+    return report([{ rule: "storyline_missing", where: storyPath, detail: "no storyline here: the walkthrough_plan author writes <author dir>/storyline.mjs" }]);
+  }
+  if (!st.isFile()) return report([{ rule: "storyline_missing", where: storyPath, detail: "not a regular file" }]);
+  let story;
+  try {
+    story = (await import(pathToFileURL(storyPath).href)).default;
+  } catch (e) {
+    return report([{ rule: "storyline_unloadable", where: storyPath, detail: why(e) }]);
+  }
+  let result;
+  try {
+    result = lintStoryline(story, { tree: tree ? path.resolve(tree) : null, steps });
+  } catch (e) {
+    // A storyline that throws while being read (a getter, a proxy) is a finding, never a crash without a report.
+    return report([{ rule: "storyline_unreadable", where: storyPath, detail: why(e) }]);
+  }
+  return report(result.findings, { chapters: result.chapters, checks: result.checks });
+}

package/scripts/demo/walkthrough.mjs

@@ -3,8 +3,12 @@
 //
 //   wicked-garden run scripts/demo/walkthrough.mjs record [--storyline <path>]
 //   wicked-garden run scripts/demo/walkthrough.mjs seal   --root <dir>
+//   wicked-garden run scripts/demo/walkthrough.mjs lint   --root <author dir> [--storyline <path>] [--tree <dir>] [--steps <id,...>]
 //
 // Required env for record: WICKED_EVIDENCE_ROOT, WICKED_RUN_ID, WICKED_RUN_UNIT, WICKED_TREE
+// The storyline: --storyline <path>, else $WICKED_WALKTHROUGH_AUTHOR/storyline.mjs (the walkthrough_plan step's
+// author dir, which the engine hands the record tool); with neither, record refuses (storyline_refused).
+// lint (walkthrough-lint.mjs, DES §4.5) is the walkthrough_plan step's pinned validator: exit 0 = no finding.
 // Safety: WICKED_WALKTHROUGH_JAIL must be set; without it writes INCONCLUSIVE(unjailed_host) and exits 0.
 //
 // What the proof root holds is ONE contract with crew's walkthrough view and acceptance
@@ -39,6 +43,7 @@ import { tmpdir } from "node:os";
 import { makeSegmentRecorder, failedAtInVideo, stitchParts, extractFrame, SEGMENT_TRIM_START } from "./record.mjs";
 import { fixtureOrigin } from "./readonly.mjs";
 import { crewRunStamp } from "../qe/lib/crew-run.mjs";
+import { lintAction } from "./walkthrough-lint.mjs";
 
 // ---- arg parsing ---------------------------------------------------------------
 const [action, ...rawArgs] = process.argv.slice(2);
@@ -48,11 +53,22 @@ function argVal(flag) {
   return i >= 0 ? rawArgs[i + 1] ?? null : null;
 }
 
-if (action !== "record" && action !== "seal") {
-  process.stderr.write("usage: walkthrough.mjs <record|seal> [--storyline <path>] [--root <dir>]\n");
+if (action !== "record" && action !== "seal" && action !== "lint") {
+  process.stderr.write("usage: walkthrough.mjs <record|seal|lint> [--storyline <path>] [--root <dir>]\n");
   process.exit(2);
 }
 
+// ---- lint action (standalone; the walkthrough_plan step's pinned validator) ------
+if (action === "lint") {
+  const steps = argVal("--steps");
+  process.exit(await lintAction({
+    root: argVal("--root") ?? process.env.WICKED_EVIDENCE_ROOT ?? null,
+    storyline: argVal("--storyline"),
+    tree: argVal("--tree"),
+    steps: steps ? steps.split(",").map((x) => x.trim()).filter(Boolean) : null,
+  }));
+}
+
 // ---- seal action (standalone, no env required) ---------------------------------
 if (action === "seal") {
   const sealRoot = argVal("--root") ?? process.env.WICKED_EVIDENCE_ROOT;
@@ -92,10 +108,13 @@ function tryStaticSegmentKeys(filePath) {
 }
 
 // Resolve storyline path early so the jail check can enumerate chapters.
+// --storyline wins; else the author dir the engine hands the record tool (wicked-core `record_launch`). Not the
+// unit ordinal (WICKED_RUN_UNIT): the author writes under its own plan step's id (wicked-garden#1231).
+const AUTHOR_DIR = process.env.WICKED_WALKTHROUGH_AUTHOR ? path.resolve(process.env.WICKED_WALKTHROUGH_AUTHOR) : null;
 const _earlyStoryPath = (() => {
   const arg = argVal("--storyline");
   if (arg) return path.resolve(arg);
-  return path.join(path.dirname(ROOT), "author", STEP_ID, "storyline.mjs");
+  return AUTHOR_DIR ? path.join(AUTHOR_DIR, "storyline.mjs") : null;
 })();
 
 // ---- jail check ----------------------------------------------------------------
@@ -560,11 +579,14 @@ function judgeChapter(seg, captures, failedAtSec, { crossCheck = null, vaultEntr
         // Claim not recorded in vault (never reached)
         claimVerdict = "FAIL";
       } else {
-        // result field (vault ≥0.7.0): "PASS"|"MISSING"|"FAIL"|"ERROR" (uppercase)
-        // verifier_status (older vault): "pass"|"fail"|"error" (lowercase)
+        // Precedence: (1) hash_ok === false — a tampered / mismatched payload is a FAIL whatever
+        // the verifier said; (2) verifier_status "error" (jq absent, verifier crashed) — the vault
+        // folds it into `result: "FAIL"`, but DES §4.5 says an environment fault is INCONCLUSIVE,
+        // never a product failure; (3) the folded `result` ("PASS"|"MISSING"|"FAIL"|"ERROR",
+        // uppercase), falling back to verifier_status ("pass"|"fail"|"error") for an older vault.
         const res = vc.result?.toUpperCase();
         const vs = vc.verifier_status?.toUpperCase();
-        const r = res ?? vs;
+        const r = vc.hash_ok === false ? "FAIL" : vs === "ERROR" ? "ERROR" : (res ?? vs);
         claimVerdict = r === "PASS" ? "PASS"
           : r === "MISSING" || r === "FAIL" ? "FAIL"
           : "INCONCLUSIVE";
@@ -607,13 +629,17 @@ function judgeChapter(seg, captures, failedAtSec, { crossCheck = null, vaultEntr
 function claimDetail(claimVerdict, cap, vaultClaim, vaultAvailable, vaultError) {
   if (!vaultAvailable) return "vault unavailable: no cross-check could run";
   if (vaultError) return "vault cross-check returned ERROR";
+  const why = vaultClaim && [vaultClaim.reason, vaultClaim.message, vaultClaim.detail].find((v) => typeof v === "string" && v);
+  const vaultSays = (status) => (why ? `vault ${status}: ${why}` : `vault ${status}`);
+  // The vault verified an artifact for this claim: its finding names the cause, whatever the capture
+  // looked like (mirrors the verdict precedence in judgeChapter).
+  if (vaultClaim?.hash_ok === false) return vaultSays("hash mismatch");
+  if (vaultClaim && String(vaultClaim.verifier_status ?? "").toUpperCase() === "ERROR") return vaultSays("verifier error");
   if (cap?._verifier_error) return `collector error: ${cap._verifier_error}`;
   if (!cap) return "never reached: ctx.check was not called for this id";
   if (!vaultClaim) return "not recorded in the vault";
   if (claimVerdict === "PASS") return null;
-  const status = vaultClaim.result ?? vaultClaim.verifier_status ?? claimVerdict;
-  const why = [vaultClaim.reason, vaultClaim.message, vaultClaim.detail].find((v) => typeof v === "string" && v);
-  return why ? `vault ${status}: ${why}` : `vault ${status}`;
+  return vaultSays(vaultClaim.result ?? vaultClaim.verifier_status ?? claimVerdict);
 }
 
 /** The root-relative files behind a capture, as crew serves them (`/walkthrough/file?path=`). */
@@ -845,18 +871,12 @@ async function main() {
     ? parseInt(process.env.WICKED_WALKTHROUGH_DISK_CAP, 10) : 0;
 
   // Locate storyline
-  const storyArgPath = argVal("--storyline");
-  let storyPath;
-  if (storyArgPath) {
-    storyPath = path.resolve(storyArgPath);
-  } else {
-    const authorDir = path.join(path.dirname(ROOT), "author", STEP_ID);
-    const autoPath = path.join(authorDir, "storyline.mjs");
-    storyPath = autoPath;
-  }
+  const storyPath = _earlyStoryPath;
 
-  if (!fs.existsSync(storyPath)) {
-    writeResult(ROOT, { overall: "INCONCLUSIVE", cause: "storyline_refused", reason: `storyline not found: ${storyPath}`, chapters: [] });
+  if (!storyPath || !fs.existsSync(storyPath)) {
+    const reason = storyPath ? `storyline not found: ${storyPath}`
+      : "no storyline: pass --storyline <path> or set WICKED_WALKTHROUGH_AUTHOR (the walkthrough_plan author dir)";
+    writeResult(ROOT, { overall: "INCONCLUSIVE", cause: "storyline_refused", reason, chapters: [] });
     writeProgress(ROOT, { overall: "INCONCLUSIVE", cause: "storyline_refused" });
     finishWithSeal(ROOT, { tree: TREE, storyline_sha: null, contract_shas: {}, overall: "INCONCLUSIVE", cause: "storyline_refused", chapters: [] });
     process.exit(0);