@ketecode/loom 0.0.0-stage → 0.2.0

package/rules/rust.md

@@ -0,0 +1,26 @@
+---
+name: rust
+description: Always-on rules for Rust files, covering cargo tooling, error handling, panics, unsafe code, async and dependency hygiene.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: read-only
+  kete-loom/paths: "**/*.rs"
+  kete-loom/owner: "Kete-org"
+---
+
+- Run `cargo fmt`, `cargo clippy --all-targets` and `cargo test` after a change. Fix clippy warnings instead of adding `#[allow]` without a reason.
+- Return `Result` for recoverable failures and propagate with `?`. Add context to errors as they cross a boundary.
+- Use the project's error approach (often `thiserror` for libraries, `anyhow` for applications); never return `Box<dyn Error>` or `String` errors from a public library API without reason.
+- Never use `unwrap()` or `expect()` on input, I/O or anything that can fail at runtime outside tests. Use `expect("why this cannot fail")` only for true invariants.
+- Avoid code that can panic on untrusted input: indexing with `[]`, slicing strings at byte offsets, and unchecked arithmetic (it panics in debug and wraps silently in release). Use `get`, `checked_*` or `saturating_*`.
+- Write `unsafe` only when it is required, keep the block minimal, and add a `// SAFETY:` comment stating the invariant it relies on.
+- Never hold a `std::sync::Mutex` guard across an `.await`; drop it first or use the async runtime's mutex.
+- Never call blocking I/O or long CPU work directly in async code; use the runtime's blocking task facility (such as `spawn_blocking`).
+- Never log or `Debug`-print secrets; implement `Debug` by hand for types that hold them.
+- Use parameterized queries in database code; never build SQL with `format!`.
+- Pass `std::process::Command` separate `.arg()` values; never run `sh -c` with a string built from input.
+- Commit `Cargo.lock` (always for binaries; Cargo now recommends it for libraries too). Do not add a dependency for a few lines of code.
+
+For more, load the rust-patterns and rust-testing skills.

package/rules/security.md

@@ -0,0 +1,29 @@
+---
+name: security
+description: Always-on secure coding rules for any language, covering input validation, injection, authorization, least privilege, deserialisation, dependencies and keeping secrets and personal data out of logs.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: security
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+- Treat all external input as untrusted: request data, headers, cookies, uploaded files, queue messages, LLM output and third-party API responses.
+- Validate input at the trust boundary against an allowlist of type, length, range and format. Reject what fails; do not try to clean it up.
+- Use parameterised queries or the ORM's bound parameters. Never build SQL, NoSQL or LDAP queries by string concatenation or formatting.
+- Run external commands with an argument array and no shell. Never pass user input into a shell string, `eval` or dynamic code execution.
+- Encode output for its context (HTML, attribute, URL, JS) and use the framework's auto-escaping; never mark untrusted data as safe.
+- Resolve user-supplied file paths against a fixed base directory and reject any result outside it.
+- Enforce authentication and authorization on the server for every request and every object accessed. Hidden UI or client checks are not access control.
+- Grant least privilege: minimal scopes for tokens, database users, service accounts, CI jobs and file permissions.
+- Never deserialise untrusted data with formats that can run code (`pickle`, Java native serialization, unsafe YAML loaders). Use JSON or a safe loader with a schema.
+- Validate outbound URLs built from user input against an allowlist of hosts to prevent SSRF.
+- Use the platform's vetted crypto and password-hashing libraries and a cryptographically secure random source for tokens. Never write your own crypto.
+- Keep TLS certificate verification on. Never disable it to make a request work.
+- Never log secrets, tokens, passwords, session IDs or personal data. Redact them in errors, traces and analytics too.
+- Return generic error messages to clients; keep stack traces and internal details in server logs.
+- Add dependencies only when needed, from the official registry, pinned through the lockfile. Check the name for typosquats and run the project's audit tool after changes.
+- Default to secure configuration: deny by default, `Secure`, `HttpOnly` and `SameSite` on session cookies, CSRF protection on state-changing requests that use cookie auth, debug mode off in production.
+
+For more, load the security-review skill.

package/rules/swift.md

