vigiles 5.2.0 → 6.0.0

package/dist/scaffold-test.js

@@ -100,18 +100,68 @@ console.log(formatTriggerRateReport(report));
 assertTriggerRate(report, { min: 0.8, maxFalsePositive: 0.3 });
 `;
 }
-/** A subagent → the deterministic harness tier; point at the railway/Result path. */
-function agentScaffold(input) {
+/** A JSON value placeholder for an `OutputFieldType`, for the `vigiles:ok` block. */
+function placeholderFor(type) {
+    switch (type) {
+        case "number":
+            return 1;
+        case "boolean":
+            return true;
+        case "string[]":
+            return ["example"];
+        default:
+            return "example";
+    }
+}
+/** Render a `result(ok, err)` builder call reconstructed from the parsed contract. */
+function renderContractBuilder(contract) {
+    const shape = (fields) => `{ ${fields.map((f) => `${f.name}: ${JSON.stringify(f.type)}`).join(", ")} }`;
+    return `result(\n  ${shape(contract.ok)},\n  ${shape(contract.err)},\n)`;
+}
+/**
+ * The OUTCOME test, GENERATED FROM the subagent's `result()` contract: reconstruct
+ * the contract, build a matching `vigiles:ok` block, and `assertAgentOk` it —
+ * deterministic, no LLM judge. This is the typed-spec payoff a markdown
+ * `description:` cannot give you: a parseable, typed outcome a test reads directly.
+ */
+function outcomeSection(input, contract) {
+    const okValue = Object.fromEntries(contract.ok.map((f) => [f.name, placeholderFor(f.type)]));
+    const firstField = contract.ok[0]?.name;
+    const fieldAssertion = firstField
+        ? `// TODO: assert the VALUES you expect (the shape is already validated above), e.g.:\n//   assert.ok(value.${firstField}, "expected a ${firstField}");`
+        : "";
+    return `import assert from "node:assert/strict";
+import { result } from "vigiles/spec";
+import { assertAgentOk } from "vigiles/testing";
+
+// Reconstructed from ${input.name}'s ## Output contract (its compiled .md) — the
+// typed result() the spec wrote. assertAgentOk parses + validates the outcome
+// with NO model judge; swap \`okOutput\` for a real \`runHarness\` turn (Part B in
+// examples/harness/railway-result.harness.mjs) to assert REAL behaviour.
+const contract = ${renderContractBuilder(contract)};
+
+const okOutput = [
+  "${input.name} finished its task.",
+  "\`\`\`vigiles:ok",
+  ${JSON.stringify(JSON.stringify(okValue))},
+  "\`\`\`",
+].join("\\n");
+
+const value = assertAgentOk(okOutput, contract); // deterministic — no LLM judge
+${fieldAssertion}
+console.log("✓ ${input.name}: result() outcome parses + validates against its typed contract");
+`;
+}
+/** The fallback when the subagent has no `result()` contract — assert a tool use. */
+function fallbackSection(input) {
     const toolHint = input.tools && input.tools.length > 0
         ? `assertToolUsed(r, ${JSON.stringify(input.tools[0])}); // its declared contract: ${input.tools.join(", ")}`
         : `assertToolUsed(r, "Task"); // TODO: assert what the subagent should do`;
-    return `${header(`Starter harness test for the \`${input.name}\` subagent.`, `npx vigiles test ${suggestedPath(input)}`)}
-import { runHarnessTest, assertToolUsed } from "vigiles/testing";
-
-// A subagent's OUTCOME is best asserted via a result() contract — deterministic,
-// no LLM judge. If ${input.name} has one, use assertAgentOk(r.output, contract)
-// instead; see the railway-result example in the vigiles docs.
+    return `import { runHarnessTest, assertToolUsed } from "vigiles/testing";
 
+// ${input.name} has no result() contract, so its outcome can't be asserted
+// deterministically — add one (result() on its agent() spec) for a no-judge
+// outcome test. For now, assert it reaches for the right tool.
 const r = await runHarnessTest({
   plugin: ".", // TODO: the plugin dir holding this subagent
   // TODO: a prompt that dispatches ${input.name} (via the Task tool).
@@ -124,6 +174,61 @@ ${toolHint}
 console.log("✓ ${input.name}: subagent test ran");
 `;
 }
+/**
+ * The SAFETY check, GENERATED FROM the subagent's side-effecting `tools`: assert it
+ * stays inside its declared write surface and never reaches for a destructive op.
+ * The `tools` allowlist + effectSurface identify the "hole"; the check asserts it —
+ * a test the typed contract writes for you (markdown can declare the tools, not test them).
+ */
+function safetySection(input, sideEffecting) {
+    const checks = [];
+    if (sideEffecting.includes("Bash")) {
+        checks.push(`  notTool("Bash", { command: /git push|rm -rf/ }), // never a destructive op`);
+    }
+    if (sideEffecting.some((t) => t === "Write" || t === "Edit")) {
+        checks.push(`  didNotWrite("secrets.env"), // TODO: the path(s) it must NOT write outside its surface`);
+    }
+    if (checks.length === 0) {
+        checks.push(`  // TODO: a notTool()/didNotWrite() per side-effecting tool: ${sideEffecting.join(", ")}`);
+    }
+    return `
+// --- Safety (deterministic) — generated from ${input.name}'s side-effecting tools: ${sideEffecting.join(", ")} ---
+// In a real run, replace this constructed Trace with a real \`runHarness\` /
+// \`measure\` turn (use interceptTools so a real model's attempt is DENIED, never
+// executed — see docs/eval-architecture.md). The checks below are derived from the
+// declared tools contract — the agent's "hole" asserted to stay in its lane.
+{
+  const trace = {
+    output: "done",
+    turns: 1,
+    hooks: [],
+    toolCalls: [
+      // TODO: the tool calls a benign run of ${input.name} makes.
+      { name: "Bash", input: { command: "git status" } },
+    ],
+    file: () => null,
+  };
+  assertChecks(trace, [
+${checks.join("\n")}
+  ]);
+  console.log("✓ ${input.name}: stayed inside its declared side-effect surface");
+}
+`;
+}
+/** A subagent → deterministic outcome + safety tests, generated from its typed contract. */
+function agentScaffold(input) {
+    const head = header(`Starter harness test for the \`${input.name}\` subagent.`, `npx vigiles test ${suggestedPath(input)}`);
+    const safetyImport = input.sideEffectingTools && input.sideEffectingTools.length > 0
+        ? `import { notTool, didNotWrite, assertChecks } from "vigiles/testing";\n`
+        : "";
+    const body = input.resultContract
+        ? outcomeSection(input, input.resultContract)
+        : fallbackSection(input);
+    const safety = input.sideEffectingTools && input.sideEffectingTools.length > 0
+        ? safetySection(input, input.sideEffectingTools)
+        : "";
+    return `${head}\n${safetyImport}${body}${safety}`;
+}
 const TIER = {
     hook: "unit",
     skill: "eval",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "5.2.0",
+  "version": "6.0.0",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",