pi-aia-asf 0.17.7 → 0.17.9

package/CHANGELOG.md

@@ -7,6 +7,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+`gate.tracked.claim` / `.resolve` / `.park` / `.wait` in `.asf/config.json` add patterns
+(string or array) to the built-in matcher set. They **widen, never replace**: a project
+that typos `claim` would otherwise stop tracking its own claims, and a floor that a
+stray character in a config file can switch off is not a floor. Non-string entries are
+ignored rather than compiled in.
+
+`lib/gates/tracked.mjs` now says plainly what it is — **a tripwire over tool names and
+the agent's own prose, not an authority over ticket state**. It cannot see a tracker's
+database and its vocabulary is a small illustrative set; a tool named `grabWorkItem` is
+invisible until the project says so. The asymmetry is deliberate: a miss costs a run
+that settles early, a false alarm costs one steer.
+
+### Fixed — a matcher that matched everything
+
+`matchersFromConfig()` built the wait matcher as `alternatives + "|" + extras` even when
+`extras` was empty, leaving a trailing `|`. An empty alternative matches the empty
+string, so **every progress message in every project would have been read as a
+confessed wait** — a gate that trips on everything is as useless as one that trips on
+nothing, and much harder to notice. Every union is now guarded by a length check, and a
+test pins that no matcher matches `""`, `"anything at all"`, or a config entry of
+`""`/`undefined`/`null`. Caught by the suite that checks a benign progress message is
+not a wait, and mutation-verified: restoring the dangling `|` fails two checks.
+
 ## [0.17.7] - 2026-11-09
 
 ### Fixed — "waiting" is now illegal as a disposition

package/lib/code-health/index.mjs