@@ -0,0 +1,28 @@
+---
+name: swift
+description: Always-on rules for Swift code, covering optionals, value types, error handling, Swift concurrency and actors, memory and retain cycles, and build and test checks.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: read-only
+  kete-loom/paths: "**/*.swift"
+  kete-loom/owner: "Kete-org"
+---
+
+- Never use `!`, `try!` or `as!` on values that can fail at runtime; use `guard let`, `if let`, `??`, `as?` or a thrown error.
+- Avoid implicitly unwrapped optionals except for values a framework sets before first use, such as outlets.
+- Prefer `let` over `var`, and `struct` or `enum` for data; use `class` when you need identity or shared mutable state.
+- Switch over enums exhaustively; avoid `default` on enums you own so a new case is a compile error, and use `@unknown default` for non-frozen SDK enums.
+- Throw specific, meaningful errors and handle them with `do`/`catch`; never discard them with `try?` where the failure matters.
+- Use `async`/`await` and structured concurrency (`async let`, task groups) over completion handlers in new code.
+- Protect shared mutable state with an `actor` or `@MainActor`; never mutate it from several tasks unguarded.
+- Update UI only on the main actor.
+- Make types that cross concurrency domains `Sendable`, and fix concurrency warnings; use `@unchecked Sendable` or `nonisolated(unsafe)` only when you add the synchronization yourself and say why in a comment.
+- Check `Task.isCancelled` or call `try Task.checkCancellation()` in long-running work.
+- Capture `self` weakly (`[weak self]`) in escaping closures stored by `self` or its children, to avoid retain cycles.
+- Mark delegate properties `weak`.
+- Never store secrets in `UserDefaults` or plain files; use the Keychain.
+- Build and test with the project's configured tooling (`swift build` and `swift test` for packages, or the Xcode scheme), and use its configured formatter or linter.
+
+For more, load the swift-patterns and swift-testing skills.

package/rules/testing.md

@@ -0,0 +1,25 @@
+---
+name: testing
+description: Always-on rules for writing and running tests in any language, covering behaviour-focused tests, failing tests first for bugs, determinism, isolation, speed and running the suite before finishing.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+- Use the project's configured test framework, runner and file layout. Do not add a second one.
+- Test behaviour through the public interface: inputs, outputs and observable effects. Do not assert on private methods or internal call order.
+- For a bug, first write a test that reproduces it and watch it fail, then fix the code until it passes.
+- Give each test one reason to fail and a name that says the expected behaviour.
+- Cover edge cases and error paths, not just the happy path: empty, boundary, invalid and failing-dependency inputs.
+- Make tests deterministic. Inject or fake the clock, seed any randomness and never depend on test order, wall-clock time or time zone.
+- Never use fixed sleeps to wait. Wait on a condition with a timeout, or use fake timers.
+- Keep tests isolated: each test sets up and tears down its own state, uses temporary directories and never relies on shared mutable globals.
+- Never call the real network or third-party services in unit tests. Fake slow or nondeterministic boundaries (network, clock, external APIs); use real objects for the code under test.
+- Keep unit tests fast; move slow integration and end-to-end tests to their own suite.
+- A flaky test is a bug: find the cause instead of adding retries.
+- Run the relevant tests after every change and the full suite before finishing.
+
+For more, load the tdd-workflow skill and the testing skill for your language, such as python-testing or typescript-testing.

package/rules/typescript.md

