karajan-code 2.7.3 → 2.8.0

package/src/audit/agent-readiness.js

@@ -0,0 +1,240 @@
+/**
+ * kj audit --agent-readiness — score a repo for AI-agent readability.
+ *
+ * Static, deterministic, NO LLM call. Inspired by addyosmani/agentic-seo.
+ * Catches the failure modes that make repos invisible to Cursor /
+ * Cline / Aider / Claude Code:
+ *   - no llms.txt → agents have to crawl the README
+ *   - oversized doc pages → agents truncate or drop them
+ *   - JS-only docs → agents can't render
+ *   - broken heading hierarchy → agents misinfer structure
+ *   - no robots allowlist → some agents skip silently
+ *
+ * Returns a 0-100 score + per-check detail + top remediation hints.
+ * Pure data transformation: filesystem reads in, analysis out.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const PAGE_BYTE_LIMIT = 32 * 1024; // ≈ 8K tokens, the typical agent budget per fetch
+
+/**
+ * Catalogue of checks. Each check has:
+ *   - id          — stable identifier
+ *   - weight      — points contributed when ok
+ *   - run         — (rootDir) => { ok, hint, details }
+ */
+const CHECKS = [
+  {
+    id: "llms-txt-present",
+    weight: 25,
+    description: "llms.txt at repo root",
+    run(rootDir) {
+      const p = path.join(rootDir, "llms.txt");
+      const ok = fs.existsSync(p) && fs.statSync(p).isFile();
+      return ok
+        ? { ok: true, hint: null, details: { path: p } }
+        : { ok: false, hint: "Add llms.txt at repo root with a single-fetch index of docs + commands.", details: {} };
+    },
+  },
+  {
+    id: "llms-txt-valid",
+    weight: 10,
+    description: "llms.txt has at least one section heading and one link",
+    run(rootDir) {
+      const p = path.join(rootDir, "llms.txt");
+      if (!fs.existsSync(p)) return { ok: false, hint: "llms.txt missing — see llms-txt-present.", details: {} };
+      const text = safeRead(p);
+      const hasSection = /^##\s+/m.test(text);
+      const hasLink = /\[[^\]]+\]\([^)]+\)/.test(text);
+      const ok = hasSection && hasLink;
+      return ok
+        ? { ok: true, hint: null, details: { hasSection, hasLink } }
+        : { ok: false, hint: "Add `## Section` headings and `[label](path)` links to llms.txt.", details: { hasSection, hasLink } };
+    },
+  },
+  {
+    id: "robots-allowlist",
+    weight: 10,
+    description: "robots.txt explicitly Allows AI crawlers",
+    run(rootDir) {
+      // Check root or public/.
+      const candidates = ["robots.txt", "public/robots.txt", "static/robots.txt"];
+      const found = candidates.find((c) => fs.existsSync(path.join(rootDir, c)));
+      if (!found) return { ok: false, hint: "Add robots.txt with `User-agent: GPTBot|ClaudeBot|PerplexityBot\\nAllow: /` blocks.", details: {} };
+      const text = safeRead(path.join(rootDir, found));
+      const aiBots = ["GPTBot", "ClaudeBot", "PerplexityBot", "anthropic-ai", "Google-Extended"];
+      const allowed = aiBots.filter((bot) => new RegExp(`User-agent:\\s*${bot}[\\s\\S]*?Allow:\\s*/`, "i").test(text));
+      const ok = allowed.length > 0;
+      return ok
+        ? { ok: true, hint: null, details: { found, allowed } }
+        : { ok: false, hint: `robots.txt found at ${found} but no AI crawler explicitly Allowed. Add explicit User-agent: ClaudeBot blocks.`, details: { found, allowed } };
+    },
+  },
+  {
+    id: "page-token-budget",
+    weight: 15,
+    description: "every .md doc fits within ≈ 8K tokens (32 KB raw)",
+    run(rootDir) {
+      const docsDir = path.join(rootDir, "docs");
+      if (!fs.existsSync(docsDir)) {
+        // No docs/ at all is its own kind of agent-unfriendly, but
+        // not strictly a budget violation. Pass with a hint.
+        return { ok: true, hint: "No docs/ directory found. Consider adding one.", details: { docsDirPresent: false } };
+      }
+      const oversized = listMarkdownFiles(docsDir).filter((f) => fs.statSync(f).size > PAGE_BYTE_LIMIT);
+      if (oversized.length === 0) {
+        return { ok: true, hint: null, details: { oversizedCount: 0 } };
+      }
+      const sample = oversized.slice(0, 3).map((f) => `${path.relative(rootDir, f)} (${(fs.statSync(f).size / 1024).toFixed(1)} KB)`);
+      return {
+        ok: false,
+        hint: `Split or trim ${oversized.length} oversized doc(s): ${sample.join(", ")}.`,
+        details: { oversizedCount: oversized.length, sample },
+      };
+    },
+  },
+  {
+    id: "heading-hierarchy",
+    weight: 10,
+    description: "each .md has exactly one H1 and no skipped levels",
+    run(rootDir) {
+      const docsDir = path.join(rootDir, "docs");
+      if (!fs.existsSync(docsDir)) return { ok: true, hint: null, details: { docsDirPresent: false } };
+      const violations = [];
+      for (const f of listMarkdownFiles(docsDir)) {
+        const text = safeRead(f);
+        const h1Count = (text.match(/^#\s+/gm) || []).length;
+        if (h1Count !== 1) {
+          violations.push({ file: path.relative(rootDir, f), h1Count });
+          continue;
+        }
+        // Check for skipped levels (#### without preceding ###, etc.)
+        const headings = [...text.matchAll(/^(#{1,6})\s/gm)].map((m) => m[1].length);
+        let prev = 0;
+        for (const lvl of headings) {
+          if (prev > 0 && lvl > prev + 1) {
+            violations.push({ file: path.relative(rootDir, f), reason: `H${prev}→H${lvl} skip` });
+            break;
+          }
+          prev = lvl;
+        }
+      }
+      if (violations.length === 0) {
+        return { ok: true, hint: null, details: { violationsCount: 0 } };
+      }
+      const sample = violations.slice(0, 3);
+      return {
+        ok: false,
+        hint: `Fix heading hierarchy in ${violations.length} doc(s): ${sample.map((v) => v.file).join(", ")}.`,
+        details: { violationsCount: violations.length, sample },
+      };
+    },
+  },
+  {
+    id: "agents-readme",
+    weight: 10,
+    description: "docs/agents/README.md as agent entry point",
+    run(rootDir) {
+      const p = path.join(rootDir, "docs/agents/README.md");
+      const ok = fs.existsSync(p);
+      return ok
+        ? { ok: true, hint: null, details: { path: p } }
+        : { ok: false, hint: "Create docs/agents/README.md as the agent-facing index (links from llms.txt).", details: {} };
+    },
+  },
+  {
+    id: "skill-md-coverage",
+    weight: 20,
+    description: "at least one SKILL.md per declared CLI capability",
+    run(rootDir) {
+      const skillDir = path.join(rootDir, "docs/agents");
+      if (!fs.existsSync(skillDir)) return { ok: false, hint: "Create docs/agents/ with one SKILL.<command>.md per CLI capability.", details: {} };
+      const skillFiles = fs.readdirSync(skillDir).filter((f) => /^SKILL\..+\.md$/.test(f));
+      if (skillFiles.length === 0) {
+        return { ok: false, hint: "Add SKILL.<command>.md files documenting each CLI capability.", details: { skillFilesCount: 0 } };
+      }
+      // We don't enumerate the user's own CLI here (out of scope for a
+      // generic auditor). At least 1 SKILL.md is the minimum signal.
+      return { ok: true, hint: null, details: { skillFilesCount: skillFiles.length } };
+    },
+  },
+];
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, "utf8"); } catch { return ""; }
+}
+
+function listMarkdownFiles(dir, out = []) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.name.startsWith(".") || e.name === "node_modules") continue;
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) listMarkdownFiles(p, out);
+    else if (e.isFile() && e.name.endsWith(".md")) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Run every agent-readiness check against `rootDir`. Returns a
+ * report with score, per-check results, and ranked remediation hints.
+ *
+ * @param {string} rootDir — absolute path to the repo root to audit
+ * @returns {{ score: number, checks: object[], topFixes: object[] }}
+ */
+export function runAgentReadiness(rootDir) {
+  const checks = [];
+  let earned = 0;
+  let possible = 0;
+  for (const c of CHECKS) {
+    possible += c.weight;
+    let result;
+    try {
+      result = c.run(rootDir);
+    } catch (err) {
+      result = { ok: false, hint: `Check threw: ${err.message}`, details: { error: err.message } };
+    }
+    if (result.ok) earned += c.weight;
+    checks.push({
+      id: c.id,
+      description: c.description,
+      weight: c.weight,
+      score: result.ok ? c.weight : 0,
+      ok: result.ok,
+      hint: result.hint,
+      details: result.details || {},
+    });
+  }
+  const score = possible === 0 ? 0 : Math.round((earned / possible) * 100);
+  const topFixes = checks
+    .filter((c) => !c.ok && c.hint)
+    .sort((a, b) => b.weight - a.weight)
+    .slice(0, 5)
+    .map((c, i) => ({
+      priority: i + 1,
+      checkId: c.id,
+      weightLost: c.weight,
+      action: c.hint,
+    }));
+  return { score, possible, earned, checks, topFixes };
+}
+
+/**
+ * Render the report in plain text for the human terminal.
+ */
+export function formatAgentReadinessReport({ score, checks, topFixes }, rootDir) {
+  const lines = [`Agent Readiness — ${rootDir}: ${score}/100`, ""];
+  for (const c of checks) {
+    const tick = c.ok ? "✓" : "✗";
+    const pts = `(+${c.score})`.padStart(6);
+    lines.push(`  ${tick} ${c.description.padEnd(50)} ${pts}${c.hint ? "  " + c.hint : ""}`);
+  }
+  if (topFixes.length > 0) {
+    lines.push("", "Top fixes:");
+    for (const f of topFixes) {
+      lines.push(`  ${f.priority}. [${f.checkId}] ${f.action}`);
+    }
+  }
+  return lines.join("\n");
+}

