pi-aia-asf 0.12.2 → 0.13.1

package/CHANGELOG.md

@@ -7,11 +7,151 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.12.2] - 2026-10-14
+## [0.13.1] - 2026-10-16
+
+### Fixed
+
+- **A measurement without a target no longer reads as a verdict.** 0.13.0
+  shipped the measurement contract but left the last clause of the requirement
+  unimplemented: *where no defensible default exists the output is
+  `no-default: needs a declared target`, never a silent pass*. Now:
+  - **`perf.target` is the one parameter that ships no default.** A latency or
+    throughput target is a product decision; a number ASF invented would be a
+    fabricated specification. With nobody having declared one, the parameter
+    resolves to `value: null, origin: "no-default"` and the verdict text is the
+    literal `no-default: needs a declared target`.
+  - **`target` is required on latency and throughput claims.** A claim can carry
+    a complete measurement contract — percentile, load, samples, environment,
+    lab-or-field — and still be judging nothing. That is now reported, with
+    `noDefault` set on the result. A **regression** claim still needs no target:
+    it compares two arms rather than a threshold.
+  - **The parameter guard keeps its teeth.** The flag that exempts a parameter
+    from a band is the same flag that *forbids* it from shipping a general
+    default, so a fabricated number cannot smuggle itself in as "no default
+    needed". Adding `perf.target` also tripped the existing guard for a missing
+    `meaning` field — the guard working as intended on its first real test.
+  - `SKILL.md`/06k/06b state the rule where the contract is stated, and the
+    config screen shows `no-default` as a first-class origin.
+
+## [0.13.0] - 2026-10-16
 
 ### Added
 