@@ -0,0 +1,29 @@
+---
+name: typescript
+description: Always-on rules for TypeScript and JavaScript files, covering type safety, untrusted input, async errors, modules and the project's own tooling.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: read-only
+  kete-loom/paths: "**/*.ts, **/*.tsx, **/*.mts, **/*.cts, **/*.js, **/*.jsx, **/*.mjs, **/*.cjs"
+  kete-loom/owner: "Kete-org"
+---
+
+- Use the project's package manager (the one its lockfile belongs to), formatter, linter and test runner. Never add a second lockfile.
+- Run the project's type check (often `tsc --noEmit`) and lint after a change, not only the tests.
+- Never weaken `tsconfig.json` or lint settings to make an error go away.
+- Never silence the compiler with `any`, `as any`, `@ts-ignore` or a `!` non-null assertion. If a suppression is truly needed, use `@ts-expect-error` with a reason.
+- Type values you have not checked as `unknown` and narrow them. Validate untrusted input (request bodies, `JSON.parse`, env vars, files) at the boundary with the project's schema library or a type guard.
+- End a `switch` over a union with a `never` check so a new case fails to compile.
+- Use `const` by default, `let` when reassigned, never `var`. Use `===` and `!==` (the project's `== null` idiom aside).
+- Await or return every promise, or mark it with `void` and handle its rejection. Never leave a floating promise.
+- Never pass an async function to `forEach`; use `for...of` with `await`, or `Promise.all` / `Promise.allSettled` over `map`.
+- Catch errors as `unknown`, and throw `Error` objects, never strings. Pass the original as `{ cause }` when wrapping.
+- Use `?.` and `??` for missing values; `||` also replaces `0`, `""` and `false`.
+- Never build HTML, SQL, shell commands or file paths by string concatenation with user input. Use parameterized queries, `execFile`/`spawn` with an argument array, and the framework's escaping.
+- Never use `eval`, `new Function` or `innerHTML` with untrusted data.
+- Match the package's module system (`"type"` in `package.json`, `.mjs`/`.cjs`); never mix `require` and `import` in one file.
+- Never put secrets in client code or in env vars the framework exposes to the browser (such as `NEXT_PUBLIC_` or `VITE_`).
+
+For more, load the typescript-patterns and typescript-testing skills.

package/rules/use-skills.md

@@ -0,0 +1,23 @@
+---
+name: use-skills
+description: Always-on rule to check for an installed skill, agent or command that fits a task before starting it, say which one is used, and follow its steps rather than working from memory.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: meta
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+- Before starting a task, including a clarifying question or a quick look at the code, check whether an installed skill, agent or command covers it. Check again when the task changes.
+- If one fits even partly, load it and tell the user in one line which one you are using and why.
+- Prefer the most specific match: a framework skill over a language skill, a language reviewer over a general one.
+- Process skills (brainstorming, debugging, test-first, planning) come before implementation skills; they decide how the work is done.
+- Follow a loaded skill's steps in order. Do not skip a step because you remember the gist or the task looks simple.
+- Where a skill has a checklist, work through every item and report each one.
+- Treat a skill's "stop and ask" points as real stops; do not guess past them.
+- Read a skill's `references/` files when its steps tell you to, not from memory of similar files.
+- Delegate to an agent when its description matches and its separate context helps (reviews, wide searches, build fixes).
+- If no skill fits, say so briefly and work normally; do not force a poor match.
+- The user's explicit instructions win over any skill. When they conflict, follow the user and mention the conflict once.
+- Never claim to have followed a skill you did not load.

package/schemas/skill-frontmatter.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ketecode.ai/schemas/kete-loom/skill-frontmatter.schema.json",
+  "title": "Kete Loom SKILL.md frontmatter",
+  "description": "The strictest common subset of the Agent Skills spec (agentskills.io) as read by Claude Code, Codex, OpenCode, Cursor, Gemini CLI and GitHub Copilot, plus Kete Loom's metadata keys. Extra keys live under `metadata` as strings, because OpenCode requires metadata to be a string-to-string map.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "description", "license", "metadata"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "Must equal the skill's folder name."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 80,
+      "maxLength": 1024,
+      "description": "Single line. Says what the skill does AND when to use it (contains 'Use when')."
+    },
+    "license": { "type": "string" },
+    "compatibility": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Plain-language environment requirements (tools, network, OS)."
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "required": ["kete-loom/version", "kete-loom/category", "kete-loom/risk"],
+      "properties": {
+        "kete-loom/version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+        "kete-loom/category": {
+          "type": "string",
+          "enum": ["coding", "testing", "security", "integrations", "devops", "data", "ai", "docs", "business", "compliance", "meta"]
+        },
+        "kete-loom/risk": {
+          "type": "string",
+          "enum": ["read-only", "writes-files", "runs-commands", "network"],
+          "description": "Highest-impact action the skill instructs the agent to take."
+        },
+        "kete-loom/requires": {
+          "type": "string",
+          "description": "Comma-separated CLIs or runtimes the skill expects, e.g. 'git, node'."
+        },
+        "kete-loom/owner": { "type": "string" }
+      }
+    }
+  }
+}

package/scripts/lib/audit.js