@@ -35,7 +35,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 +50,37 @@ 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 */
-      }
+    writeFileSync(join(root, BASELINE_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);
+  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/extension/commands/inspect.ts

@@ -40,14 +40,19 @@ export async function cmdStatus(): Promise<string> {
 /** Code Health Gate: objective measurement at function / module / architecture level. */
 export async function cmdHealth(args: string[]): Promise<string> {
   const { runHealth } = await import("../../code-health/index.mjs");
+  const { recordHealthVerdict, recordLine } = await import("../health-record.ts");
   const res = await runHealth(runRoot(), args.slice(1));
+  // The command records what it measured. Before this, only the asf_health TOOL
+  // recorded: a human could run /asf health, read HEALTHY, and leave the
+  // completion gate's health gap open with no trace that anything was measured.
+  const rec = recordHealthVerdict(res, { by: "command" });
   const tail =
     res.exitCode === 1
       ? "\n\n✗ GATE FAILED — resolve the violations before delivery."
       : res.config?.gate?.mode === "warn" && !res.healthy
         ? "\n\n(warn mode: violations reported, gate not blocking)"
         : "";
-  return res.text + tail;
+  return `${res.text}${tail}\n\n${recordLine(rec)}`;
 }
 
 /** "What enforces anything around browser testing?" — answered from the registry. */

package/lib/extension/commands/verify.ts

@@ -55,8 +55,12 @@ async function traceabilitySection(): Promise<string[]> {
 /** Gate 8 — objective convolution measurement, on the real working tree. */
 async function healthSection(): Promise<string[]> {
   const { runHealth } = await import("../../code-health/index.mjs");
+  const { recordHealthVerdict, recordLine } = await import("../health-record.ts");
   const health = await runHealth(runRoot(), []);
-  const lines = ["\nCODE HEALTH (Gate 8 — large work):", health.text];
+  // Same rule as the tool and the slash command: a measurement that is produced
+  // is a measurement that is recorded.
+  const rec = recordHealthVerdict(health, { by: "verify" });
+  const lines = ["\nCODE HEALTH (Gate 8 — large work):", health.text, recordLine(rec)];
   if (health.exitCode === 1) {
     lines.push("\n  ✗ GATE NOT PASSED — resolve code-health violations before delivery.");
   } else if (!health.healthy && health.config?.gate?.mode === "warn") {

package/lib/extension/handlers/tool-call.ts

@@ -17,7 +17,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { classifyToolCall, activationDecision } from "../../activation.mjs";
 import { evaluateBlockers, BLOCKERS, failSafeBlock } from "../../gates/blockers.mjs";
 import { deriveSuiteRun } from "../../gates/suite-runs.mjs";
-import { noteTrackedCall } from "../../gates/tracked.mjs";
+import { noteTrackedCall, matchersFromConfig } from "../../gates/tracked.mjs";
 import { readProjectConfig } from "../../gates/config.mjs";
 import { projectName, runRoot } from "../paths.ts";
 import { loadState, saveState } from "../state.ts";
@@ -112,8 +112,8 @@ function observeWebTouch(input: Input): void {
  * about it instead. Claim / resolve / park are read off the tool's name; a
  * narrated wait is read off the text the agent wrote for the reviewer.
  */
-function observeTrackedWork(toolName: string, input: Input): void {
-  const kind = noteTrackedCall(runtime.tracked, { toolName, input });
+function observeTrackedWork(toolName: string, input: Input, config: Record<string, unknown>): void {
+  const kind = noteTrackedCall(runtime.tracked, { toolName, input, matchers: matchersFromConfig(config) });
   if (!kind) return;
   appendEvidence({ kind: "tracked", action: kind, tool: toolName, item: String(input.ticket_id || input.ticketId || input.id || "") || null });
   if (kind === "wait") {
@@ -223,6 +223,9 @@ export function registerToolCallHandler(pi: ExtensionAPI): void {
       const ev = event as Event;
       const toolName = String(ev.toolName || "");
       const input = ev.input || {};
+      // Read once, hand it to whoever needs it: the gate below and the tracked-work
+      // matcher both ask, and a second read is a second answer to the same question.
+      const config = readProjectConfig(runRoot());
 
       // An observer failure here must not block the work, so it is fenced.
       try {
@@ -232,9 +235,8 @@ export function registerToolCallHandler(pi: ExtensionAPI): void {
       }
       observeSuiteAttempt(input, ev);
       observeWebTouch(input);
-      observeTrackedWork(toolName, input);
+      observeTrackedWork(toolName, input, config);
 
-      const config = readProjectConfig(runRoot());
       const res = evaluateBlockers(toolName, input, {
         ctx: {
           suiteRuns,

package/lib/extension/health-record.ts

@@ -0,0 +1,46 @@
+/**
+ * Recording a health verdict — one definition, three callers.
+ *
+ * The completion gate asks for a recorded health verdict. It used to be that
+ * only the `asf_health` tool recorded one, while `/asf health` and `/asf verify`
+ * printed the same measurement and left no trace: a human could run the command,
+ * see HEALTHY, and the gate would stay open with nothing to show for it. Either
+ * a measurement is evidence or it is not — so every path that produces the
+ * verdict records it, and `by:` says who produced it.
+ *
+ * The counting rules and the wording are in `lib/code-health/measure.mjs`
+ * (pure, tested without a harness); this file only supplies the ledger, the
+ * evidence trail and the run's scale.
+ */
+
+import { ledger } from "./gate-state.ts";
+import { appendEvidence } from "./evidence.ts";
+import { currentScale } from "./run.ts";
+import { healthRunEntry, measuredMetrics, skippedMetrics } from "../code-health/measure.mjs";
+import type { HealthVerdictSource, HealthRecord } from "../code-health/measure.d.mts";
+
+export type { HealthVerdictSource, HealthRecord } from "../code-health/measure.d.mts";
+export { measuredMetrics, measureSummary, recordLine } from "../code-health/measure.mjs";
+
+const LEVELS = ["small", "standard", "major"];
+
+/**
+ * Append the verdict to the ledger and the evidence trail.
+ *
+ * `level` falls back to the run's scale, so a bare `/asf health` still records
+ * at a level the gate can judge.
+ */
+export function recordHealthVerdict(res: HealthVerdictSource | null | undefined, opts: { by: string; level?: string }): HealthRecord {
+  const level = LEVELS.includes(String(opts?.level)) ? String(opts.level) : currentScale();
+  const entry = healthRunEntry(res, level);
+  const appended = ledger.append(entry);
+  appendEvidence({ ...entry, by: opts.by });
+  return {
+    verdict: entry.verdict,
+    scanned: measuredMetrics(res as { ran?: number }),
+    skipped: skippedMetrics(res),
+    level,
+    recorded: !!appended.ok,
+    error: appended.ok ? "" : String(appended.error),
+  };
+}

package/lib/extension/tools/health.ts

@@ -12,15 +12,17 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
-import { ledger } from "../gate-state.ts";
-import { appendEvidence } from "../evidence.ts";
 import { currentScale } from "../run.ts";
+import { recordHealthVerdict, recordLine } from "../health-record.ts";
 
 interface HealthResult {
   text: string;
   healthy: boolean;
   exitCode: number;
   rows?: unknown[];
+  /** Metrics actually measured (pass+fail). Skipped and error rows are NOT in it. */
+  ran?: number;
+  skipped?: number;
 }
 
 async function runHealthGate(scope: string): Promise<HealthResult> {
@@ -33,20 +35,18 @@ async function runHealthGate(scope: string): Promise<HealthResult> {
   return (await runHealth(runRoot(), args)) as HealthResult;
 }
 
-/** A recorded verdict is the point: measuring without recording clears nothing. */
+/**
+ * A recorded verdict is the point: measuring without recording clears nothing.
+ * The counting rules and the wording live in health-record.ts so the tool, the
+ * slash command and `/asf verify` cannot drift into disagreeing with each other.
+ */
 async function measureAndRecord(levelIn: string, scopeIn: string) {
   const res = await runHealthGate(scopeIn);
-  const verdict = res.exitCode === 1 ? "fail" : res.healthy ? "pass" : "warn";
-  const scanned = Array.isArray(res.rows) ? res.rows.length : 0;
   const level: string = ["small", "standard", "major"].includes(levelIn) ? levelIn : currentScale();
-  const appended = ledger.append({ kind: "health-run", level, verdict, scanned });
-  appendEvidence({ kind: "health-run", level, verdict, scanned, by: "tool" });
-  const recorded = appended.ok
-    ? "recorded as evidence; the completion gate's health gap is now closed."
-    : `NOT recorded (${appended.error})`;
+  const rec = recordHealthVerdict(res, { by: "tool", level });
   return {
-    text: `${res.text}\n\nverdict: ${verdict} (${scanned} metric(s) measured, level ${level}) — ${recorded}`,
-    details: { verdict, scanned, level, recorded: appended.ok, by: "tool", error: "" },
+    text: `${res.text}\n\n${recordLine(rec)}`,
+    details: { verdict: rec.verdict, scanned: rec.scanned, level: rec.level, recorded: rec.recorded, by: "tool", error: rec.error },
   };
 }
 

package/lib/gates/tracked.d.mts

@@ -16,11 +16,21 @@ export interface TrackedState {
 
 export declare const DISPOSITIONS: string[];
 
+export interface TrackedMatchers {
+  claim: RegExp;
+  resolve: RegExp;
+  park: RegExp;
+  wait: RegExp;
+}
+
+/** Built-in matchers, widened (never replaced) by `gate.tracked.*` in the project config. */
+export function matchersFromConfig(config?: Record<string, unknown>): TrackedMatchers;
+
 export function createTracked(): TrackedState;
 
 export function noteTrackedCall(
   tracked: TrackedState,
-  call: { toolName?: string; input?: Record<string, unknown> },
+  call: { toolName?: string; input?: Record<string, unknown>; matchers?: TrackedMatchers },
 ): "claim" | "resolve" | "park" | "wait" | null;
 
 export function danglingGaps(tracked: TrackedState | undefined): string[];

package/lib/gates/tracked.mjs

@@ -17,6 +17,13 @@
  * So the illegal state is named, and the legal answers are exactly three. They
  * are all actions, and the agent can take every one of them — which is what
  * makes this gap steerable rather than the 2026-11-07 kind that loops forever.
+ *
+ * What this is: a **tripwire over tool names and the agent's own prose**, not an
+ * authority over ticket state. It cannot see a tracker's database, and its
+ * vocabulary is a small illustrative set, widened per project through
+ * `gate.tracked.*`. A tool named `grabWorkItem` is invisible to it until someone
+ * says so. That is acceptable because the cost of a miss is a run that settles
+ * early; the cost of a false alarm is one steer.
  */
 
 /** The only three things an agent may do with work it cannot finish right now. */
@@ -57,6 +64,44 @@ const WAITING_ALTERNATIVES = [
 ];
 const WAITING_RE = new RegExp(WAITING_ALTERNATIVES.join("|"), "i");
 
+/**
+ * The matchers as one value, so a project can widen them.
+ *
+ * `gate.tracked.claim` / `.resolve` / `.park` / `.wait` in the project config each
+ * add patterns to the built-in set (a string, or an array of strings). They widen,
+ * never replace: a project that forgets `claim` would stop tracking its own claims,
+ * and a gate that can be switched off by a typo in a config file is not a floor.
+ */
+export function matchersFromConfig(config = {}) {
+  const extra = (key) => {
+    const v = config[`gate.tracked.${key}`];
+    const list = Array.isArray(v) ? v : typeof v === "string" ? [v] : [];
+    return list.filter((x) => typeof x === "string" && x.trim()).map((x) => x.trim());
+  };
+  const build = (base, key) => {
+    const add = extra(key);
+    return add.length ? new RegExp(`${base.source}|${add.map(escapeRe).join("|")}`, "i") : base;
+  };
+  // The empty alternative is the trap here: `a|b|` matches the empty string, so a
+  // dangling `|` turns "does this text confess a wait" into "yes, always" — a gate
+  // that trips on everything is as useless as one that trips on nothing, and it is
+  // far harder to notice. Every union below is guarded by `add.length`.
+  const waitAdd = extra("wait");
+  const waitSource = waitAdd.length
+    ? `${WAITING_ALTERNATIVES.join("|")}|${waitAdd.map(escapeRe).join("|")}`
+    : WAITING_ALTERNATIVES.join("|");
+  return {
+    claim: build(CLAIM_RE, "claim"),
+    resolve: build(RESOLVE_RE, "resolve"),
+    park: build(PARK_RE, "park"),
+    wait: new RegExp(waitSource, "i"),
+  };
+}
+
+function escapeRe(source) {
+  return source.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 /** Identify the item a call is about, so one ticket is one entry. */
 function itemId(input) {
   if (!input || typeof input !== "object") return null;
@@ -99,22 +144,23 @@ function closeItem(tracked, id) {
  * Returns a short label for the evidence trail (`claim` / `resolve` / `park` /
  * `wait` / null). Never throws on odd input: this is an observer on the hot path.
  */
-export function noteTrackedCall(tracked, { toolName = "", input = {} } = {}) {
+export function noteTrackedCall(tracked, { toolName = "", input = {}, matchers } = {}) {
+  const m = matchers || matchersFromConfig();
   if (!tracked || !toolName) return null;
   const id = itemId(input) || `tool:${toolName}`;
-  if (PARK_RE.test(toolName)) {
+  if (m.park.test(toolName)) {
     closeItem(tracked, id);
     return "park";
   }
-  if (RESOLVE_RE.test(toolName)) {
+  if (m.resolve.test(toolName)) {
     closeItem(tracked, id);
     return "resolve";
   }
-  if (CLAIM_RE.test(toolName)) {
+  if (m.claim.test(toolName)) {
     openItem(tracked, id, toolName);
     return "claim";
   }
-  if (NARRATE_RE.test(toolName) && WAITING_RE.test(textOf(input))) {
+  if (NARRATE_RE.test(toolName) && m.wait.test(textOf(input))) {
     // Narrating a wait does not make it legal; it makes it visible to the gate.
     openItem(tracked, id, toolName);
     if (!tracked.waits.includes(id)) tracked.waits.push(id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.17.7",
+  "version": "0.17.9",
   "description": "Ai Applied Agentic Software Factory — codifies the full software development flow: intake, research, spec capture, adversarial analysis, planning with approval gates, test-first implementation, and release. Requires pi-vigilant, pi-smart-web-search, pi-smart-fetch, and pi-aia-browser.",
   "keywords": [
     "pi-package",

package/skills/aia-asf/references/06e-code-health.md

@@ -67,6 +67,20 @@ whose tool is not installed are skipped (or fail the gate when
 `/asf verify` (large work) runs the gate as **Gate 8** after the M1
 traceability matrix. Small work shows the report but never blocks.
 
+All three paths — the `/asf health` command, `/asf verify`, and the
+**`asf_health` tool** — record the verdict as evidence, so any of them closes the
+completion gate's health gap. An autonomous run uses the tool: a slash command is
+something the agent cannot type, and a gap it cannot close is a bug, not a gate.
+
+**What `scanned` counts.** It is the number of metrics that actually ran
+(pass/fail), never the number of metrics planned. Skipped metrics (tool not
+installed, level off) and disabled ones (no persistence in the project) are not
+in it, and neither are rows that errored. So `scanned: 0` means the gate examined
+nothing — which the ledger prints as *"examined nothing, not a pass"* rather than
+letting a green-looking line summarise a measurement of nothing at all. If every
+metric is skipped, installing the toolchain is what closes the gap properly;
+re-running the gate does not.
+
 ## 3. Configuration
 
 Optional `.asf-code-health.json` at the project root. Merged over the defaults

package/skills/aia-asf/references/06f-stability.md

@@ -140,6 +140,18 @@ Two things this is **not**: it is not a ban on saying "blocked" honestly (say it
 report, with the disposition you took); and it is not a reason to resolve work that is
 not done — a false `resolved` is the worse failure. Park it.
 
+It is a **tripwire over tool names and the agent's own prose, not an authority over
+ticket state** — it cannot see a tracker's database, and its vocabulary is a small
+illustrative set. A project widens it (never narrows it) in `.asf/config.json`:
+
+```json
+{ "gate.tracked.claim": "grabWorkItem", "gate.tracked.wait": ["still stuck on"] }
+```
+
+Keys: `gate.tracked.claim`, `.resolve`, `.park`, `.wait`. A miss costs a run that
+settles early; a false alarm costs one steer. That asymmetry is why the defaults lean
+toward catching.
+
 ## Anti-patterns
 
 - ❌ Unbounded retries on non-idempotent writes