pi-aia-asf 0.17.9 → 0.17.10

package/CHANGELOG.md

@@ -7,6 +7,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.10] - 2026-11-10
+
+### Added
+
+- (describe changes for 0.17.10)
+
+## [0.18.0] - 2026-11-10
+
+### Added — the browser evidence the completion gate demands can now be produced
+
+The gate required browser verification whenever a UI file was touched (in two places:
+the ledger's completeness check and the delivery report), but the only registered
+tools were `asf_health` and `asf_decisions`. Any session that edited a tsx/html/css
+file was steered at a gap it had no hands for — the health loop, one layer down. Two
+agent-callable tools now close it, mirroring `asf_health`:
+
+- `asf_browser_verify {page, action, assertion}` — **refused** unless the session
+  actually drove a browser. ASF sees every `tool_call`, so a verification with no
+  browser in the room is a claim about a page nobody opened; `browser_diagnose` and
+  `browser_logs` do not count, because they report on the daemon, not on the surface.
+  All three fields are required: that is the minimum a reviewer can go and repeat.
+- `asf_browser_na {reason}` — **refused** when the reason is a placeholder (`n/a`,
+  `none`, `not applicable`, one word). A structured n/a is worth having only if a
+  reviewer can disagree with it; otherwise it is an exit around the gate.
+
+Recorded, not claimed: a tool that accepted "I verified it" would make the gate
+decorative, and a decorative gate reads as coverage. The rules live in
+`lib/gates/browser-evidence.mjs` (pure, testable without a browser) with a thin
+extension adapter, mirroring the `measure.mjs` / `health-record.ts` split.
+
+### Fixed — five ledger kinds had no producer
+
+`browser-verify`, `browser-na`, `clean-room`, `spec-transition` and `perf-scenario`
+could be validated and rendered but never written. Now:
+
+- `spec-transition` is **observed** from the real `update_spec_status` call, so the
+  delivery report renders actual transitions without anyone remembering to record them;
+- `clean-room` is observed from the release pipeline (`npm run release` /
+  `verify-published.mjs`) together with its exit code — the definition-of-done line
+  about the shipped artifact no longer promises evidence nothing can produce;
+- `perf-scenario` is **dropped**: no producer, no requirement, five mandatory fields
+  nobody could fill.
+
+### Added — the runner can no longer read a suite as green when it never checked
+
+`test/harness.mjs` honoured only `export async function run()` returning false. A
+suite exposing its verdict as the module's default export was ignored entirely —
+which is how a new suite reported "51 passed" while enforcing nothing. The runner now
+reads `run()`, a boolean default, or a boolean `ok`; a suite claiming `selfReports`
+must contain a real failure channel (`process.exit(1)` or `node:test`) or it warns;
+and a suite with none of these is named instead of passing silently. The whole class
+is pinned by `test/test-evidence-kinds.mjs`: every ledger kind must have a producer in
+the shipped package, and no kind a gate *requires* may be an orphan.
+
+Also: `tool-call.ts` passed the 300-line ceiling and its work observers moved to
+`lib/extension/handlers/observe-work.ts`, with pi's `Input`/`Event` shapes declared
+once in `observed.ts` instead of three times; `String(undefined)` → `?? ""` in the
+evidence builders (the literal "undefined" reads like a value and passes a presence
+check); and a redundant guard in `placeholderReason` was deleted because no mutation
+of it failed a test — a guard that cannot be failed is decoration, not protection.
+
 ## [0.17.9] - 2026-11-10
 
 ### Fixed — the health verdict now reports what it measured, not what it planned

package/index.ts

@@ -17,6 +17,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { setPiRef } from "./lib/extension/pi-ref.ts";
 import { registerHealthTool } from "./lib/extension/tools/health.ts";
+import { registerDecisionsTool } from "./lib/extension/tools/decisions.ts";
+import { registerBrowserTools } from "./lib/extension/tools/browser.ts";
 import { registerCommands } from "./lib/extension/commands/index.ts";
 import { registerToolCallHandler } from "./lib/extension/handlers/tool-call.ts";
 import { registerToolResultHandler } from "./lib/extension/handlers/tool-result.ts";
@@ -28,6 +30,8 @@ export { shouldPersist } from "./lib/extension/evidence.ts";
 export default function register(pi: ExtensionAPI): void {
   setPiRef(pi);
   registerHealthTool(pi);
+  registerDecisionsTool(pi);
+  registerBrowserTools(pi);
   registerCommands(pi);
   registerToolCallHandler(pi);
   registerToolResultHandler(pi);

package/lib/code-health/index.mjs

@@ -10,10 +10,12 @@ import { loadConfig } from "./config.mjs";
 import { detectLanguages, planMetrics, resolvePlans } from "./detect.mjs";
 import { listSourceFiles, detectTools, runAll } from "./run.mjs";
 import { evaluateRow, verdict, formatReport, jsonReport, diffRows, formatDiff, baselinePayload } from "./report.mjs";
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { readPath, writePath } from "../home.mjs";
 
-const BASELINE_FILE = ".asf-code-health-baseline.json";
+/** The path ASF reports and tests assert; derived from the home, never a second copy. */
+export const BASELINE_FILE = writePath("", "baseline");
 
 /** Parse CLI args: --diff, --json, --update-baseline, --verbose. */
 export function parseArgs(args) {
@@ -66,11 +68,15 @@ export async function runHealth(projectRoot, args = [], deps = {}) {
 function applyBaselineFlags({ text, rows, root, flags }) {
   if (flags.updateBaseline) {
     const payload = baselinePayload(rows);
-    writeFileSync(join(root, BASELINE_FILE), JSON.stringify(payload, null, 2) + "\n", "utf-8");
+    const file = writePath(root, "baseline");
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(payload, null, 2) + "\n", "utf-8");
     return `${text}\n\nBaseline updated: ${BASELINE_FILE}`;
   }
   if (!flags.diff) return text;
-  const baselinePath = join(root, BASELINE_FILE);
+  // Home first, then the pre-home root file — a project that set a baseline
+  // before the home existed must still diff against its own ratchet.
+  const baselinePath = readPath(root, "baseline");
   let baselineRows = [];
   if (existsSync(baselinePath)) {
     try {
@@ -83,4 +89,3 @@ function applyBaselineFlags({ text, rows, root, flags }) {
   return `${text}\n\n${formatDiff(diffRows(rows, baselineRows))}`;
 }
 
-export { BASELINE_FILE };

package/lib/decisions/consult.d.mts

@@ -0,0 +1,46 @@
+import type { DecisionRecord, DecisionProblem } from "./schema.d.mts";
+
+export interface Register {
+  dir: string;
+  records: DecisionRecord[];
+  problems: DecisionProblem[];
+}
+
+export interface DecisionResult {
+  ok: boolean;
+  file?: string;
+  id?: string;
+  superseded?: string;
+  by?: string;
+  problems?: DecisionProblem[];
+}
+
+export interface AddArgs {
+  record: DecisionRecord;
+  body?: string;
+  config?: Record<string, unknown> | null;
+  planApproved?: boolean;
+  read?: DecisionRecord[];
+}
+
+export interface SupersedeArgs extends AddArgs {
+  id: string;
+  by?: string;
+}
+
+export function registerAt(root: string, config?: Record<string, unknown> | null): Register;
+/**
+ * Project-relative paths: `applies_to` is written relative to the repo while a
+ * run records absolute ones, and the two must be compared on the same footing.
+ */
+export function relativeTo(root: string, files: string[] | undefined): string[];
+export function cardIndex(records: DecisionRecord[] | undefined, opts?: { max?: number; bytes?: number }): string[];
+export function unreadGoverning(
+  records: DecisionRecord[] | undefined,
+  filePath: string,
+  read: string[] | undefined,
+): DecisionRecord[];
+export function citedIds(text: string | undefined, records: DecisionRecord[] | undefined): string[];
+export function addDecision(root: string, args: AddArgs): DecisionResult;
+export function supersedeDecision(root: string, args: SupersedeArgs): DecisionResult;
+export function refreshIndex(root: string, config?: Record<string, unknown> | null): { file: string; count: number };

package/lib/decisions/consult.mjs

@@ -0,0 +1,184 @@
+/**
+ * The consult surface: what the handlers and the tool actually call.
+ *
+ * Kept separate from `store.mjs` because the store is about files and this is
+ * about a *run*: what is in context, what has been read, what has been cited,
+ * and what a new decision has to satisfy before it is allowed to exist. The
+ * rule it enforces is the cheap one that makes the whole register worth
+ * building — a decision only governs work if it was in front of the agent when
+ * that work was written.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { decisionsDir, ensureHome } from "../home.mjs";
+import { loadRegister, governing, indexForCard, writeRecord, updateRecord, nextNumber, writeIndex, fileNameFor } from "./store.mjs";
+import { validateRegister } from "./schema.mjs";
+
+const ID_RE = /ADR-\d{4}/g;
+
+/** Whether a named enforcement check exists — relative to the measured project. */
+function existsIn(root, p) {
+  try {
+    return fs.existsSync(path.join(root, String(p)));
+  } catch {
+    return true;
+  }
+}
+
+/** Read the register for a project. Reading never creates anything. */
+export function registerAt(root, config) {
+  const dir = decisionsDir(root, config || {});
+  const { records, problems } = loadRegister(dir);
+  const exists = (p) => existsIn(root, p);
+  return { dir, records, problems: problems.concat(validateRegister(records, { exists })) };
+}
+
+/** The budgeted index for the run card. */
+export function cardIndex(records, opts) {
+  return indexForCard(records, opts);
+}
+
+/**
+ * Which accepted decisions govern a file the agent is about to change and has
+ * not read this run. That set is the whole read-before-edit floor.
+ */
+export function unreadGoverning(records, filePath, read) {
+  return governing(records, filePath).filter((r) => !(read || []).includes(String(r.id)));
+}
+
+/**
+ * Project-relative paths, because `applies_to` is written relative to the repo
+ * and the run records absolute ones. A path outside the project is left alone —
+ * it governs nothing, and silently dropping it would hide that fact.
+ */
+export function relativeTo(root, files) {
+  return (files || [])
+    .filter((f) => typeof f === "string" && f.trim())
+    .map((f) => {
+      const s = String(f).replace(/\\/g, "/");
+      if (!path.isAbsolute(s)) return s;
+      const rel = path.relative(root, s);
+      return rel && !rel.startsWith("..") ? rel : s;
+    });
+}
+
+/** Which accepted decisions a piece of text cites. */
+export function citedIds(text, records) {
+  const found = String(text || "").match(ID_RE) || [];
+  const known = new Set((records || []).filter((r) => r.status === "accepted").map((r) => String(r.id)));
+  return found.filter((id) => known.has(id));
+}
+
+/** What makes a record law rather than a suggestion. */
+function hasAcceptanceEvidence(d) {
+  return Boolean(String(d.from_spec || "").trim() || String(d.user_instructed || "").trim() || String(d.plan || "").trim());
+}
+
+/**
+ * Default the status rather than refuse the record.
+ *
+ * A record with nothing behind it is a *proposal* — visible, never enforced —
+ * which is the honest default and keeps an unattended run from having to ask.
+ * Evidence (a spec id, the user's own words, an approved plan) is what promotes
+ * it to law, and the validator still refuses `accepted` without it, so a
+ * hand-written or imported record cannot skip the same bar.
+ */
+function defaultStatus(d) {
+  if (d.status) return d.status;
+  if (String(d.origin || "") === "backfill" && Array.isArray(d.source) && d.source.length) return "accepted";
+  return hasAcceptanceEvidence(d) ? "accepted" : "proposed";
+}
+
+/**
+ * Record a new decision.
+ *
+ * An invalid record is **not written**: a register full of half-records is worse
+ * than a smaller one, because the half-records are the ones that get followed
+ * into the code. The caller gets the fix list instead.
+ */
+
+/**
+ * The set a write is validated against: what is on disk, plus whatever the caller
+ * already loaded, minus the file this write replaces (it is being rewritten, not
+ * duplicated).
+ *
+ * Deduplicated by FILE, never by id — two files carrying the same id is exactly
+ * the corruption the validator has to be able to see, and a caller that passes the
+ * records it just loaded must not turn every record into a duplicate of itself.
+ */
+function validationSet(dir, probe, read) {
+  const byFile = new Map();
+  for (const r of [...loadRegister(dir).records, ...(read || [])]) {
+    const key = String(r.__file || "");
+    if (key && key === String(probe.__file)) continue;
+    byFile.set(key || `#${byFile.size}`, r);
+  }
+  return [probe, ...byFile.values()];
+}
+
+export function addDecision(root, { record, body, config, planApproved, read }) {
+  ensureHome(root);
+  const dir = decisionsDir(root, config || {});
+  const data = { ...record };
+  data.status = defaultStatus(data);
+  if (!data.id) data.id = `ADR-${String(nextNumber(dir)).padStart(4, "0")}`;
+  if (!data.decided) data.decided = new Date().toISOString().slice(0, 10);
+  const probe = { ...data, body: body ?? data.body, __file: fileNameFor(data.id, data.title) };
+  const problems = validateRegister(validationSet(dir, probe, read), { planApproved: planApproved === true, exists: (p) => existsIn(root, p) });
+  // Only this record's own faults may refuse it. The register's existing
+  // records are passed in so collisions (duplicate ids, overlapping scopes,
+  // one-sided supersession) are caught — but a neighbour's formatting is not
+  // this write's problem, and refusing on it would make a register unwritable.
+  const blocking = problems.filter((p) => p.severity === "error" && (p.id === data.id || p.file === probe.__file || !p.id));
+  if (blocking.length) return { ok: false, problems: blocking, file: undefined };
+  const written = writeRecord(dir, data, body ?? data.body);
+  if (!written.created) return { ok: false, problems: [{ severity: "error", field: "id", message: `${written.file} already exists — a decision is superseded, never rewritten` }], file: written.file };
+  const refreshed = loadRegister(dir);
+  writeIndex(dir, refreshed.records);
+  return { ok: true, file: written.file, id: data.id, problems: problems.filter((p) => p.severity === "notice") };
+}
+
+/**
+ * Replace a decision. The old record keeps its history and gains
+ * `superseded_by`; the new one names it in `supersedes`. Both halves are written
+ * together, because a one-way link leaves two records looking current — which is
+ * exactly how an agent ends up following a decision that was reversed.
+ */
+export function supersedeDecision(root, { by, id, record, body, config, planApproved, read }) {
+  const dir = decisionsDir(root, config || {});
+  const loaded = loadRegister(dir).records;
+  const older = loaded.find((r) => String(r.id) === String(id));
+  if (!older) return { ok: false, problems: [{ severity: "error", field: "id", message: `${id} is not in the register` }] };
+  // The id is decided BEFORE validation: the bidirectional check asks what the
+  // old record will say about the new one, and that cannot be answered after the
+  // new record has already been written. Validating the pair as it will exist is
+  // the only order in which a legitimate supersession can be written at all.
+  const newId = String(record.id || `ADR-${String(nextNumber(dir)).padStart(4, "0")}`);
+  // The register this function already opened is the authority for what exists —
+  // a caller that forgot to pass `read` (or passed a stale one) must not make a
+  // legitimate supersession look like a link to nothing.
+  const known = [...new Map([...loaded, ...(read || [])].map((r) => [String(r.id), r])).values()].map((r) =>
+    String(r.id) === String(id) ? { ...r, status: "superseded", superseded_by: newId } : r,
+  );
+  const created = addDecision(root, {
+    record: { ...record, id: newId, supersedes: [String(id)] },
+    body,
+    config,
+    planApproved,
+    read: known,
+  });
+  if (!created.ok) return created;
+  const back = updateRecord(dir, String(id), { status: "superseded", superseded_by: created.id });
+  if (!back.created) return { ok: false, problems: [{ severity: "error", field: "supersedes", message: `could not mark ${id} superseded (${back.reason})` }] };
+  const refreshed = loadRegister(dir);
+  writeIndex(dir, refreshed.records);
+  return { ok: true, file: back.file, id: created.id, superseded: String(id), by: String(by || "agent") };
+}
+
+/** Re-generate the index from the records (the records are the source). */
+export function refreshIndex(root, config) {
+  const dir = decisionsDir(root, config || {});
+  const { records } = loadRegister(dir);
+  return { file: writeIndex(dir, records), count: records.length };
+}

package/lib/decisions/glob.d.mts

@@ -0,0 +1,2 @@
+export function globToRe(glob: string): RegExp;
+export function matchesAny(path: string, globs: string[] | undefined): boolean;

package/lib/decisions/glob.mjs

@@ -0,0 +1,57 @@
+/**
+ * The tiny glob matcher a decision uses to name the code it governs.
+ *
+ * `applies_to: [lib/gates/**, test/test-gates.mjs]` is the field that turns a
+ * paragraph into something that can be *routed*: it is how ASF knows, at the
+ * moment a file is about to be edited, which decisions apply to that file.
+ *
+ * Written here rather than pulled from a package for the same reason as the
+ * front-matter parser — a gate's behaviour must not vary with what the measured
+ * project has installed. Supported: `*` (not across `/`), `**` (across `/`),
+ * `?`, and a trailing `/` meaning "everything under here".
+ */
+
+function escapeRe(s) {
+  return s.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Emit the pattern for a run of stars starting at `i`, and report how much of the
+ * glob it consumed. Pulled out of `globToRe` because the three star cases are where
+ * all the nesting lived; with them here, the compiler is a flat switch.
+ */
+function starPattern(g, i) {
+  if (g[i + 1] !== "*") return { pattern: "[^/]*", skip: 1 };
+  // `**/` may match zero directories, so swallow the separator with it.
+  if (g[i + 2] === "/") return { pattern: "(?:.*/)?", skip: 3 };
+  return { pattern: ".*", skip: 2 };
+}
+
+/** Compile one glob into an anchored RegExp. */
+export function globToRe(glob) {
+  let g = String(glob || "");
+  if (!g) return /^$/;
+  if (g.endsWith("/")) g += "**";
+  let out = "";
+  for (let i = 0; i < g.length; i++) {
+    const c = g[i];
+    if (c === "*") {
+      const star = starPattern(g, i);
+      out += star.pattern;
+      i += star.skip - 1;
+      continue;
+    }
+    if (c === "?") {
+      out += "[^/]";
+      continue;
+    }
+    out += escapeRe(c);
+  }
+  return new RegExp(`^${out}$`);
+}
+
+/** Does a project-relative path fall under any of these globs? */
+export function matchesAny(path, globs) {
+  const p = String(path || "").replace(/^\.\//, "").replace(/^\/+/, "");
+  return (globs || []).some((g) => globToRe(g).test(p));
+}

package/lib/decisions/parse.d.mts

@@ -0,0 +1,11 @@
+export interface ParsedFrontMatter {
+  data: Record<string, unknown>;
+  body: string;
+  errors: string[];
+}
+export function parseFrontMatter(text: string): ParsedFrontMatter;
+export function serializeFrontMatter(
+  data: Record<string, unknown>,
+  body: string,
+  order?: string[],
+): string;

package/lib/decisions/parse.mjs

@@ -0,0 +1,138 @@
+/**
+ * The front matter of a decision record.
+ *
+ * A documented subset of YAML — flat `key: value`, inline arrays, block lists,
+ * comments — parsed by ASF rather than by a YAML dependency. The reason is the
+ * same one that makes the health gate write its own eslint config and run
+ * `--no-config-lookup`: what a gate reads must not depend on a library the
+ * measured project happens to have installed.
+ *
+ * The second reason is the user. These files are edited by hand, verbatim, in
+ * whatever editor is open. So the parser is strict about what it understands and
+ * *loud* about what it does not: unsupported syntax is returned as an error,
+ * never skipped, because a record silently parsed as empty reads as "no
+ * decisions" — and an empty register is a gate that passes for the wrong reason.
+ */
+
+const FM_DELIM = /^---\s*$/;
+
+function stripComment(value) {
+  let out = "";
+  let quote = null;
+  for (let i = 0; i < value.length; i++) {
+    const c = value[i];
+    if (quote) {
+      out += c;
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      quote = c;
+      out += c;
+      continue;
+    }
+    if (c === "#" && (i === 0 || /\s/.test(value[i - 1]))) break;
+    out += c;
+  }
+  return out.trim();
+}
+
+function unquote(v) {
+  const t = v.trim();
+  if (t.length > 1 && (t[0] === '"' || t[0] === "'") && t.endsWith(t[0])) return t.slice(1, -1);
+  return t;
+}
+
+function parseScalar(v) {
+  const t = unquote(v);
+  if (t === "") return "";
+  if (t === "true") return true;
+  if (t === "false") return false;
+  if (/^-?\d+(\.\d+)?$/.test(t)) return Number(t);
+  return t;
+}
+
+function parseInlineArray(v) {
+  const inner = v.trim().replace(/^\[/, "").replace(/\]$/, "").trim();
+  if (!inner) return [];
+  return inner.split(",").map((s) => parseScalar(s.trim())).filter((x) => x !== "");
+}
+
+/** Is this line something the subset cannot express (nested map, tabs, anchors)? */
+function unsupported(line) {
+  if (/\t/.test(line)) return "tabs are not valid indentation";
+  if (/^\s+\S+:\s*$/.test(line) || /^\s+\S+:\s+\S/.test(line)) return "nested maps are not supported";
+  if (/^\s*[-*]\s+\S+:/.test(line)) return "maps inside lists are not supported";
+  if (/^\s*[&*]|:\s*[|>]\s*$/.test(line)) return "anchors and block scalars are not supported";
+  return undefined;
+}
+
+/**
+ * Apply one front-matter line to `data`. Returns an error string when the line is
+ * not something this parser understands, `null` when it was consumed happily, and
+ * the new current key when a `key:` opened a list. Kept separate from the loop so
+ * the four shapes a line can have (blank/comment, unsupported, bullet, pair) read
+ * as four branches instead of one nested pile.
+ */
+function applyLine(line, data, key) {
+  const bad = unsupported(line);
+  if (bad) return { error: bad };
+  const bullet = /^\s*-\s+(.*)$/.exec(line);
+  if (bullet && key) {
+    if (!Array.isArray(data[key])) data[key] = [];
+    data[key].push(parseScalar(stripComment(bullet[1])));
+    return {};
+  }
+  const kv = /^([A-Za-z_][\w.-]*):\s*(.*)$/.exec(line);
+  if (!kv) return { error: `not a "key: value" pair — "${line.trim()}"`, key: null };
+  const next = kv[1];
+  const value = stripComment(kv[2]);
+  if (value === "") data[next] = [];
+  else if (value.startsWith("[")) data[next] = parseInlineArray(value);
+  else data[next] = parseScalar(value);
+  return { key: next };
+}
+
+/**
+ * Parse `---` front matter out of a markdown document.
+ * @returns {{data: Record<string, unknown>, body: string, errors: string[]}}
+ */
+export function parseFrontMatter(text) {
+  const lines = String(text ?? "").replace(/\r\n/g, "\n").split("\n");
+  if (lines[0].trim() !== "---") {
+    return { data: {}, body: lines.join("\n"), errors: ["missing front matter (the file must start with ---)"] };
+  }
+  const end = lines.findIndex((l, i) => i > 0 && FM_DELIM.test(l));
+  if (end < 0) {
+    return { data: {}, body: "", errors: ["front matter is never closed (no second ---)"] };
+  }
+  const data = {};
+  const errors = [];
+  let key = null;
+  for (let i = 1; i < end; i++) {
+    const line = lines[i].replace(/\s+$/, "");
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const out = applyLine(line, data, key);
+    if (out.error) {
+      errors.push(`front matter line ${i + 1}: ${out.error}`);
+      key = out.key === null ? null : key;
+      continue;
+    }
+    if (out.key) key = out.key;
+  }
+  return { data, body: lines.slice(end + 1).join("\n"), errors };
+}
+
+function emitValue(v) {
+  if (Array.isArray(v)) return `[${v.map(emitValue).join(", ")}]`;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  const s = String(v ?? "");
+  return /[:#\[\]{}"']|^\s|\s$/.test(s) ? `"${s.replace(/"/g, '\\"')}"` : s;
+}
+
+/** Serialize a record back to front matter + body. Keys keep the declared order. */
+export function serializeFrontMatter(data, body, order = []) {
+  const keys = order.length ? [...order.filter((k) => k in data), ...Object.keys(data).filter((k) => !order.includes(k))] : Object.keys(data);
+  const fm = keys.map((k) => `${k}: ${emitValue(data[k])}`);
+  return `---\n${fm.join("\n")}\n---\n\n${String(body ?? "").trim()}\n`;
+}

package/lib/decisions/schema.d.mts

@@ -0,0 +1,36 @@
+export interface DecisionRecord extends Record<string, unknown> {
+  id?: string;
+  status?: string;
+  title?: string;
+  decision?: string;
+  decided?: string | number;
+  applies_to?: string[];
+  body?: string;
+  __file?: string;
+}
+
+export interface DecisionProblem {
+  severity: "error" | "notice";
+  file?: string;
+  id?: string;
+  field?: string;
+  message: string;
+}
+
+export interface ValidateContext {
+  byId?: Map<string, DecisionRecord>;
+  planApproved?: boolean;
+  now?: number;
+  exists?: (p: string) => boolean;
+}
+
+export const STATUSES: string[];
+export const ORIGINS: string[];
+export const FIELD_ORDER: string[];
+export const REQUIRED_FIELDS: string[];
+export const BODY_SECTIONS: string[];
+export const ACCEPTANCE_FIELDS: string[];
+
+export function sectionsOf(body: string | undefined): Record<string, string>;
+export function validateRecord(rec: DecisionRecord, ctx?: ValidateContext): DecisionProblem[];
+export function validateRegister(records: DecisionRecord[], ctx?: ValidateContext): DecisionProblem[];