@@ -0,0 +1,96 @@
+'use strict';
+
+// `kete-loom audit`: a deterministic readiness scorecard for working on a project with coding agents.
+// Same input, same result: it reads files and runs read-only git commands, never a model.
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { detect } = require('./profiles');
+const { inventory } = require('./inventory');
+
+const CODEX_MAX_BYTES = 32768;
+const DETECT_CHECKS = path.join(__dirname, '..', '..', 'skills', 'verification-loop', 'scripts', 'detect-checks.js');
+
+const git = (cwd, args) => {
+  try {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).trim();
+  } catch {
+    return null;
+  }
+};
+
+function audit({ cwd = process.cwd(), home, catalog }) {
+  const checks = [];
+  const add = (id, status, title, detail, fix) => checks.push({ id, status, title, detail, ...(fix ? { fix } : {}) });
+  const root = git(cwd, ['rev-parse', '--show-toplevel']) || cwd;
+  const has = (f) => fs.existsSync(path.join(root, f));
+
+  if (git(cwd, ['rev-parse', '--is-inside-work-tree']) === 'true') add('git', 'pass', 'Git repository', 'Agents can see history, diffs and status.');
+  else add('git', 'warn', 'Git repository', 'This folder is not a git repository, so agents can\'t diff, review or roll back their changes.', 'git init');
+
+  const instr = ['AGENTS.md', 'CLAUDE.md'].filter(has);
+  if (!instr.length) add('instructions', 'fail', 'Agent instructions', 'No AGENTS.md or CLAUDE.md: every agent starts without your build commands, conventions or boundaries.', 'Write AGENTS.md (the /project-init command or the codebase-onboarding skill can draft it)');
+  else {
+    const big = instr.filter((f) => fs.statSync(path.join(root, f)).size > CODEX_MAX_BYTES);
+    if (big.length) add('instructions', 'warn', 'Agent instructions', `${big.join(', ')} is over 32 KiB; Codex stops reading there and every host pays for it on every turn.`, 'Move detail into skills, rules or linked docs');
+    else add('instructions', 'pass', 'Agent instructions', `${instr.join(' and ')} present.`);
+  }
+
+  const found = detect(root);
+  const installedRows = [...inventory({ scope: 'user', home, cwd: root }), ...inventory({ scope: 'project', home, cwd: root })];
+  const installedNames = new Set(installedRows.map((r) => r.name));
+  if (!found.length) add('packs', 'pass', 'Packs for this stack', 'No language or framework detected that Kete Loom has a pack for.');
+  else {
+    const want = [...new Set(found.flatMap((d) => [...(d.skills || []), ...(d.agents || []), ...(d.rules || [])]))].filter((n) => ['skills', 'agents', 'rules'].some((k) => (catalog[k] || []).some((i) => i.dir === n)));
+    const missing = want.filter((n) => !installedNames.has(n));
+    const stack = found.map((d) => d.what).join(', ');
+    if (!missing.length) add('packs', 'pass', 'Packs for this stack', `Installed for ${stack}.`);
+    else add('packs', missing.length === want.length ? 'fail' : 'warn', 'Packs for this stack', `Detected ${stack}; missing ${missing.length} of ${want.length}: ${missing.slice(0, 8).join(', ')}${missing.length > 8 ? '…' : ''}.`, 'npx @ketecode/loom install --profile core   (run it in this project)');
+  }
+
+  let commands = [];
+  try {
+    commands = JSON.parse(execFileSync(process.execPath, [DETECT_CHECKS, root], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000 })).checks || [];
+  } catch (e) {
+    // detect-checks exits 3 when it finds nothing; its JSON is still on stdout.
+    try {
+      commands = JSON.parse(e.stdout || '{}').checks || [];
+    } catch {
+      commands = [];
+    }
+  }
+  const kinds = new Set(commands.map((c) => c.kind));
+  if (!kinds.has('test')) add('verification', 'fail', 'Verification commands', 'No test command found, so agents can\'t prove a change works.', 'Add a test script (package.json "test", Makefile "test", pytest config…) and name it in AGENTS.md');
+  else if (!kinds.has('lint') && !kinds.has('typecheck')) add('verification', 'warn', 'Verification commands', `Tests found (${commands.find((c) => c.kind === 'test').command}), but no lint or type-check command.`, 'Add a lint or type-check script so agents catch mistakes before tests');
+  else add('verification', 'pass', 'Verification commands', commands.map((c) => c.command).join(', '));
+
+  const ci = ['.github/workflows', '.gitlab-ci.yml', '.circleci', 'azure-pipelines.yml', 'bitbucket-pipelines.yml', 'Jenkinsfile', '.buildkite'].filter(has);
+  if (ci.length) add('ci', 'pass', 'Continuous integration', `${ci.join(', ')}.`);
+  else add('ci', 'warn', 'Continuous integration', 'No CI configuration found, so nothing re-checks what agents push.', 'Add CI that runs the same build, lint and test commands (the github-actions-ci skill can set it up)');
+
+  const hooks = new Set(installedRows.filter((r) => r.kind === 'hooks').map((r) => r.name));
+  const safety = ['block-dangerous-commands', 'guard-secrets'];
+  const missingHooks = safety.filter((h) => !hooks.has(h));
+  if (!missingHooks.length) add('hooks', 'pass', 'Safety hooks', `${safety.join(' and ')} are installed.`);
+  else add('hooks', 'warn', 'Safety hooks', `Not installed: ${missingHooks.join(', ')}. Nothing stops an agent from running rm -rf ~ or writing a key into a file.`, `npx @ketecode/loom install --hook ${missingHooks.join(',')}`);
+
+  const tracked = (git(root, ['ls-files']) || '').split('\n').filter((f) => /(^|\/)\.env(\.[^/]*)?$/.test(f) && !/\.(example|sample|template|dist|defaults)$/.test(f));
+  const ignore = has('.gitignore') ? fs.readFileSync(path.join(root, '.gitignore'), 'utf8') : '';
+  if (tracked.length) add('secrets', 'fail', 'Secrets', `Committed environment files: ${tracked.join(', ')}. Anything in them is in git history.`, 'git rm --cached the files, add .env* to .gitignore, and rotate every secret they held');
+  else if (!/^\s*\/?\.env\*?\s*$|^\s*\.\*\s*$|^\s*\*\.env\s*$/m.test(ignore)) add('secrets', 'warn', 'Secrets', '.gitignore does not ignore .env files, so the next one created can be committed by accident.', 'Add .env and .env.* to .gitignore (keep .env.example tracked)');
+  else add('secrets', 'pass', 'Secrets', 'No environment files committed, and .gitignore covers them.');
+
+  if (has('package.json')) {
+    const locks = ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb', 'npm-shrinkwrap.json'].filter(has);
+    if (locks.length) add('lockfile', 'pass', 'Dependency lockfile', locks.join(', '));
+    else add('lockfile', 'warn', 'Dependency lockfile', 'package.json without a lockfile: agents and CI can resolve different dependency versions.', 'Run your package manager\'s install and commit the lockfile');
+  }
+
+  const weight = { pass: 1, warn: 0.5, fail: 0 };
+  const score = Math.round((checks.reduce((n, c) => n + weight[c.status], 0) / checks.length) * 100);
+  const order = { fail: 0, warn: 1, pass: 2 };
+  return { root, score, checks: checks.sort((a, b) => order[a.status] - order[b.status]) };
+}
+
+module.exports = { audit };

