@antelopejs/dms 0.15.1 → 0.16.0

package/bin/control/verify/formal.mjs

@@ -2,9 +2,15 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, matchesGlob, relative } from "node:path";
 import { behaviourChange, inWorktree } from "./behaviour.mjs";
+import { decodeFormalResult } from "./decode.mjs";
 
 const OUTPUT_LIMIT = 64 * 1024 * 1024;
 
+/**
+ * @param {import("./types.mjs").FormalCheck} check The check
+ * @param {string[]} changed Repository paths
+ * @returns {boolean} Whether a changed path matches the check's own files
+ */
 function changesCheckFiles(check, changed) {
   return changed.some((file) =>
     (check.files ?? []).some((glob) => matchesGlob(file, glob)),
@@ -14,9 +20,9 @@ function changesCheckFiles(check, changed) {
 /**
  * The formal checks whose covered files or own `files` a set of changed files touches.
  *
- * @param {Record<string, any>} skill The skill
+ * @param {import("./skill.mjs").Skill} skill The skill
  * @param {string[]} changed Repository paths
- * @returns {Record<string, any>[]} The checks
+ * @returns {import("./types.mjs").FormalCheck[]} The checks
  */
 export function touchedFormalChecks(skill, changed) {
   return skill.config.formal.filter(
@@ -26,6 +32,12 @@ export function touchedFormalChecks(skill, changed) {
   );
 }
 
+/**
+ * @param {import("./types.mjs").FormalCheck} check The check
+ * @param {number | null} exitCode How the run exited
+ * @param {string} output What the run printed
+ * @returns {string[]} The violated rules
+ */
 function violatedRules(check, exitCode, output) {
   if (check.violation) {
     return [
@@ -37,6 +49,11 @@ function violatedRules(check, exitCode, output) {
   return exitCode === 0 ? [] : ["property"];
 }
 
+/**
+ * @param {string[]} command The program and its arguments
+ * @param {string} cwd Where to run it
+ * @returns {import("node:child_process").SpawnSyncReturns<string>} The run
+ */
 function runCommand(command, cwd) {
   const [program, ...args] = command;
   return spawnSync(program, args, {
@@ -46,6 +63,12 @@ function runCommand(command, cwd) {
   });
 }
 
+/**
+ * @param {string} folder The evidence folder
+ * @param {string} prefix `base-` for the base run, else empty
+ * @param {string[]} command The command that ran
+ * @param {import("node:child_process").SpawnSyncReturns<string>} run The run
+ */
 function writeRun(folder, prefix, command, run) {
   writeFileSync(join(folder, `${prefix}command.txt`), `${command.join(" ")}\n`);
   writeFileSync(join(folder, `${prefix}stdout.txt`), run.stdout ?? "");
@@ -56,12 +79,22 @@ function writeRun(folder, prefix, command, run) {
   writeFileSync(join(folder, `${prefix}exit-code.txt`), `${run.status}\n`);
 }
 
+/**
+ * @param {import("./types.mjs").FormalCheck} check The check
+ * @param {string} output What the run printed
+ * @returns {string[]} The passing rules
+ */
 function passingRules(check, output) {
   return check.passing
     ? [...new Set([...output.matchAll(check.passing)].map((match) => match[1]))]
     : [];
 }
 
+/**
+ * @param {import("./types.mjs").FormalCheck} check The check
+ * @param {import("node:child_process").SpawnSyncReturns<string>} run The run
+ * @returns {import("./types.mjs").Rules} The exit code and rules
+ */
 function rulesOf(check, run) {
   return {
     exitCode: run.status,
@@ -70,6 +103,13 @@ function rulesOf(check, run) {
   };
 }
 
+/**
+ * @param {import("./skill.mjs").Skill} skill The skill
+ * @param {import("./types.mjs").FormalCheck} check The check
+ * @param {string} baseSha The base commit
+ * @param {string} folder The evidence folder
+ * @returns {import("./types.mjs").Rules} The rules at the base
+ */
 function baseRules(skill, check, baseSha, folder) {
   const command = check.baseCommand ?? check.command;
   const run = inWorktree(skill.repo, baseSha, (dir) =>
@@ -79,6 +119,14 @@ function baseRules(skill, check, baseSha, folder) {
   return rulesOf(check, run);
 }
 
+/**
+ * @param {import("./skill.mjs").Skill} skill The skill
+ * @param {import("./types.mjs").FormalCheck} check The check
+ * @param {{ baseSha: string, headSha: string, changed: string[] }} diff The diff
+ * @param {string} folder The evidence folder
+ * @param {import("./types.mjs").Rules} head The rules at HEAD
+ * @returns {Pick<import("./types.mjs").FormalResult, "behaviour" | "checkChanged" | "base" | "fixed" | "missing">} The gate fields
+ */
 function gateFields(skill, check, diff, folder, head) {
   const behaviour = behaviourChange(skill, check, diff);
   const checkChanged = changesCheckFiles(check, diff.changed);
@@ -106,11 +154,11 @@ function gateFields(skill, check, diff, folder, head) {
  * `fixed` lists the rules the base broke that HEAD reports passing, and
  * `missing` the rules the base broke that HEAD reports neither failing nor passing.
  *
- * @param {Record<string, any>} skill The skill
- * @param {Record<string, any>} state The run
- * @param {Record<string, any>} check The check
+ * @param {import("./skill.mjs").Skill} skill The skill
+ * @param {import("../run-state.mjs").RunState} state The run
+ * @param {import("./types.mjs").FormalCheck} check The check
  * @param {{ baseSha: string, headSha: string, changed: string[] } | null} diff The diff's base, head and changed files, for a check that covers it
- * @returns {Record<string, any>} The result
+ * @returns {import("./types.mjs").FormalResult} The result
  */
 export function runFormalCheck(skill, state, check, diff) {
   const folder = join(state.evidence, "formal", check.name);
@@ -147,7 +195,7 @@ export function runFormalCheck(skill, state, check, diff) {
  * covered code's behaviour; a rule the base reported and HEAD no longer
  * reports fails; rules the base broke that HEAD reports passing are fixed.
  *
- * @param {Record<string, any>} result The recorded result
+ * @param {import("./types.mjs").FormalResult} result The recorded result
  * @returns {{ fails: boolean, outcome: string }} The weight and its wording
  */
 export function formalGate(result) {
@@ -198,11 +246,14 @@ export function formalGate(result) {
 /**
  * The recorded result of a formal check in a run, if it ran.
  *
- * @param {Record<string, any>} state The run
+ * @param {import("../run-state.mjs").RunState} state The run
  * @param {string} name The check
- * @returns {Record<string, any> | undefined} The result
+ * @returns {import("./types.mjs").FormalResult | undefined} The result
  */
 export function readFormalResult(state, name) {
   const file = join(state.evidence, "formal", name, "result.json");
-  return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : undefined;
+  if (!existsSync(file)) return undefined;
+  /** @type {unknown} */
+  const stored = JSON.parse(readFileSync(file, "utf8"));
+  return decodeFormalResult(stored, file);
 }

package/bin/control/verify/formal.test.mjs

@@ -28,10 +28,19 @@ const CHECK_CONFIG = {
   behaviour: { kind: "emit" },
 };
 
+/**
+ * @param {string} repo
+ * @param {...string} args
+ */
 function git(repo, ...args) {
   return execFileSync("git", args, { cwd: repo, encoding: "utf8" }).trim();
 }
 
+/**
+ * @param {string} repo
+ * @param {Record<string, string>} files
+ * @param {string} message
+ */
 function commit(repo, files, message) {
   for (const [path, content] of Object.entries(files)) {
     mkdirSync(dirname(join(repo, path)), { recursive: true });
@@ -54,6 +63,10 @@ function commit(repo, files, message) {
   return git(repo, "rev-parse", "HEAD");
 }
 
+/**
+ * @param {import("node:test").TestContext} t
+ * @param {Record<string, string>} head
+ */
 function formalRepo(t, head) {
   const root = mkdtempSync(join(tmpdir(), "dms-control-formal-test-"));
   t.after(() => rmSync(root, { recursive: true, force: true }));
@@ -77,12 +90,15 @@ function formalRepo(t, head) {
   return { skill, state: { evidence }, diff: { baseSha, headSha, changed } };
 }
 
+/**
+ * @param {ReturnType<typeof formalRepo>} repo
+ */
 function gated({ skill, state, diff }) {
   const [check] = touchedFormalChecks(skill, diff.changed);
   return check ? runFormalCheck(skill, state, check, diff) : null;
 }
 
-test("a rule counts as fixed only when HEAD reports it passing, never when HEAD drops it", (t) => {
+await test("a rule counts as fixed only when HEAD reports it passing, never when HEAD drops it", (t) => {
   const fixed = gated(
     formalRepo(t, {
       "src/math.js": ADD.replace("a + b", "a + b + 0"),
@@ -101,7 +117,7 @@ test("a rule counts as fixed only when HEAD reports it passing, never when HEAD
   assert.deepEqual(dropped.missing, ["NegativeZero"]);
 });
 
-test("a diff that touches only a check's own files runs the check and gates it against the base", (t) => {
+await test("a diff that touches only a check's own files runs the check and gates it against the base", (t) => {
   const result = gated(
     formalRepo(t, {
       ".agents/skills/formal-add/check.mjs": CHECK_WITHOUT_RULE,
@@ -114,7 +130,7 @@ test("a diff that touches only a check's own files runs the check and gates it a
   });
 });
 
-test("a diff that touches neither the covered files nor the check's files does not touch the check", (t) => {
+await test("a diff that touches neither the covered files nor the check's files does not touch the check", (t) => {
   const { skill, diff } = formalRepo(t, { "README.md": "# Demo\n" });
   assert.deepEqual(touchedFormalChecks(skill, diff.changed), []);
 });

package/bin/control/verify/judgement.mjs

@@ -1,5 +1,12 @@
 import { existsSync, readFileSync } from "node:fs";
+import { decodeRawJudgement } from "./decode.mjs";
 
+/**
+ * @param {import("./skill.mjs").Skill} skill The skill
+ * @param {string | undefined} value The kind a judgement names
+ * @param {string} label Where the kind was read
+ * @returns {string} The kind
+ */
 function doorKind(skill, value, label) {
   if (!Object.hasOwn(skill.config.doors, value)) {
     throw new Error(
@@ -9,6 +16,11 @@ function doorKind(skill, value, label) {
   return value;
 }
 
+/**
+ * @param {import("./skill.mjs").Skill} skill The skill
+ * @param {import("./types.mjs").RawJudgement} raw The judgement file
+ * @returns {import("./types.mjs").DoorRow[]} The door rows
+ */
 function parseRows(skill, raw) {
   return (raw.doors?.rows ?? []).map((row, index) => {
     if (!row.kind || !row.location || !row.irreversible || !row.containment) {
@@ -24,6 +36,11 @@ function parseRows(skill, raw) {
   });
 }
 
+/**
+ * @param {import("./skill.mjs").Skill} skill The skill
+ * @param {import("./types.mjs").RawJudgement} raw The judgement file
+ * @returns {import("./types.mjs").FalsePositive[]} The dismissed doors
+ */
 function parseFalsePositives(skill, raw) {
   return (raw.doors?.falsePositives ?? []).map((entry, index) => {
     if (!entry.location || !entry.reason?.trim()) {
@@ -43,9 +60,9 @@ function parseFalsePositives(skill, raw) {
  * verdict without a One-way doors section is void, and one that does not
  * name its verifier is refused, so both throw.
  *
- * @param {Record<string, any>} skill The skill
+ * @param {import("./skill.mjs").Skill} skill The skill
  * @param {string} file The judgement file
- * @returns {{ notVerified: string[], attention: string[], docs: { page: string, matches: boolean, note: string }[], doorsNone: string | null, doors: Record<string, string>[], falsePositives: Record<string, string>[], verifier: string }} The judgement
+ * @returns {import("./types.mjs").Judgement} The judgement
  */
 export function readJudgement(skill, file) {
   if (!existsSync(file)) {
@@ -53,7 +70,9 @@ export function readJudgement(skill, file) {
       `${file} is missing: write the verifier's judgement before rendering the verdict`,
     );
   }
-  const raw = JSON.parse(readFileSync(file, "utf8"));
+  /** @type {unknown} */
+  const stored = JSON.parse(readFileSync(file, "utf8"));
+  const raw = decodeRawJudgement(stored, file);
   const rows = parseRows(skill, raw);
   const none = raw.doors?.none?.trim() || null;
   if (!none && rows.length === 0) {

package/bin/control/verify/map.mjs

@@ -5,6 +5,11 @@ import { flaggedDoors, patchFiles } from "./doors.mjs";
 import { loadJourneys } from "../journey.mjs";
 import { journeysFile, readFeatures } from "./skill.mjs";
 
+/**
+ * @param {string} file A repository path
+ * @param {string[]} globs The globs
+ * @returns {boolean} Whether a glob matches the path
+ */
 function matches(file, globs) {
   return globs.some((glob) => matchesGlob(file, glob));
 }
@@ -13,7 +18,7 @@ function matches(file, globs) {
  * Whether a repository path is user-facing: matched by the config's
  * `userFacing` globs and by none of its `notUserFacing` globs.
  *
- * @param {Record<string, any>} skill The skill
+ * @param {import("./skill.mjs").Skill} skill The skill
  * @param {string} file A repository path
  * @returns {boolean} True when a feature must cover it
  */
@@ -37,10 +42,20 @@ export function featuresOf(file, features) {
     .map((feature) => feature.name);
 }
 
+/**
+ * @param {import("./skill.mjs").Skill} skill The skill
+ * @returns {string[]} The tracked paths
+ */
 function trackedFiles(skill) {
   return git(["ls-files"], skill.repo).split("\n").filter(Boolean);
 }
 
+/**
+ * @param {import("./skill.mjs").Skill} skill The skill
+ * @param {ReturnType<typeof readFeatures>[number]} feature The feature
+ * @param {string[]} tracked The tracked paths
+ * @returns {Promise<string[]>} One line per problem
+ */
 async function featureProblems(skill, feature, tracked) {
   const problems = [];
   const file = journeysFile(skill, feature.name);
@@ -84,6 +99,11 @@ async function featureProblems(skill, feature, tracked) {
   return problems;
 }
 
+/**
+ * @param {import("./skill.mjs").Skill} skill The skill
+ * @param {string[]} tracked The tracked paths
+ * @returns {string[]} One line per problem
+ */
 function doorProblems(skill, tracked) {
   const problems = [];
   for (const [kind, rule] of Object.entries(skill.config.doors)) {
@@ -112,7 +132,7 @@ function doorProblems(skill, tracked) {
  * pages, every feature and door glob
  * matches a tracked file, and every door rule has a seeded door.
  *
- * @param {Record<string, any>} skill The skill
+ * @param {import("./skill.mjs").Skill} skill The skill
  * @returns {Promise<string[]>} One line per problem
  */
 export async function checkMap(skill) {
@@ -146,7 +166,7 @@ const CONTAINED_KINDS = ["data", "format"];
  * doors a set of changed files opens: a door row must name one of them,
  * passing in the run.
  *
- * @param {Record<string, any>} skill The skill
+ * @param {import("./skill.mjs").Skill} skill The skill
  * @param {string[]} changed Repository paths
  * @returns {string[]} The journeys, each once
  */
@@ -167,9 +187,9 @@ function containmentJourneys(skill, changed) {
  * outside every glob is an unmapped surface, and `containments` lists the
  * journeys that can contain each Data or Format door the diff opens.
  *
- * @param {Record<string, any>} skill The skill
+ * @param {import("./skill.mjs").Skill} skill The skill
  * @param {string} baseRef The base, such as `origin/main`
- * @returns {{ baseRef: string, baseSha: string, headSha: string, changed: string[], touched: { feature: string, files: string[] }[], unmapped: string[], docs: string[], containments: string[], run: string[] }} The plan
+ * @returns {import("./types.mjs").Plan} The plan
  */
 export function planFor(skill, baseRef) {
   const features = readFeatures(skill);

package/bin/control/verify/publish.mjs

@@ -3,11 +3,16 @@ import { cpSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { git } from "../git.mjs";
+import { decodeCommitStatuses } from "./decode.mjs";
 import { originRepository } from "./verdict.mjs";
 
 const EVIDENCE_BRANCH = "verify-evidence";
 const SCRATCH_BRANCH = "verify-evidence-scratch";
 
+/**
+ * @param {string} repo The checkout
+ * @returns {boolean} Whether origin holds the evidence branch
+ */
 function remoteBranchExists(repo) {
   return git(["ls-remote", "--heads", "origin", EVIDENCE_BRANCH], repo) !== "";
 }
@@ -17,8 +22,8 @@ function remoteBranchExists(repo) {
  * `verify-evidence` branch and pushes it, from a temporary worktree so the
  * checkout under review is never touched.
  *
- * @param {Record<string, any>} skill The skill
- * @param {Record<string, any>} state The run
+ * @param {import("./skill.mjs").Skill} skill The skill
+ * @param {import("../run-state.mjs").RunState} state The run
  * @param {{ pr: number, headSha: string, result: string }} verdict The verdict
  * @returns {string} The pushed evidence commit
  */
@@ -102,7 +107,7 @@ export function pushEvidence(skill, state, verdict) {
 /**
  * Posts the verdict as a PR comment.
  *
- * @param {Record<string, any>} skill The skill
+ * @param {import("./skill.mjs").Skill} skill The skill
  * @param {{ pr: number, markdown: string }} verdict The verdict
  * @returns {string} The comment URL gh prints
  */
@@ -126,7 +131,7 @@ export function postComment(skill, verdict) {
  * Sets the `verify` commit status on the head SHA the verdict judged:
  * `success` for PASS and PASS+NOTES, `failure` for FAIL.
  *
- * @param {Record<string, any>} skill The skill
+ * @param {import("./skill.mjs").Skill} skill The skill
  * @param {{ headSha: string, result: string }} verdict The verdict
  * @param {string} targetUrl The comment URL
  * @returns {string | null} GitHub's error when the status could not be set
@@ -159,21 +164,22 @@ export function setStatus(skill, verdict, targetUrl) {
  * Reads back the `verify` status GitHub holds for a SHA, so the write is
  * checked through a second command.
  *
- * @param {Record<string, any>} skill The skill
+ * @param {import("./skill.mjs").Skill} skill The skill
  * @param {string} sha The commit
  * @returns {string} The status state, or `absent`
  */
 export function readStatus(skill, sha) {
-  const statuses = JSON.parse(
-    execFileSync(
-      "gh",
-      ["api", `repos/${originRepository(skill.repo)}/commits/${sha}/statuses`],
-      {
-        cwd: skill.repo,
-        encoding: "utf8",
-      },
-    ),
+  const answer = execFileSync(
+    "gh",
+    ["api", `repos/${originRepository(skill.repo)}/commits/${sha}/statuses`],
+    {
+      cwd: skill.repo,
+      encoding: "utf8",
+    },
   );
+  /** @type {unknown} */
+  const stored = JSON.parse(answer);
+  const statuses = decodeCommitStatuses(stored, "gh api statuses");
   return (
     statuses.find((status) => status.context === "verify")?.state ?? "absent"
   );

package/bin/control/verify/seeded.mjs

@@ -3,18 +3,24 @@ import {
   cpSync,
   existsSync,
   mkdtempSync,
-  readFileSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, relative } from "node:path";
+import { join, relative, resolve } from "node:path";
 import { git } from "../git.mjs";
 import { CONTROL_BIN } from "../stack.mjs";
+import { readFeatureResults } from "./decode.mjs";
 import { runPrepare } from "./skill.mjs";
 
 const OUTPUT_LIMIT = 64 * 1024 * 1024;
 
+/**
+ * @param {string} cwd Where to run it
+ * @param {string} program The program
+ * @param {string[]} args Its arguments
+ * @returns {import("node:child_process").SpawnSyncReturns<string>} The run
+ */
 function run(cwd, program, args) {
   return spawnSync(program, args, {
     cwd,
@@ -24,6 +30,12 @@ function run(cwd, program, args) {
   });
 }
 
+/**
+ * @param {string} cwd Where to run it
+ * @param {string} program The program
+ * @param {string[]} args Its arguments
+ * @returns {string} Its trimmed output
+ */
 function mustRun(cwd, program, args) {
   const result = run(cwd, program, args);
   if (result.status !== 0) {
@@ -36,9 +48,11 @@ function mustRun(cwd, program, args) {
 
 /**
  * A scratch worktree of HEAD with the current skill copied in, the patch
- * applied when there is one, and the config's `prepare` commands run.
+ * applied when there is one, and the config's `prepare` commands run. The
+ * worktree is the skill's repository, which is also the renderer checkout
+ * when the config names a `renderer`: the patch changes what the run serves.
  *
- * @param {Record<string, any>} skill The skill
+ * @param {import("./skill.mjs").Skill} skill The skill
  * @param {string} label What the worktree is for
  * @param {string | null} patch The patch file, or `null` for the control
  * @returns {{ worktree: string, skill: string }} The worktree and its skill copy
@@ -56,21 +70,48 @@ function prepareWorktree(skill, label, patch) {
   return { worktree, skill: copy };
 }
 
+/**
+ * @param {import("./skill.mjs").Skill} skill The skill
+ * @param {string} worktree The scratch worktree
+ */
 function removeWorktree(skill, worktree) {
   git(["worktree", "remove", "--force", worktree], skill.repo);
 }
 
-function runFeatureIn(prepared, skill, feature) {
-  const playground = join(prepared.worktree, skill.config.playground);
-  const control = (args) =>
-    run(prepared.worktree, process.execPath, [CONTROL_BIN, ...args]);
-  const started = control([
+/**
+ * The `up` arguments for a scratch worktree: the config's playground and
+ * renderer, resolved in the worktree unless absolute.
+ *
+ * @param {import("./skill.mjs").Skill} skill The skill
+ * @param {{ worktree: string, skill: string }} prepared The scratch worktree and its skill copy
+ * @returns {string[]} The arguments
+ */
+export function upArguments(skill, prepared) {
+  const { playground, renderer } = skill.config;
+  return [
     "up",
     "--playground",
-    playground,
+    resolve(prepared.worktree, playground),
+    ...(renderer ? ["--renderer", resolve(prepared.worktree, renderer)] : []),
     "--skill",
     prepared.skill,
-  ]);
+  ];
+}
+
+/**
+ * @param {{ worktree: string, skill: string }} prepared The scratch worktree and its skill copy
+ * @param {import("./skill.mjs").Skill} skill The skill
+ * @param {string} feature The feature
+ * @returns {{ run: string, results: import("./types.mjs").FeatureResult[], output: string }} The run folder, its results and output
+ */
+function runFeatureIn(prepared, skill, feature) {
+  /**
+   * @param {string[]} args The dms-control arguments
+   * @returns {import("node:child_process").SpawnSyncReturns<string>} The run
+   */
+  const control = (args) =>
+    run(prepared.worktree, process.execPath, [CONTROL_BIN, ...args]);
+  const started = control(upArguments(skill, prepared));
   const dir = started.stdout.trim().split("\n").at(-1) ?? "";
   if (started.status !== 0 || !existsSync(join(dir, "run.json"))) {
     return {
@@ -88,16 +129,24 @@ function runFeatureIn(prepared, skill, feature) {
   ]);
   control(["down", dir]);
   const file = join(dir, "evidence", feature, "feature.json");
-  const results = existsSync(file)
-    ? JSON.parse(readFileSync(file, "utf8"))
-    : [];
+  const results = readFeatureResults(file);
   return { run: dir, results, output: `${journeys.stdout}${journeys.stderr}` };
 }
 
+/**
+ * @param {import("./types.mjs").FeatureResult} result A journey result
+ * @returns {boolean} Whether one of its checks failed
+ */
 function failsACheck(result) {
   return result.steps.some((step) => step.checks.some((check) => !check.pass));
 }
 
+/**
+ * @param {string} feature The feature
+ * @param {ReturnType<typeof runFeatureIn>} control The unpatched run
+ * @param {ReturnType<typeof runFeatureIn>} seeded The patched run
+ * @returns {import("./types.mjs").SeededOutcome} The outcome
+ */
 function judge(feature, control, seeded) {
   const passedInControl = new Set(
     control.results
@@ -134,9 +183,9 @@ function judge(feature, control, seeded) {
  * harness error and does not count. Worktrees are removed; both runs keep
  * their evidence, and `seeded.json` in the patched run records the outcome.
  *
- * @param {Record<string, any>} skill The skill
+ * @param {import("./skill.mjs").Skill} skill The skill
  * @param {string[]} features The features
- * @returns {Record<string, any>[]} One outcome per feature
+ * @returns {import("./types.mjs").SeededOutcome[]} One outcome per feature
  */
 export function runSeededBreaks(skill, features) {
   const control = prepareWorktree(skill, "control", null);

package/bin/control/verify/skill.mjs

@@ -3,13 +3,26 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { checkoutOf } from "../git.mjs";
+import { isRecord } from "../json.mjs";
+import { decodeSkillConfig } from "./decode.mjs";
 
 const CONFIG_FILE = "verify.config.ts";
 const OUTPUT_LIMIT = 64 * 1024 * 1024;
 
+/**
+ * @typedef {{ dir: string, name: string, repo: string, config: SkillConfig, featuresDir: string, journeysDir: string, seededBreaksDir: string, seededDoorsDir: string }} Skill
+ * @typedef {{ playground: string, renderer?: string, prepare: string[][], userFacing: string[], notUserFacing: string[], smoke: string, smokeJourney: string, doors: Record<string, { globs: string[], funnels: string[], containments: string[], why: string } | null>, formal: import("./types.mjs").FormalCheck[] }} SkillConfig
+ */
+
+/**
+ * @param {string} text A feature file
+ * @returns {Map<string, string[]>} The lists of its frontmatter
+ */
 function frontmatterLists(text) {
+  /** @type {Map<string, string[]>} */
   const lists = new Map();
   const match = /^---\n([\s\S]*?)\n---\n/.exec(text);
+  /** @type {string[] | undefined} */
   let current;
   for (const line of (match?.[1] ?? "").split("\n")) {
     const key = /^(\w+):\s*$/.exec(line);
@@ -24,6 +37,10 @@ function frontmatterLists(text) {
   return lists;
 }
 
+/**
+ * @param {string} cwd Where the command runs
+ * @returns {string} The one verification skill folder of the checkout
+ */
 function discover(cwd) {
   const { root } = checkoutOf(cwd);
   const skills = join(root ?? cwd, ".agents", "skills");
@@ -49,14 +66,18 @@ function discover(cwd) {
  *
  * @param {string | undefined} option The `--skill` folder
  * @param {string} cwd Where the command runs
- * @returns {Promise<Record<string, any>>} The skill
+ * @returns {Promise<import("./skill.mjs").Skill>} The skill
  */
 export async function loadSkill(option, cwd) {
   const dir = resolve(option ?? discover(cwd));
   const { root } = checkoutOf(dir);
   if (!root) throw new Error(`${dir} is not inside a git checkout`);
-  const { default: config } = await import(
-    pathToFileURL(join(dir, CONFIG_FILE)).href
+  const file = join(dir, CONFIG_FILE);
+  /** @type {unknown} */
+  const loaded = await import(pathToFileURL(file).href);
+  const config = decodeSkillConfig(
+    isRecord(loaded) ? loaded.default : undefined,
+    file,
   );
   return {
     dir,
@@ -74,7 +95,7 @@ export async function loadSkill(option, cwd) {
  * Every feature file under `features/`, README.md excluded, with its
  * `covers:` globs, `docs:` pages and text.
  *
- * @param {Record<string, any>} skill The skill
+ * @param {Skill} skill The skill
  * @returns {{ name: string, file: string, covers: string[], docs: string[], body: string }[]} The features
  */
 export function readFeatures(skill) {
@@ -97,7 +118,7 @@ export function readFeatures(skill) {
 /**
  * The journeys module of a feature.
  *
- * @param {Record<string, any>} skill The skill
+ * @param {Skill} skill The skill
  * @param {string} feature The feature name
  * @returns {string} Its path
  */
@@ -109,7 +130,7 @@ export function journeysFile(skill, feature) {
  * Runs the config's `prepare` commands (install and build) in a checkout of
  * the repository, so a run starts from a fresh build.
  *
- * @param {Record<string, any>} skill The skill
+ * @param {Skill} skill The skill
  * @param {string} cwd The checkout
  * @throws When a command fails, with its output
  */