pi-aia-asf 0.17.8 → 0.17.9

package/CHANGELOG.md

@@ -7,6 +7,44 @@ 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

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.17.8",
+  "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