package/scripts/lib/behavior.js

@@ -0,0 +1,52 @@
+'use strict';
+
+// Behaviour evals: evals/behavior.json in a skill or agent folder. Each scenario is a user request
+// (often with pressure to skip the item's discipline), optional files the agent can see, and what the
+// reply must and must not show. scripts/run-behavior-evals.js runs them with and without the item.
+
+const fs = require('fs');
+const path = require('path');
+
+const PRESSURES = ['time', 'sunk-cost', 'authority', 'exhaustion', 'social', 'pragmatism', 'small-scope'];
+const MIN_SCENARIOS = 2;
+
+const behaviorFile = (item) => path.join(item.path, 'evals', 'behavior.json');
+
+// Returns null when the item has no behavior.json, else { scenarios, problems }.
+function loadBehavior(item) {
+  const file = behaviorFile(item);
+  if (!fs.existsSync(file)) return null;
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (e) {
+    return { scenarios: [], problems: [`evals/behavior.json is not valid JSON: ${e.message}`] };
+  }
+  return { scenarios: Array.isArray(data.scenarios) ? data.scenarios : [], problems: validate(data) };
+}
+
+function validate(data) {
+  const problems = [];
+  const list = data && Array.isArray(data.scenarios) ? data.scenarios : null;
+  if (!list) return ['evals/behavior.json needs a "scenarios" array'];
+  if (list.length < MIN_SCENARIOS) problems.push(`evals/behavior.json needs at least ${MIN_SCENARIOS} scenarios`);
+  const names = new Set();
+  list.forEach((s, i) => {
+    const at = `scenario ${i + 1}${s && typeof s.name === 'string' ? ` "${s.name}"` : ''}`;
+    if (!s || typeof s !== 'object') return problems.push(`${at} is not an object`);
+    if (typeof s.name !== 'string' || !s.name.trim()) problems.push(`${at} needs a name`);
+    else if (names.has(s.name)) problems.push(`${at}: duplicate name`);
+    else names.add(s.name);
+    if (typeof s.prompt !== 'string' || s.prompt.trim().length < 20) problems.push(`${at}: prompt must be at least 20 characters`);
+    const strings = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string' && x.trim().length >= 10);
+    if (!strings(s.expect) || !s.expect.length) problems.push(`${at}: "expect" must be a non-empty list of criteria (10+ characters each)`);
+    if (s.forbid !== undefined && !strings(s.forbid)) problems.push(`${at}: "forbid" must be a list of criteria (10+ characters each)`);
+    if (s.pressure !== undefined && (!Array.isArray(s.pressure) || s.pressure.some((p) => !PRESSURES.includes(p)))) problems.push(`${at}: "pressure" values must be from ${PRESSURES.join(', ')}`);
+    if (s.files !== undefined && (typeof s.files !== 'object' || Array.isArray(s.files) || Object.entries(s.files).some(([k, v]) => typeof v !== 'string' || path.isAbsolute(k) || k.split(/[\\/]/).includes('..')))) {
+      problems.push(`${at}: "files" maps relative paths to file contents`);
+    }
+  });
+  return problems;
+}
+
+module.exports = { loadBehavior, validate, behaviorFile, PRESSURES, MIN_SCENARIOS };