-- (describe changes for 0.12.2)
+- **The enforcement layer (`lib/gates/`, wired into `/asf`).** Until now every
+  ASF gate was a sentence in a markdown file that the agent was asked to
+  remember. These are code that runs, each with the two fixtures that make it
+  trustworthy.
+  - **`defaults.mjs` — three-tier configuration.** Every tunable ships with a
+    researched general default (with its source), a documented adaptation band,
+    and project calibration allowed **only inside the band**. A value outside
+    the band is explicit user configuration and is labelled `override`, never
+    silently obeyed. Statistical-validity constants (`bench.significance`,
+    `valid.interleavedComparison`, `valid.rawSamplesRetained`,
+    `valid.scannedZeroIsPass`) are **non-adaptive** — a project may not
+    calibrate its way out of a valid comparison, only make it more patient.
+  - **`ledger.mjs` — the evidence ledger.** Entries are derived from observed
+    tool traffic (suite runs, health verdicts, browser verification). There is
+    **no model-callable way to append an entry**, malformed entries are rejected
+    and recorded, and `scanned: 0` is reported as *examined nothing*, never as a
+    pass.
+  - **`authority.mjs` — gate authority is earned and revocable.**
+    `probation → active` requires clean runs **plus at least one caught fixture
+    case** (a gate that never fires looks exactly like a gate that works). An
+    active gate is demoted automatically when its false-positive rate or
+    blocks-per-run exceeds budget. Every transition is append-only, needs a
+    reason, and appears in the delivery report. A bypass request is recorded as
+    friction, not as evidence that the gate is wrong.
+  - **`blockers.mjs` — objective `tool_call` blockers.** Secrets in a tracked
+    file, a test subset run without stating its impact area, push without a
+    green full suite, destructive git on a dirty tree. Each declares its own
+    `failSafe: "block" | "allow"` — a crashing secret check blocks, a crashing
+    convenience check does not stop the loop. Every blocker has an autonomous
+    exit the agent can take itself; nothing here opens a UI prompt for approval.
+  - **`settle.mjs` — the completion gate**, bounded at `MAX_CONTINUATIONS = 2`.
+    Past the cap the gaps are **reported**, not blocked forever.
+  - **`measurement.mjs` — the measurement contract and the comparison.** A bare
+    numeric claim (`p95 < 2s`) is detected and reported as incomplete rather
+    than accepted. Regression verdicts use significance **plus effect size**
+    with retained raw samples — a naive ±15% threshold missed a real +10%
+    regression in 40/40 local trials where this caught 40/40. On a busy machine
+    the verdict is `skipped: machine busy`: no verdict, not a pass.
+  - **`acceptance.mjs`, `report.mjs`** — perf/security acceptance validation and
+    the delivery report, which is **assembled from the ledger and gate verdicts,
+    not written**, and shows each DoD item's enforcement class (H / M / S) so a
+    self-attested item cannot read as a verified one.
+  - **`config.mjs` + `declarations.mjs`** — the config screen (unknown parameters
+    refused, non-adaptive ones reported as ignored, out-of-band values clamped
+    and labelled) and the obligation declarations, which carry **no consumer
+    vocabulary** and are validated against the tests that enforce them.
+- **New commands:** `/asf rules [H|M|S|area]`, `/asf config`, `/asf gates`,
+  `/asf report [--checklist]`.
+- **`obligations.d/aia-asf.json`** — ASF's 17 standing obligations declared for
+  the loop guard, `source: "aia-asf"`, carried verbatim by the guard, which
+  never interprets it.
+- **`references/06k-performance.md`** — the measurement contract, CI-cheap vs
+  scheduled placement, load scenarios (including the arrival-model trap),
+  escalation, and the ASVS performance/resource overlap.
+- **5 new suites, 292 checks** (`test-gates`, `test-performance-gates`,
+  `test-config-screen`, `test-delivery-report`, `test-security-mapping`) on a
+  shared `test/gate-harness.mjs` that requires **a fire fixture and a near-miss
+  fixture for every gate**, and meta-asserts that gate count equals covered
+  gate count so a gate cannot be added and quietly left untested.
+
+### Changed
+
+- **06h is now pinned to real ASVS 5.0 numbering** (`v5.0.0_release`, V1–V17).
+  The previous chapter table had been written from memory and was wrong. ASF
+  does not maintain a second security checklist alongside ASVS, and one
+  abuse-case load run now satisfies both the security and performance DoD.
+- **06b gains Rules 21–23** (measurement contract, performance placement, gate
+  autonomy/negative-controls/budget) and four new DoD lines; the rule count in
+  `SKILL.md` is now asserted to *agree* with the heading count rather than to
+  equal a hardcoded number, which is what let the drift through.
+- **02-research.md gains T1/T2/T3 evidence classes.** Every shipped default
+  cites its class and source; a T3 value is never presented as a rule, and "a
+  default that cannot explain itself is a guess with better formatting".
+- **06d: a delegated verification prompt must carry its measurement contract**,
+  and a returned number without one is a claim, not a result.
+
+### Fixed
+
+- **`obligations.d/` was not in `package.json` `files`** — found by clean-room
+  verification, not by the suite. An installed ASF would have shipped the
+  enforcement code with no declarations for it to load, so `/asf rules` would
+  have reported an empty and perfectly green list.
+- **`assertSignalsExist` reported false drift in every consumer project.** It
+  ran against the installed package, which ships no `test/`, producing one
+  bogus failure per obligation. It now says once that the check was skipped
+  because this is not the declaring repo — and still fails hard where a `test/`
+  directory exists and a named file or assertion is genuinely missing.
+
+## [0.12.2] - 2026-10-14
+
+### Fixed
+
+- **`npm run check` now checks.** It was `tsc --noCheck …` with a compiler that
+  was not even resolvable here — `node_modules` is a hand-built symlink tree
+  pointing at the global pi install, which `npm install` cannot reconcile, so
+  the declared devDependency was never installed. Three layers of nothing:
+  no compiler, no checking, and — even when a compiler was found — the host API
+  resolved to `any`.
+  - `scripts/typecheck.sh` + `tsconfig.typecheck.json`: strict typecheck of
+    `index.ts` against the pinned host API, installed into gitignored `.tools/`
+    and mapped explicitly. Prints the compiler **and** host-types versions it
+    ran, so the gate cannot silently run something other than what is declared.
+  - **`lib/code-health/index.d.mts`** — the Code Health gate stays plain ESM on
+    purpose, but at the call site its entire surface was `any`. This is the
+    boundary: a field added to `runHealth`'s return that is not declared here is
+    now a type error rather than a silent pass. Verified by mutation —
+    `h.noSuchFieldOnPurpose` → `TS2339`.
+  - **devDependencies were stale**: pinned at pi `0.83.0` while the extension
+    runs against pi `1.2.0`. Now `1.2.0`, with `typebox` at the `1.3.27` the
+    host ships.
+
+### Changed
+
+- **Releases are gated.** `scripts/release.sh` runs the typecheck and the full
+  suite before anything is versioned, tagged or published.
 
 ## [0.12.1] - 2026-10-14
 

