pi-aia-asf 0.17.8 → 0.17.10

package/CHANGELOG.md

@@ -7,6 +7,105 @@ 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
+
+`asf_health` recorded `scanned` as `rows.length`, and `rows` contains every metric
+the gate **planned** — including the ones that never ran because a tool was not
+installed. Three things followed, all reported from the same observation:
+
+- the ledger's `scanned 0` rule ("examined nothing, not a pass") was unreachable
+  while any metric was planned, so a run that measured nothing was recorded as a
+  nine-metric audit;
+- the tool's own summary line contradicted the report printed directly above it —
+  `NOT healthy — 8 metric(s) skipped` followed by `9 metric(s) measured`;
+- the honest number already existed and was thrown away: `verdict()` returns
+  `ran`, counting pass+fail and deliberately **excluding** error rows, but
+  `runHealth()` never returned it.
+
+`runHealth()` now returns `ran` and `skipped`, and the recorded count comes from
+them. Counting `status !== "skipped"` was the tempting fix and is wrong: it counts
+errored rows as measured, which puts the report, the ledger and the summary line
+back out of agreement — the exact disagreement being fixed. A metric that does not
+apply (no persistence in the project) is neither ran nor skipped.
+
+### Changed — every path that produces a health verdict records it
+
+`/asf health` and the Gate 8 section of `/asf verify` printed the measurement and
+left no trace, so a human could run the command, read HEALTHY, and leave the
+completion gate's health gap open. Recording was the `asf_health` tool's private
+privilege; it is now shared, with `by:` saying who produced the verdict
+(`tool` / `command` / `verify`). The counting rules and the summary wording moved
+to `lib/code-health/measure.mjs` — pure, dependency-free, and tested without a
+harness — so the three callers cannot drift into contradicting each other again.
+
+A verdict over zero metrics says so out loud: *"Nothing was actually measured — a
+verdict over zero metrics is not a pass, and installing the missing tools is what
+closes this properly."*
+
+
 ## [0.17.8] - 2026-11-09
 
 ### Added — the tracked-work vocabulary is the project's to widen

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) {
@@ -35,7 +37,7 @@ export async function runHealth(projectRoot, args = [], deps = {}) {
   const config = await loadConfig(projectRoot, deps.readFile);
   if (!config.enabled) {
     const text = "Code Health Gate: disabled (enabled: false).";
-    return { text, json: { enabled: false }, exitCode: 0, healthy: true, rows: [], config };
+    return { text, json: { enabled: false }, exitCode: 0, healthy: true, rows: [], ran: 0, skipped: 0, config };
   }
 
   const files = listSourceFiles(projectRoot, config.ignore);
@@ -50,29 +52,40 @@ export async function runHealth(projectRoot, args = [], deps = {}) {
   const gateBlocks = config.gate.mode === "block" && config.gate.scope !== "off";
   const exitCode = gateBlocks && !v.healthy ? 1 : 0;
 
-  let text = formatReport(rows, config);
+  const text = applyBaselineFlags({ text: formatReport(rows, config), rows, root: projectRoot, flags });
 
+  const json = flags.json ? jsonReport(rows, config) : null;
+  // `ran` and `skipped` are verdict()'s own counts, and they leave here because
+  // they are the ONLY honest answer to "how much was actually measured" — see
+  // lib/code-health/measure.mjs. `rows.length` counts metrics PLANNED.
+  return { text, json, exitCode, healthy: v.healthy, rows, ran: v.ran, skipped: v.skipped, config };
+}
+
+/**
+ * `--update-baseline` and `--diff`, factored out of `runHealth` so the gate's
+ * main path stays readable and the metric accounting stays in one place.
+ */
+function applyBaselineFlags({ text, rows, root, flags }) {
   if (flags.updateBaseline) {
     const payload = baselinePayload(rows);
-    writeFileSync(join(projectRoot, BASELINE_FILE), JSON.stringify(payload, null, 2) + "\n", "utf-8");
-    text += `\n\nBaseline updated: ${BASELINE_FILE}`;
-  } else if (flags.diff) {
-    const baselinePath = join(projectRoot, BASELINE_FILE);
-    let baselineRows = [];
-    if (existsSync(baselinePath)) {
-      try {
-        const base = JSON.parse(readFileSync(baselinePath, "utf-8"));
-        baselineRows = Object.entries(base.metrics || {}).map(([key, m]) => ({ key, value: m.value, status: m.status }));
-      } catch {
-        /* unreadable baseline → no diff */
-      }
+    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;
+  // 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 {
+      const base = JSON.parse(readFileSync(baselinePath, "utf-8"));
+      baselineRows = Object.entries(base.metrics || {}).map(([key, m]) => ({ key, value: m.value, status: m.status }));
+    } catch {
+      /* unreadable baseline → no diff */
     }
-    const changes = diffRows(rows, baselineRows);
-    text += "\n\n" + formatDiff(changes);
   }
-
-  const json = flags.json ? jsonReport(rows, config) : null;
-  return { text, json, exitCode, healthy: v.healthy, rows, config };
+  return `${text}\n\n${formatDiff(diffRows(rows, baselineRows))}`;
 }
 
-export { BASELINE_FILE };

package/lib/code-health/measure.d.mts

@@ -0,0 +1,25 @@
+export interface HealthVerdictSource {
+  healthy?: boolean;
+  exitCode?: number;
+  ran?: number;
+  skipped?: number;
+}
+
+export interface HealthRecord {
+  verdict: string;
+  scanned: number;
+  skipped: number;
+  level: string;
+  recorded: boolean;
+  error: string;
+}
+
+export function measuredMetrics(res: HealthVerdictSource | null | undefined): number;
+export function skippedMetrics(res: HealthVerdictSource | null | undefined): number;
+export function verdictOf(res: HealthVerdictSource | null | undefined): string;
+export function measureSummary(res: HealthVerdictSource | null | undefined, level: string): string;
+export function healthRunEntry(
+  res: HealthVerdictSource | null | undefined,
+  level: string,
+): { kind: "health-run"; level: string; verdict: string; scanned: number };
+export function recordLine(rec: HealthRecord): string;

package/lib/code-health/measure.mjs

@@ -0,0 +1,76 @@
+/**
+ * What a health verdict actually measured — the pure half.
+ *
+ * `scanned` is the number three readers must agree on: the ledger's
+ * "examined nothing, not a pass" rule, the report's own `HEALTHY — N metric(s)
+ * checked, M skipped` line, and the summary line the agent reads after the
+ * report. It used to be `rows.length`, and `rows` counts every metric PLANNED —
+ * including the ones that never ran because a tool was missing. So a project
+ * where eight of nine metrics could not run was recorded as a nine-metric
+ * audit, the ledger's zero-rule became unreachable, and the tool's summary
+ * contradicted the report printed directly above it.
+ *
+ * The honest number already existed: `verdict()` returns `ran`, which counts
+ * pass+fail and deliberately EXCLUDES error rows. Counting `status !==
+ * "skipped"` instead would count errors as measured and put the three readers
+ * back out of agreement — which is the bug this file exists to prevent.
+ *
+ * Pure and dependency-free on purpose: the recording glue lives beside the
+ * ledger, and this is what the tests can pin without a harness.
+ */
+
+/**
+ * Metrics actually measured. Skipped, disabled and error rows are NOT counted.
+ *
+ * Both spellings are accepted because the two objects that travel through this
+ * file use different names for the same fact: the gate's verdict says `ran`,
+ * the recorded ledger entry says `scanned`. A summary that read only one of them
+ * would print "0 metric(s) measured" over an eight-metric audit — which is the
+ * exact contradiction this module exists to prevent, so it is read from
+ * whichever field the caller has.
+ */
+export function measuredMetrics(res) {
+  if (Number.isFinite(res?.ran)) return Number(res.ran);
+  if (Number.isFinite(res?.scanned)) return Number(res.scanned);
+  return 0;
+}
+
+/** Metrics that were planned but never ran. */
+export function skippedMetrics(res) {
+  return Number.isFinite(res?.skipped) ? Number(res.skipped) : 0;
+}
+
+/** pass/fail/warn — the same reading the exit code and the report use. */
+export function verdictOf(res) {
+  if (res?.exitCode === 1) return "fail";
+  return res?.healthy ? "pass" : "warn";
+}
+
+/** The one wording, so no caller can invent a contradictory one. */
+export function measureSummary(res, level) {
+  const skipped = skippedMetrics(res);
+  return `${measuredMetrics(res)} metric(s) measured${skipped ? `, ${skipped} skipped` : ""}, level ${level}`;
+}
+
+/** The ledger entry: `scanned` is what ran, never what was planned. */
+export function healthRunEntry(res, level) {
+  return { kind: "health-run", level, verdict: verdictOf(res), scanned: measuredMetrics(res) };
+}
+
+/**
+ * What the reader is told after a recording.
+ *
+ * A verdict over zero metrics is spelled out as not-a-pass: the failure mode
+ * this guards against is an agent (or a human) reading a green-looking line that
+ * summarised a measurement of nothing at all.
+ */
+export function recordLine(rec) {
+  const recorded = rec.recorded
+    ? "recorded as evidence; the completion gate's health gap is now closed."
+    : `NOT recorded (${rec.error})`;
+  const nothing = rec.scanned === 0
+    ? " Nothing was actually measured — a verdict over zero metrics is not a pass, " +
+      "and installing the missing tools is what closes this properly."
+    : "";
+  return `verdict: ${rec.verdict} (${measureSummary(rec, rec.level)}) — ${recorded}${nothing}`;
+}

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;