package/scripts/lib/frontmatter.js

@@ -0,0 +1,65 @@
+'use strict';
+
+// Minimal parser for the frontmatter subset Kete Loom allows:
+//   key: value              (plain or quoted scalar, single line)
+//   metadata:               (one nested level of key: "string" pairs)
+// Anything else (folded scalars, lists, deeper nesting) is reported as an
+// error, because not every host parses full YAML the same way.
+
+// A value that opens with a quote must close with the same one (`"git"\n  key: x` is a broken line, not a string).
+const brokenQuote = (raw) => {
+  const v = raw.trim();
+  if (v.startsWith('"')) return !/^"(?:[^"\\]|\\.)*"\s*(?:#.*)?$/.test(v);
+  if (v.startsWith("'")) return !/^'(?:[^']|'')*'\s*(?:#.*)?$/.test(v);
+  return false;
+};
+
+function unquote(raw) {
+  const v = raw.trim();
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    return { value: v.slice(1, -1), quoted: true };
+  }
+  return { value: v, quoted: false };
+}
+
+function parseFrontmatter(text) {
+  const errors = [];
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+  if (!match) {
+    return { data: null, body: text, errors: ['missing frontmatter block (--- ... ---) at top of file'] };
+  }
+  const data = {};
+  let current = null;
+  const lines = match[1].split(/\r?\n/);
+  lines.forEach((line, i) => {
+    if (!line.trim() || line.trim().startsWith('#')) return;
+    const nested = /^ {2}([^\s:][^:]*):\s*(.*)$/.exec(line);
+    const top = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+    if (top) {
+      const [, key, rest] = top;
+      if (rest === '') {
+        data[key] = {};
+        current = key;
+      } else {
+        if (/^[>|]/.test(rest.trim())) {
+          errors.push(`line ${i + 2}: "${key}" uses a multi-line YAML scalar; keep it on one line`);
+        }
+        if (rest.trim().startsWith('[') || rest.trim().startsWith('{')) {
+          errors.push(`line ${i + 2}: "${key}" uses an inline list/map; only plain strings are portable`);
+        }
+        if (brokenQuote(rest)) errors.push(`line ${i + 2}: "${key}" has an unclosed or mismatched quote`);
+        data[key] = unquote(rest).value;
+        current = null;
+      }
+    } else if (nested && current) {
+      const [, key, rest] = nested;
+      if (brokenQuote(rest)) errors.push(`line ${i + 2}: "${key.trim()}" has an unclosed or mismatched quote`);
+      data[current][key.trim()] = unquote(rest).value;
+    } else {
+      errors.push(`line ${i + 2}: unsupported frontmatter syntax: ${line.trim()}`);
+    }
+  });
+  return { data, body: text.slice(match[0].length), errors };
+}
+
+module.exports = { parseFrontmatter };