package/index.ts

@@ -15,7 +15,20 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
+import { cpus, loadavg } from "node:os";
+import { execFileSync } from "node:child_process";
+
+import { createLedger, deriveSuiteRun, renderLedger } from "./lib/gates/ledger.mjs";
+import { evaluateBlockers, BLOCKERS } from "./lib/gates/blockers.mjs";
+import { createAuthority, renderAuthority } from "./lib/gates/authority.mjs";
+import { decideSettlement, renderCompletionGate, MAX_CONTINUATIONS } from "./lib/gates/settle.mjs";
+import { cli as configCli, screenModel, assertParametersAreConsumed, readProjectConfig } from "./lib/gates/config.mjs";
+import { loadDeclarations, renderRules, assertSignalsExist } from "./lib/gates/declarations.mjs";
+import { renderDeliveryReport, renderChecklist } from "./lib/gates/report.mjs";
+import { PARAMS } from "./lib/gates/defaults.mjs";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -236,7 +249,122 @@ function dependencySummary(): string {
 
 // ─── Extension registration ────────────────────────────────────────────────
 
+// ─── Enforcement session state ─────────────────────────────────────────────
+//
+// What the extension *observed*, not what the agent asserted. The ledger is
+// written from tool traffic and there is no model-callable way to append to it:
+// if the agent could append an entry it would append a convenient one.
+
+const ledger = createLedger();
+const authority = createAuthority();
+
+interface GateStat {
+  verdicts: number;
+  fired: number;
+  confirmedFalse: number;
+  blocks: number;
+}
+const gateStats: Record<string, GateStat> = {};
+
+/** Set when register() runs; the ledger writes entries through it. */
+let piRef: ExtensionAPI | null = null;
+
+/** suite-run attempts awaiting their result, keyed by toolCallId. */
+const pendingSuiteRuns = new Map<string, Record<string, unknown>>();
+/** Completed suite runs — the fact the push gate checks for. */
+const suiteRuns: Array<{ scope: string; exitCode: number; command: string; durationMs: number; testCount: number | string }> = [];
+/** Memoised dirty-tree answer, refreshed at most once per tool call. */
+let dirtyCache: { at: number; dirty: boolean } | null = null;
+
+/** Bounded: beyond the cap the gate reports the gap instead of nagging forever. */
+let continuationsRequested = 0;
+let lastSettleDecision: { missing: string[]; exhausted?: boolean } | null = null;
+let webTouched = false;
+let impactStated = false;
+
+/** Where this extension is installed — the declaration file ships beside it. */
+function extensionDir(): string {
+  try {
+    return dirname(fileURLToPath(import.meta.url));
+  } catch {
+    return process.cwd();
+  }
+}
+
+/**
+ * Project characteristics the adaptation band may calibrate within. Anything
+ * not measured is simply absent, so the general default is used rather than a
+ * guess — a default that cannot explain itself is a guess with better formatting.
+ */
+function collectMeasurements(): Record<string, unknown> {
+  const m: Record<string, unknown> = {};
+  const last = [...ledger.entries].reverse().find((e: any) => e.kind === "suite-run" && e.scope === "full");
+  if (last && typeof last.durationMs === "number") m.suiteRuntimeMs = last.durationMs;
+  const cores = cpus()?.length;
+  if (cores) m.cores = cores;
+  const la = loadavg()?.[0];
+  if (typeof la === "number" && cores) m.machineQuiet = la <= cores;
+  return m;
+}
+
+function recordVerdict(gate: string, v: { fired?: boolean; scanned?: number }) {
+  const s = (gateStats[gate] ||= { verdicts: 0, fired: 0, confirmedFalse: 0, blocks: 0 });
+  s.verdicts++;
+  if (v.fired) s.fired++;
+  // scanned: 0 is recorded as examined-nothing. It is never a pass, here or in
+  // the report, and the ledger keeps the number so the claim can be audited.
+  if (v.scanned === 0) s.confirmedFalse++;
+}
+
+function appendEvidence(entry: Record<string, unknown>) {
+  const res = ledger.append(entry);
+  if (res.ok) {
+    try {
+      // Durable and excluded from model context: evidence costs no prompt budget.
+      (piRef as unknown as { appendEntry?: (t: string, d?: unknown) => void } | null)?.appendEntry?.("asf-evidence", res.entry);
+    } catch {
+      /* the in-memory ledger is the source of truth for this session */
+    }
+  } else {
+    try {
+      (piRef as unknown as { appendEntry?: (t: string, d?: unknown) => void } | null)?.appendEntry?.("asf-evidence-rejected", { problem: res.error });
+    } catch {
+      /* reported where possible */
+    }
+  }
+  return res;
+}
+
+/** Is the working tree dirty? Fail-open: an unknown state must not block. */
+function gitDirty(): boolean {
+  const now = Date.now();
+  if (dirtyCache && now - dirtyCache.at < 5000) return dirtyCache.dirty;
+  let dirty = false;
+  try {
+    const out = execFileSync("git", ["status", "--porcelain"], { cwd: process.cwd(), encoding: "utf-8", timeout: 5000 });
+    dirty = String(out).trim().length > 0;
+  } catch {
+    // Not a repo, or git unavailable: we cannot claim the tree is dirty, and a
+    // convenience gate must not block on its own blindness.
+    dirty = false;
+  }
+  dirtyCache = { at: now, dirty };
+  return dirty;
+}
+
+function numberConfig(config: Record<string, unknown>, key: string, fallback: number): number {
+  const v = config[key];
+  return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+
+/** Small work is held to the reduced DoD — the scale rule is the trigger here. */
+function currentScale(): "small" | "standard" | "major" {
+  return lastScaleWasSmall ? "small" : "standard";
+}
+let lastScaleWasSmall = false;
+
 export default function register(pi: ExtensionAPI): void {
+  piRef = pi;
   // Startup check: warn once per session if deps are missing (unless disabled)
   // The extension loads at startup; log to console so it surfaces in logs.
 
@@ -292,6 +420,7 @@ export default function register(pi: ExtensionAPI): void {
       case "refactor":
         return await setPhase(ctx, "intake", "refactor", "large");
       case "small":
+        lastScaleWasSmall = true;
         return await setPhase(ctx, "implementation", undefined, "small");
       case "status": {
         const project = projectName();
@@ -411,6 +540,78 @@ export default function register(pi: ExtensionAPI): void {
               : "";
         return res.text + tail;
       }
+      case "rules": {
+        // The registry question with an answer: "what enforces anything around
+        // browser testing?" used to require reading every reference file.
+        const here = process.cwd();
+        const pkgDir = extensionDir();
+        const { obligations, problems } = loadDeclarations(pkgDir);
+        if (problems.length) {
+          return `ASF declaration has problems:\n- ${problems.join("\n- ")}`;
+        }
+        const filter = args[1];
+        const cls = ["H", "M", "S"].includes((filter || "").toUpperCase()) ? filter.toUpperCase() : undefined;
+        const area = cls ? undefined : filter;
+        const drift = assertSignalsExist(pkgDir, obligations);
+        const text = renderRules(obligations, { area, cls });
+        return text + (drift.length ? `\n\nDeclaration/test drift:\n- ${drift.join("\n- ")}` : "");
+      }
+      case "config": {
+        // One screen for every parameter. The screen is a convenience, not the
+        // only door: --get/--set/--explain/--check work headless with the same
+        // validation, so a typo is refused here rather than discovered later by
+        // a gate silently not running.
+        const a = args.map((s) => s.trim()).filter(Boolean);
+        const flag = (a[1] || "--get").toLowerCase();
+        const projectDir = process.cwd();
+        const measurements = collectMeasurements();
+        if (flag === "--screen" || flag === "screen") {
+          const rows = screenModel({ projectDir, measurements });
+          return rows
+            .map(
+              (r) =>
+                `${r.id} = ${r.currentValue}  [${r.origin}]  band ${r.band}${r.nonAdaptive ? "  (NON-ADAPTIVE)" : ""}\n    ${r.meaning ?? r.description.split("\n")[0]}`,
+            )
+            .join("\n");
+        }
+        if (flag === "--check") {
+          const problems = assertParametersAreConsumed(readProjectConfig(projectDir), {
+            knownGates: [...new Set(Object.values(PARAMS).map((p: { gate: string }) => p.gate))],
+          });
+          return problems.length ? `configuration problems:\n- ${problems.join("\n- ")}` : "configuration is consistent";
+        }
+        const action = flag === "--set" ? "set" : flag === "--unset" ? "unset" : flag === "--explain" ? "explain" : "get";
+        let key: string | undefined = a[2];
+        let value: string | undefined;
+        if (action === "set" && key && key.includes("=")) {
+          const [k, ...rest] = key.split("=");
+          key = k;
+          value = rest.join("=");
+        }
+        return configCli({ action, key, value, projectDir, measurements });
+      }
+      case "report": {
+        // The delivery report is ASSEMBLED, not written (P35). Everything below
+        // comes from what the harness observed this session; a gap stays visible
+        // as a gap rather than becoming a tick.
+        const checklist = args[1] === "--checklist";
+        return checklist
+          ? renderChecklist()
+          : renderDeliveryReport({
+              ledger,
+              authority,
+              gateStats,
+              completion: lastSettleDecision || { missing: [] },
+            });
+      }
+      case "gates": {
+        // What the enforcement layer decided, and what it charged.
+        return [
+          renderLedger(ledger),
+          renderAuthority(authority, gateStats),
+          renderCompletionGate(lastSettleDecision || { missing: [] }),
+        ].join("\n\n");
+      }
       case "abort":
         return await setPhase(ctx, "none");
       default:
@@ -424,6 +625,10 @@ export default function register(pi: ExtensionAPI): void {
           "  /asf status     — show current phase\n" +
           "  /asf health     — run the code health gate (function/module/architecture)\n" +
           "  /asf verify     — run the definition-of-done QA gate\n" +
+          "  /asf rules [H|M|S|area] — list declared obligations and what enforces them\n" +
+          "  /asf report [--checklist] — the delivery report, assembled from observed evidence\n" +
+          "  /asf config [--get [k] | --set k=v | --unset k | --explain k | --check | --screen] — every ASF parameter, with its origin\n" +
+          "  /asf gates      — gate verdicts, authority state and friction for this session\n" +
           "  /asf abort      — end the current session\n\n" +
           dependencySummary()
         );
@@ -473,4 +678,178 @@ export default function register(pi: ExtensionAPI): void {
       ctx.ui.notify(await runApprove(ctx), "info");
     },
   });
+
+  // ── tool_call: observe, then block only what is objectively blockable ────
+  //
+  // Two jobs, in this order. First **observe**: turn what the extension watched
+  // happen into evidence, because "I ran the full suite" and "I did not run the
+  // full suite" must not be two sentences with no observable difference. Then
+  // **block**: only rules decidable from the tool input plus session state, each
+  // with an autonomous exit the agent can take itself.
+  //
+  // No gate here asks a human anything. `block: true, reason` returns the reason
+  // to the model, which is agent-facing feedback; nothing calls a UI prompt to
+  // seek approval. A blocker whose only exit is a human decision is misdesigned
+  // and belongs in the report, not in the path.
+  pi.on("tool_call", (event) => {
+    try {
+      const toolName = String((event as { toolName?: unknown }).toolName || "");
+      const input = (event as { input?: Record<string, unknown> }).input || {};
+
+      // Observe: a full test-suite run becomes evidence only because we saw it.
+      const command = typeof input.command === "string" ? input.command : undefined;
+      if (command) {
+        const started = Date.now();
+        const derived = deriveSuiteRun(command, 0, 0, "");
+        if (derived) {
+          // Exit code and duration are filled in by the tool_result handler;
+          // recording the attempt here keeps the ledger chronological.
+          (derived as Record<string, unknown>)._startedAt = started;
+          pendingSuiteRuns.set((event as { toolCallId?: string }).toolCallId || String(started), derived);
+        }
+        if (/\basf-approve\b/.test(command)) {
+          // A bypass is recorded as friction, never as evidence the gate is
+          // wrong: otherwise the exploit is to bypass a gate until it demotes.
+          appendEvidence({
+            kind: "gate-block",
+            gate: "asf-approve",
+            rule: "bypass-requested",
+            reason: "asf-approve invoked — recorded as friction; a bypass request is not evidence that a gate is wrong",
+            bypassed: true,
+          });
+        }
+      }
+
+      // Observe: a write to a web surface means browser verification is owed.
+      const touched = typeof input.path === "string" ? input.path : typeof input.file_path === "string" ? input.file_path : "";
+      if (touched && /\.(tsx|jsx|html|vue|svelte|css)$/i.test(touched)) webTouched = true;
+
+      const config = readProjectConfig(process.cwd());
+      const enabled: Record<string, boolean> = {};
+      for (const b of BLOCKERS) {
+        const k = b.switch.replace(/^gate\./, "");
+        if (config[`gate.block.${k}`] === false || config[b.switch] === false) enabled[b.switch] = false;
+      }
+
+      const res = evaluateBlockers(toolName, input, {
+        suiteRuns,
+        dirty: () => gitDirty(),
+        impactStated,
+        trackedPaths: undefined,
+      }, { enabled });
+
+      for (const v of res.verdicts || []) {
+        recordVerdict(v.gate, v);
+        appendEvidence({ kind: "gate-verdict", gate: v.gate, fired: !!v.fired, scanned: typeof v.scanned === "number" ? v.scanned : 0 });
+      }
+
+      if (res.block) {
+        const gate = res.rule || "unknown";
+        const s = (gateStats[gate] ||= { verdicts: 0, fired: 0, confirmedFalse: 0, blocks: 0 });
+        s.blocks++;
+        appendEvidence({ kind: "gate-block", gate, rule: res.rule || gate, reason: String(res.reason || "").slice(0, 400) });
+        // Automatic demotion check (P45): a gate that blocks repeatedly in one
+        // run is interrupting the loop rather than guarding it.
+        const budgets = {
+          falsePositiveBudget: numberConfig(config, "gate.falsePositiveBudget", 0.05),
+          blocksPerRunBudget: numberConfig(config, "gate.blocksPerRunBudget", 3),
+        };
+        const check = authority.checkBudget(gate, {
+          blocksThisRun: s.blocks,
+          verdicts: gateStats[gate]?.verdicts || 0,
+          falsePositives: gateStats[gate]?.confirmedFalse || 0,
+          budgets,
+        });
+        if (check.demote && check.report) {
+          try {
+            (pi as unknown as { appendEntry?: (t: string, d?: unknown) => void }).appendEntry?.("asf-gate-transition", {
+              gate,
+              to: "demoted",
+              reason: check.reasons.join("; "),
+            });
+          } catch {
+            /* reported where possible */
+          }
+        }
+        return { block: true, reason: res.reason };
+      }
+      return undefined;
+    } catch {
+      // An observer must never break the thing it observes. The fail-safe for
+      // the secret rule lives inside evaluateBlockers, where it is explicit.
+      return undefined;
+    }
+  });
+
+  // ── tool_result: complete the evidence for an observed suite run ────────
+  //
+  // The exit code and duration are what make a suite run a fact rather than an
+  // attempt, and they come from what the tool returned — not from what the
+  // agent says it returned. Test counts are recorded only where a known runner's
+  // output can actually be read; otherwise they stay 'unknown', never 0.
+  pi.on("tool_result", (event) => {
+    try {
+      const id = String((event as { toolCallId?: unknown }).toolCallId || "");
+      const pending = pendingSuiteRuns.get(id);
+      if (!pending) return undefined;
+      pendingSuiteRuns.delete(id);
+
+      const content = (event as { content?: unknown }).content;
+      const output = typeof content === "string" ? content : JSON.stringify(content ?? "");
+      const isError = !!(event as { isError?: boolean }).isError;
+      const startedAt = typeof pending._startedAt === "number" ? pending._startedAt : Date.now();
+      const derived = deriveSuiteRun(
+        String(pending.command || ""),
+        isError ? 1 : 0,
+        Date.now() - startedAt,
+        output,
+      );
+      if (derived) {
+        delete (derived as Record<string, unknown>)._startedAt;
+        suiteRuns.push({
+          scope: derived.scope,
+          exitCode: derived.exitCode,
+          command: derived.command,
+          durationMs: derived.durationMs,
+          testCount: derived.testCount,
+        });
+        appendEvidence({ ...derived });
+      }
+      return undefined;
+    } catch {
+      return undefined;
+    }
+  });
+
+  // ── agent_before_settle: no "done" without evidence ───────────────────
+  //
+  // Registered here and not on `agent_settled` because pi documents the latter
+  // as final and notification-only, while `agent_before_settle` is the final
+  // actionable boundary. And nothing here awaits a resumed run: the loop guard
+  // documents a production hang caused by exactly that.
+  pi.on("agent_before_settle", () => {
+    try {
+      const decision = decideSettlement(ledger, {
+        scale: currentScale(),
+        webTouched,
+        continuationsSoFar: continuationsRequested,
+      });
+      lastSettleDecision = decision;
+      appendEvidence({
+        kind: "gate-verdict",
+        gate: "completion",
+        fired: decision.missing.length > 0,
+        scanned: ledger.entries.length,
+      });
+      if (decision.block && continuationsRequested < MAX_CONTINUATIONS) {
+        continuationsRequested++;
+        // One bounded continuation naming exactly what is missing. No UI prompt:
+        // this sends the agent back to work, it does not ask anyone anything.
+        return { continue: true };
+      }
+      return undefined;
+    } catch {
+      return undefined;
+    }
+  });
 }

package/lib/gates/acceptance.d.mts

@@ -0,0 +1,19 @@
+export interface Acceptance {
+  [field: string]: unknown;
+}
+export const REQUIRED_PERF: string[];
+export const REQUIRED_SECURITY: string[];
+export function validatePerfAcceptance(
+  acceptance: Acceptance | null,
+  now?: Date,
+): { ok: boolean; invalid: string[]; acceptance: Acceptance | null };
+export function validateSecurityAcceptance(
+  acceptance: Acceptance | null,
+  now?: Date,
+): { ok: boolean; invalid: string[]; expired?: boolean; acceptance: Acceptance | null };
+export function securityGate(input: {
+  findings?: { id?: string; title?: string; severity?: string }[];
+  acceptances?: Acceptance[];
+  followUps?: { finding?: string; ticket?: string }[];
+}): { ok: boolean; open: string[] };
+export function renderAcceptance(kind: "perf" | "security", acceptance: Acceptance): string;