package/src/bootstrap.js

@@ -36,7 +36,7 @@ function getPackageVersion() {
 // ── Individual checks ────────────────────────────────────────────────
 
 async function checkGitRepo() {
-  let ok = false;
+  let ok;
   try {
     ok = await ensureGitRepo();
   } catch { /* git may not be installed */
@@ -219,6 +219,31 @@ function formatBootstrapFailure(failures) {
  * Throws Error with actionable message if any prerequisite fails.
  */
 export async function ensureBootstrap(projectDir, config) {
+  // Plugin discovery runs unconditionally on every bootstrap, regardless
+  // of whether the bootstrap cache says environment is valid. A user
+  // dropping a new file into `.karajan/plugins/` expects it to be picked
+  // up without running `kj init` again.
+  //
+  // Pre-v2.7.5 this was never called — `loadPlugins()` was exported but
+  // never imported from production code, so any plugin the user added
+  // was silently ignored. Fixed in TSK-0329.
+  try {
+    const { loadPlugins } = await import("./plugins/loader.js");
+    await loadPlugins({ projectDir });
+  } catch { /* plugin system failed — non-blocking, continue bootstrap */ }
+
+  // TSK-0339: register the Planning Game adapter in the integrations registry
+  // when enabled. The orchestrator no longer imports `src/planning-game/*`
+  // directly — it calls `getIntegration("tracker")?.hookName(...)` instead.
+  // Other trackers (GitHub Projects, Jira, Linear, …) drop in by writing
+  // a sibling adapter that calls `registerIntegration("tracker", …)`.
+  if (config?.planning_game?.enabled) {
+    try {
+      const { registerPgAdapter } = await import("./planning-game/pipeline-adapter.js");
+      await registerPgAdapter();
+    } catch { /* PG registration failed — non-blocking, continue bootstrap */ }
+  }
+
   const cached = await readBootstrapFile(projectDir);
   if (isBootstrapValid(cached, projectDir)) {
     return; // Environment already validated

package/src/brain/decision-tracker.js

@@ -11,6 +11,8 @@
  * the session for human input.
  */
 
+import { setBrainDecisions } from "../session/mutators.js";
+
 export const DEFAULT_MAX_DECISIONS = 20;
 export const INDECISION_REPEAT_THRESHOLD = 3; // 3 identical classifications in a row
 
@@ -42,7 +44,7 @@ export const INDECISION_REPEAT_THRESHOLD = 3; // 3 identical classifications in
  */
 export function createTracker(session, { max = DEFAULT_MAX_DECISIONS } = {}) {
   if (!Array.isArray(session.brainDecisions)) {
-    session.brainDecisions = [];
+    setBrainDecisions(session, []);
   }
   return { session, max };
 }

package/src/brain/decisor.js

@@ -125,7 +125,7 @@ function applyOverrides(roles, overrides) {
  * @param {{ forceRoles?: string[], skipRoles?: string[] }} [args.overrides]
  * @returns {Decision}
  */
-export function buildDecision({ triage, task, config = {}, overrides = {} } = {}) {
+export function buildDecision({ triage, task: _task, config = {}, overrides = {} } = {}) {
   const level = triage?.level || "simple";
   const taskType = triage?.taskType || "sw";
 

package/src/canvas/parse-md.js

@@ -0,0 +1,238 @@
+/**
+ * REASONS Canvas markdown parser.
+ *
+ * Reads a `SPEC.canvas.md` file and returns a Canvas object that
+ * validates against canvas/schema.js.
+ *
+ * Format:
+ *
+ *   # <title>
+ *
+ *   ## REASONS:Requirements
+ *   <problem statement, free text>
+ *
+ *   Definition of done:
+ *   - bullet 1
+ *   - bullet 2
+ *
+ *   ## REASONS:Entities
+ *   - `User` — fields: id, email. has-many Order.
+ *   - `Order` — ...
+ *
+ *   ## REASONS:Approach
+ *   <free text>
+ *
+ *   ## REASONS:Structure
+ *   - touches: src/auth/*, src/orders/*
+ *   - depends_on: TokenService
+ *   - contracts: POST /orders, GET /orders/:id
+ *
+ *   ## REASONS:Operations
+ *   1. <title>
+ *      Acceptance:
+ *      - shell: `cmd here`
+ *      - gherkin: ```Given … When … Then …```
+ *   2. ...
+ *
+ *   ## REASONS:Norms
+ *   - bullet
+ *
+ *   ## REASONS:Safeguards
+ *   - bullet
+ *
+ * Permissive on whitespace and bullet style ("- ", "* ", "1. ").
+ * Strict on structure: a missing required section ⇒ exception with a
+ * pointer to which section is missing.
+ */
+
+const SECTION_HEADER_RE = /^##\s+REASONS:(\w+)\s*$/i;
+const TITLE_RE = /^#\s+(.+?)\s*$/;
+const BULLET_RE = /^\s*(?:[-*]|\d+\.)\s+(.+?)\s*$/;
+const ACCEPTANCE_HEADER_RE = /^\s*Acceptance(?:\s+tests?)?\s*:\s*$/i;
+const TEST_LINE_RE = /^\s*(?:[-*])\s+(shell|gherkin)\s*:\s*(.+?)\s*$/i;
+
+/**
+ * Parse a SPEC.canvas.md string into a Canvas object.
+ * Throws { name: "CanvasParseError", message } on missing required sections.
+ *
+ * @param {string} source — markdown text
+ * @returns {object} Canvas object (un-validated against schema; caller validates)
+ */
+export function parseCanvasMarkdown(source) {
+  if (typeof source !== "string" || source.length === 0) {
+    throw makeError("Canvas markdown is empty or not a string.");
+  }
+
+  const lines = source.split(/\r?\n/);
+  const sections = {};
+  let title = null;
+  let currentName = null;
+  let currentBuf = [];
+
+  // First pass: split into sections.
+  for (const line of lines) {
+    const titleMatch = line.match(TITLE_RE);
+    if (titleMatch && currentName === null && title === null) {
+      title = titleMatch[1].trim();
+      continue;
+    }
+    const sectionMatch = line.match(SECTION_HEADER_RE);
+    if (sectionMatch) {
+      // flush previous
+      if (currentName) {
+        sections[currentName] = currentBuf.join("\n");
+      }
+      currentName = sectionMatch[1].toLowerCase();
+      currentBuf = [];
+      continue;
+    }
+    if (currentName) currentBuf.push(line);
+  }
+  if (currentName) sections[currentName] = currentBuf.join("\n");
+
+  if (!title) throw makeError("Missing title — first line must be `# <title>`.");
+
+  // Required sections — must be PRESENT (header exists), but content
+  // may be empty for sections like Structure where every key is
+  // optional. Use `in` so an empty-body section is accepted.
+  for (const required of ["requirements", "approach", "structure", "operations"]) {
+    if (!(required in sections)) {
+      throw makeError(`Missing required section: ## REASONS:${capitalize(required)}`);
+    }
+  }
+
+  return {
+    title,
+    requirements: parseRequirements(sections.requirements),
+    entities: sections.entities ? parseEntities(sections.entities) : [],
+    approach: sections.approach.trim(),
+    structure: parseStructure(sections.structure),
+    operations: parseOperations(sections.operations),
+    norms: sections.norms ? parseBullets(sections.norms) : [],
+    safeguards: sections.safeguards ? parseBullets(sections.safeguards) : [],
+  };
+}
+
+function capitalize(s) {
+  return s.length > 0 ? s[0].toUpperCase() + s.slice(1) : s;
+}
+
+function makeError(msg) {
+  const e = new Error(msg);
+  e.name = "CanvasParseError";
+  return e;
+}
+
+/**
+ * Requirements: a paragraph (problem) + optional "Definition of done:" bullets.
+ */
+function parseRequirements(text) {
+  const lines = text.split("\n");
+  const problemLines = [];
+  const done = [];
+  let inDone = false;
+  for (const line of lines) {
+    if (/^\s*Definition of done:?\s*$/i.test(line)) { inDone = true; continue; }
+    if (inDone) {
+      const m = line.match(BULLET_RE);
+      if (m) done.push(m[1].trim());
+      continue;
+    }
+    if (line.trim()) problemLines.push(line.trim());
+  }
+  const problem = problemLines.join(" ").trim();
+  if (!problem) throw makeError("REASONS:Requirements is empty or has no problem statement.");
+  return { problem, done };
+}
+
+/**
+ * Entities: each bullet is "Name — fields: f1, f2. notes." (loose).
+ * We parse the first word as the entity name and capture the rest as notes.
+ */
+function parseEntities(text) {
+  const out = [];
+  for (const raw of text.split("\n")) {
+    const m = raw.match(BULLET_RE);
+    if (!m) continue;
+    const body = m[1].trim();
+    // First token (possibly `quoted`) is the name; rest is notes.
+    const nameMatch = body.match(/^[`"']?([A-Za-z][\w-]*)[`"']?\s*[—-]?\s*(.*)$/);
+    if (!nameMatch) continue;
+    const [, name, rest] = nameMatch;
+    const fields = [];
+    const fm = rest.match(/fields?:\s*([^.]+)/i);
+    if (fm) fields.push(...fm[1].split(",").map((s) => s.trim()).filter(Boolean));
+    out.push({ name, fields, notes: rest });
+  }
+  return out;
+}
+
+function parseStructure(text) {
+  const out = { touches: [], depends_on: [], contracts: [] };
+  for (const raw of text.split("\n")) {
+    const m = raw.match(BULLET_RE);
+    if (!m) continue;
+    const body = m[1].trim();
+    const kvMatch = body.match(/^(touches|depends_on|contracts)\s*:\s*(.+)$/i);
+    if (!kvMatch) continue;
+    const key = kvMatch[1].toLowerCase();
+    const values = kvMatch[2].split(",").map((s) => s.trim()).filter(Boolean);
+    out[key] = values;
+  }
+  return out;
+}
+
+function parseBullets(text) {
+  const out = [];
+  for (const raw of text.split("\n")) {
+    const m = raw.match(BULLET_RE);
+    if (m) out.push(m[1].trim());
+  }
+  return out;
+}
+
+/**
+ * Operations: each top-level numbered/bulleted entry is one Operation.
+ * Inside, an "Acceptance:" sub-line introduces nested bullets where each
+ * bullet is "shell: <cmd>" or "gherkin: <scenario>".
+ */
+function parseOperations(text) {
+  const ops = [];
+  const lines = text.split("\n");
+  let current = null;
+  let inAcceptance = false;
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    // Top-level operation: numbered list or single dash at left margin.
+    const topMatch = line.match(/^(\d+\.\s+|[-*]\s+)(.+)$/);
+    if (topMatch && !line.startsWith("    ") && !line.startsWith("\t")) {
+      if (current) ops.push(current);
+      current = { title: topMatch[2].trim(), acceptance: [] };
+      inAcceptance = false;
+      continue;
+    }
+    if (current) {
+      if (ACCEPTANCE_HEADER_RE.test(line)) { inAcceptance = true; continue; }
+      const testMatch = line.match(TEST_LINE_RE);
+      if (testMatch && inAcceptance) {
+        current.acceptance.push({
+          type: testMatch[1].toLowerCase(),
+          content: testMatch[2].replace(/^`+|`+$/g, "").trim(),
+        });
+      }
+    }
+  }
+  if (current) ops.push(current);
+
+  if (ops.length === 0) {
+    throw makeError("REASONS:Operations has no operations. Each operation must be a numbered or bulleted item with at least one acceptance test.");
+  }
+  for (const op of ops) {
+    if (op.acceptance.length === 0) {
+      throw makeError(`Operation "${op.title}" has no acceptance tests. Add at least one ` +
+        '`- shell: <cmd>` or `- gherkin: <scenario>` under an "Acceptance:" line.');
+    }
+  }
+  return ops;
+}

package/src/canvas/schema.js

@@ -0,0 +1,101 @@
+/**
+ * REASONS Canvas — Valibot schema for the structured SPEC format.
+ *
+ * Issue #539. Per Martin Fowler's Structured Prompt-Driven Development
+ * (https://martinfowler.com/articles/structured-prompt-driven/), a
+ * Canvas captures intent in 7 named sections so the planner doesn't
+ * have to improvise. The shape:
+ *
+ *   Requirements — problem + done-when bullets
+ *   Entities     — domain nouns + relationships
+ *   Approach     — strategy + trade-offs
+ *   Structure    — system fit, dependencies, contracts
+ *   Operations   — concrete numbered steps. Each = one HU.
+ *   Norms        — task-level engineering standards
+ *   Safeguards   — non-negotiables: invariants, perf, security
+ *
+ * Operations carry their acceptance tests inline so the planner-time
+ * validator (validate.js) can check them parse BEFORE any LLM call.
+ * That's the bug-class fix this whole feature exists for: the
+ * 2026-04-29 incident where the planner emitted a syntactically-broken
+ * jq query and the coder iterated 3× against an irreparable test.
+ */
+
+import * as v from "valibot";
+
+const NonEmptyString = v.pipe(v.string(), v.minLength(1));
+
+const Entity = v.looseObject({
+  name: NonEmptyString,
+  fields: v.optional(v.array(v.string())),
+  relationships: v.optional(v.array(v.unknown())),
+  notes: v.optional(v.string()),
+});
+
+const AcceptanceTest = v.looseObject({
+  type: v.picklist(["shell", "gherkin"]),
+  content: NonEmptyString,
+  // optional: file hint for tester translation of gherkin
+  file: v.optional(v.string()),
+});
+
+const Operation = v.looseObject({
+  // Either a free-form title or numbered step text.
+  title: NonEmptyString,
+  // Optional: the file or module the operation produces / touches.
+  file_hint: v.optional(v.string()),
+  // Optional: dependencies on other operation titles or HU ids.
+  blocked_by: v.optional(v.array(v.string())),
+  // Required: at least ONE acceptance test per operation. Empty array
+  // is rejected at plan-time so we never ship an HU without a contract.
+  acceptance: v.pipe(v.array(AcceptanceTest), v.minLength(1)),
+});
+
+export const CanvasSchema = v.looseObject({
+  // Title is the project / feature name. The planner uses it as the
+  // plan name unless the user overrides on prompt.
+  title: NonEmptyString,
+  requirements: v.looseObject({
+    problem: NonEmptyString,
+    // Definition-of-done bullets. Empty array allowed — sometimes the
+    // problem statement IS the contract — but a non-empty array
+    // discourages woolly specs.
+    done: v.optional(v.array(NonEmptyString)),
+  }),
+  entities: v.optional(v.array(Entity)),
+  approach: NonEmptyString,
+  structure: v.looseObject({
+    touches: v.optional(v.array(v.string())),
+    depends_on: v.optional(v.array(v.string())),
+    contracts: v.optional(v.array(v.string())),
+  }),
+  operations: v.pipe(v.array(Operation), v.minLength(1)),
+  norms: v.optional(v.array(NonEmptyString)),
+  safeguards: v.optional(v.array(NonEmptyString)),
+});
+
+/**
+ * Validate-only entry point. Throws an Error with the offending path
+ * + message when the canvas doesn't match the schema. The validator
+ * (validate.js) uses this AND adds parse-checks for acceptance tests.
+ *
+ * @param {unknown} canvas
+ * @returns {import("valibot").InferOutput<typeof CanvasSchema>}
+ */
+export function parseCanvas(canvas) {
+  return v.parse(CanvasSchema, canvas);
+}
+
+/**
+ * Soft check: returns the validation result without throwing. Useful
+ * for surfacing every schema error at once instead of bailing on the
+ * first.
+ *
+ * @param {unknown} canvas
+ * @returns {{ success: true, output: object } | { success: false, issues: object[] }}
+ */
+export function safeParseCanvas(canvas) {
+  const r = v.safeParse(CanvasSchema, canvas);
+  if (r.success) return { success: true, output: r.output };
+  return { success: false, issues: r.issues };
+}