pi-aia-asf 0.17.10 → 0.17.12

package/CHANGELOG.md

@@ -7,13 +7,86 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.17.10] - 2026-11-10
-
-### Added
+## [0.17.12] - 2026-11-10
+
+### Fixed — the health gate measured the wrong project
+
+`runRoot()` is the git root of the session's cwd. That is right for where run state
+lives and wrong for what to measure, and a session launched from a home directory that
+is itself a git repo (common: `pi` started from $HOME with checkouts underneath) had
+every health gate measure the parent. It did: `asf_health` reported 363 model findings
+from an unrelated project checked out under $HOME, and eslint, madge and jscpd each
+timed out at 120s scanning a tree nobody was working in — a verdict of NOT healthy on a
+repository that is, in fact, healthy.
+
+A gate that measures the wrong directory is worse than no gate: it blocks on findings
+in code the run must not touch, or waves through the one project that is actually
+unhealthy. `measureRoot()` now answers from what the run already knows — the git root of
+the most recently touched file — and is used by the three paths that measure
+(`asf_health`, `/asf health`, `/asf verify` Gate 8). It is deliberately **not** used to
+locate state: a root that moved mid-run would orphan the run's own ledger, so
+`runRoot()` still follows the session for that.
+
+A touched path outside the workspace (a scratch dir, an unrelated checkout) does not
+move the measurement either — the session root is the safe answer. `test/test-measure-root.mjs`
+pins both on throwaway repos rather than this machine's $HOME, and both guards are
+mutation-caught.
+
+## [0.17.11] - 2026-11-10
+
+### Added — the coverage invariant is checkable from the installed package
+
+`test/test-evidence-kinds.mjs` asserts that every evidence kind a gate requires has a
+producer, but `test/` is not shipped — so a broken or half-updated install reproduced
+the one bug that suite exists to catch, and the session inside it had no way to find
+out. It could only be steered, at the same gap, forever. Three callers now ask the one
+question, against one definition in `lib/gates/evidence-coverage.mjs`:
+
+- `asf_evidence_check {kind?}` — the agent's own check. An unproducible **required**
+  kind is reported as a broken install rather than as work to keep attempting, because
+  no amount of effort records evidence nothing in the package can write.
+- `scripts/verify-published.mjs` — a fourth release section, run against the copy npm
+  just installed. A tarball missing a producer now fails the release instead of
+  shipping the loop to every user while the repository stayed green. A section that
+  throws is a failed check, never a silent pass.
+- `test/test-evidence-kinds.mjs` — asserts the answer, and asserts the shipped module
+  derives the same required set an independent derivation in the test does.
+
+### Fixed — the coverage checker could not say "no"
+
+Writing the negatives proved it: five mutations of the new module initially passed the
+suite, because every assertion asked only whether a producer was **found**. A checker
+whose regex matches everything, or that counts the ledger as the producer of its own
+kinds, is invisible to a suite like that — and `requiredOrphans: []` was invisible too.
+It is now tested against fixture packages where the answer is known to be no: a kind
+nothing writes, and a kind only the ledger mentions. The tool's two paths no session
+hits on a good day (broken install, check that threw) were untested for the same reason
+and are now driven directly.
+
+### Changed — the code-health config lives under `.asf/`
+
+`.asf/code-health.json` is now read first, with the root `.asf-code-health.json` still
+honoured so a project configured before the move does not wake up on defaults after an
+upgrade. This was the last ASF-authored file still written to the project root, and
+"everything ASF authors lives under `.asf/`" is one decision with one table of names:
+the path now comes from `FILES` in `lib/home.mjs` rather than a literal in the reader,
+which is how a file ends up written in one place and read from another.
+
+### Fixed — the shipped CHANGELOG said nothing
+
+The 0.17.10 section was the release script's untouched placeholder, twice over: an
+empty `### Added` above a second heading for the same version. `CHANGELOG.md` ships in
+the tarball, so that is what a user reads. `test/test-antipatterns.mjs` now asserts the
+shipped version has a section, that it is not the placeholder, that it has real prose,
+and that no version is listed twice — making "Vague commits or CHANGELOG placeholders"
+an enforced anti-pattern rather than a listed one.
+
+Also: `test/harness.mjs` passes a jiti loader to suites, since a `.mjs` suite cannot
+import ASF's own `.ts` modules and each suite spinning up its own loader is how two
+different loaders start disagreeing; `lib/code-health/tools.d.mts` added (an imported
+`.mjs` used from `.ts` needs a declaration or typecheck fails).
 
-- (describe changes for 0.17.10)
-
-## [0.18.0] - 2026-11-10
+## [0.17.10] - 2026-11-10
 
 ### Added — the browser evidence the completion gate demands can now be produced
 

package/index.ts

@@ -19,6 +19,7 @@ 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 { registerEvidenceCheckTool } from "./lib/extension/tools/evidence-check.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";
@@ -32,6 +33,7 @@ export default function register(pi: ExtensionAPI): void {
   registerHealthTool(pi);
   registerDecisionsTool(pi);
   registerBrowserTools(pi);
+  registerEvidenceCheckTool(pi);
   registerCommands(pi);
   registerToolCallHandler(pi);
   registerToolResultHandler(pi);

package/lib/code-health/config.mjs

@@ -203,15 +203,20 @@ export function normalizeConfig(raw) {
 }
 
 /**
- * Load the project config: read `.asf-code-health.json` if present, normalize.
- * `readFile` is injectable for tests.
+ * Load the project config: `.asf/code-health.json`, falling back to the root
+ * `.asf-code-health.json` that older releases wrote.
+ *
+ * The path comes from the home table rather than a literal here, because "everything
+ * ASF authors lives under `.asf/`" is one decision with one table of names — a second
+ * place that hardcodes a location is how a file ends up written in one place and read
+ * from another. `readFile` is injectable for tests.
  */
 export async function loadConfig(projectRoot, readFile = null) {
   const fs = readFile || (await import("node:fs/promises")).readFile;
+  const { readPath } = await import("../home.mjs");
   let raw = null;
   try {
-    const text = await fs(`${projectRoot}/.asf-code-health.json`, "utf-8");
-    raw = JSON.parse(text);
+    raw = JSON.parse(await fs(readPath(projectRoot, "healthConfig"), "utf-8"));
   } catch {
     raw = null; // no file, or unreadable/invalid → defaults
   }

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

@@ -0,0 +1,21 @@
+/** Where ASF is installed — the base for resolving its own bundled toolchain. */
+export const ASF_ROOT: string;
+
+export interface ResolvedTools {
+  eslint?: string;
+  sonarjs?: string;
+  tsParser?: string;
+  jscpd?: string;
+  madge?: string;
+  depcruise?: string;
+  /** Where each tool was found: "asf" | "project" | "path" | undefined when missing. */
+  sources: Record<string, string | undefined>;
+  missing: string[];
+  [key: string]: unknown;
+}
+
+/** Resolve the health toolchain ASF-first: ASF's install, then the project, then PATH. */
+export function resolveTools(projectRoot: string, opts?: { asfRoot?: string }): ResolvedTools;
+
+/** The required tools that could not be found; empty means the gate can measure. */
+export function missingTools(tools: ResolvedTools): string[];

package/lib/extension/commands/inspect.ts

@@ -7,7 +7,7 @@ import { projectName, runRoot } from "../paths.ts";
 import { loadState } from "../state.ts";
 import { ledger, authority, gateStats } from "../gate-state.ts";
 import { runtime } from "../runtime.ts";
-import { cardFor, collectMeasurements, extensionDir } from "../run.ts";
+import { cardFor, collectMeasurements, extensionDir, measureRoot } from "../run.ts";
 import { renderLedger } from "../../gates/ledger.mjs";
 import { renderAuthority } from "../../gates/authority.mjs";
 import { renderCompletionGate } from "../../gates/settle.mjs";
@@ -41,7 +41,7 @@ export async function cmdStatus(): Promise<string> {
 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));
+  const res = await runHealth(await measureRoot(), 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.

package/lib/extension/commands/verify.ts

@@ -6,6 +6,7 @@
  */
 
 import { projectName, runRoot } from "../paths.ts";
+import { measureRoot } from "../run.ts";
 import { loadState } from "../state.ts";
 import { loadProjectSpecs, validateTrace } from "../specs.ts";
 import { QA_CHECKLIST, type SpecItem } from "../types.ts";
@@ -56,7 +57,7 @@ async function traceabilitySection(): Promise<string[]> {
 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 health = await runHealth(await measureRoot(), []);
   // 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" });

package/lib/extension/run.ts

@@ -4,16 +4,16 @@
  */
 
 import { execFileSync } from "node:child_process";
+import { runRoot, projectName } from "./paths.ts";
 import { fileURLToPath } from "node:url";
 import { dirname } from "node:path";
-import { runRoot } from "./paths.ts";
+import { projectRoot as projectRootOf } from "../project.mjs";
 import { ensureHome } from "../home.mjs";
 import { cpus, loadavg } from "node:os";
 import { renderRunCard, cardSummary, CARD_CEILING_BYTES } from "../run-card.mjs";
 import { ledger, suiteRuns, gateStats } from "./gate-state.ts";
 import { appendEvidence } from "./evidence.ts";
 import { loadState, saveState } from "./state.ts";
-import { projectName } from "./paths.ts";
 import { runtime } from "./runtime.ts";
 import { __resetRefusals } from "../gates/refusals.mjs";
 import { cardIndex, registerAt } from "../decisions/consult.mjs";
@@ -118,6 +118,43 @@ export async function openAutoRun(trigger: string, path: string | null): Promise
   return state;
 }
 
+/**
+ * The project the gates should MEASURE.
+ *
+ * `runRoot()` is the git root of the session's cwd, which is right for where state
+ * lives and wrong for what to measure: a session started in a parent repository
+ * (a home directory that is itself a git repo is the common case) would have every
+ * gate measure that parent. It did — `asf_health` reported 363 model findings from an
+ * unrelated project checked out underneath $HOME, and every measurement tool then
+ * timed out scanning a tree nobody was working in. A gate that measures the wrong
+ * directory is worse than no gate: it blocks on findings in code the run must not
+ * touch, or waves through the one project that is actually unhealthy.
+ *
+ * The run already knows what it changed, so the answer is taken from there: the git
+ * root of the most recently touched file wins. It is deliberately NOT used to locate
+ * state — a root that moved mid-run would orphan the run's own ledger — only to
+ * decide what a measurement looks at.
+ */
+export async function measureRoot(): Promise<string> {
+  const fallback = runRoot();
+  try {
+    const state = await loadState(projectName());
+    const touched = (state?.current?.filesTouched || []) as string[];
+    for (let i = touched.length - 1; i >= 0; i--) {
+      const f = touched[i];
+      if (!f || !f.includes("/")) continue;
+      const root = projectRootOf(dirname(f));
+      // Only a root that CONTAINS the session root counts as a better answer: a
+      // stray touched path outside the workspace must not drag the measurement to
+      // someone's scratch directory.
+      if (root && (root === fallback || root.startsWith(fallback + "/"))) return root;
+    }
+  } catch {
+    /* measurement falls back to the session root; a broken guess is worse than none */
+  }
+  return fallback;
+}
+
 /** Where this extension is installed — the declaration file ships beside it. */
 
 export function extensionDir(): string {

package/lib/extension/tools/evidence-check.ts

@@ -0,0 +1,134 @@
+/**
+ * asf_evidence_check — can this install produce what its gates demand?
+ *
+ * The invariant "every evidence kind a gate requires has a producer" is the difference
+ * between a warranted loop and the unwarranted one of 2026-11-07: a run steered
+ * forever at evidence its own hands cannot record. The repository asserts it in
+ * `test/test-evidence-kinds.mjs`, but `test/` is not shipped, so a session with a
+ * broken or half-updated install had no way to find out — it could only be steered,
+ * and steered, and steered, at a gap that was never closable from inside.
+ *
+ * This is that way. It reads the installed package's own files (never the user's
+ * project) and answers one question, so "the gate is stuck on something impossible"
+ * becomes a checkable fact instead of a guess.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+interface Coverage {
+  kinds: string[];
+  required: string[];
+  producers: Record<string, string[]>;
+  orphans: string[];
+  requiredOrphans: string[];
+  files: number;
+}
+
+/** One details shape for every branch: a union whose branches disagree about which
+ *  fields exist makes the host read `error` as required and reject the tool. */
+export function details() {
+  return {
+    action: "evidence-check",
+    ok: false,
+    error: "",
+    kind: "",
+    required: false,
+    producers: [] as string[],
+    kinds: 0,
+    orphans: [] as string[],
+    requiredOrphans: [] as string[],
+    requiredList: [] as string[],
+  };
+}
+
+async function coverage(): Promise<{ coverage: Coverage; gap: { gap: string; remedy: string } | null; root: string }> {
+  const { ASF_ROOT } = await import("../../code-health/tools.mjs");
+  const { ENTRY_KINDS } = await import("../../gates/ledger.mjs");
+  const { evidenceCoverage, coverageGap } = await import("../../gates/evidence-coverage.mjs");
+  const cov = evidenceCoverage(ASF_ROOT, ENTRY_KINDS) as Coverage;
+  return { coverage: cov, gap: coverageGap(cov) as { gap: string; remedy: string } | null, root: String(ASF_ROOT) };
+}
+
+/** The answer about one kind: who records it, or the honest fact that nobody does. */
+export function reportKind(cov: Coverage, kind: string) {
+  const d = details();
+  d.kind = kind;
+  if (!cov.kinds.includes(kind)) {
+    return {
+      content: [{ type: "text" as const, text: `${kind} is not a ledger kind this install knows (${cov.kinds.join(", ")})` }],
+      details: d,
+    };
+  }
+  const producers = cov.producers[kind] || [];
+  const required = cov.required.includes(kind);
+  const text = producers.length
+    ? `${kind}: produced by ${producers.join(", ")}${required ? " (required by a gate)" : ""}`
+    : `${kind}: NOTHING in the installed package records it${required ? " — and a gate requires it, so no run can close on it" : " (nothing requires it either: dead weight)"}`;
+  return {
+    content: [{ type: "text" as const, text }],
+    details: { ...d, ok: producers.length > 0, producers, required },
+  };
+}
+
+/** The whole picture, said plainly: sound, or broken in a way no effort can fix. */
+export function reportAll(cov: Coverage, gap: { gap: string; remedy: string } | null, root: string) {
+  const d = details();
+  const text = gap
+    ? `ASF install at ${root}: ${gap.gap}\n${gap.remedy}\n\n${cov.kinds.length} kinds over ${cov.files} files; required by gates: ${cov.required.join(", ")}`
+    : `ASF install at ${root} is sound: ${cov.kinds.length} evidence kinds over ${cov.files} files, each with a producer; ${cov.required.length} of them are required by a gate (${cov.required.join(", ")}).`;
+  return {
+    content: [{ type: "text" as const, text }],
+    details: {
+      ...d,
+      ok: !gap,
+      kinds: cov.kinds.length,
+      required: cov.required.length > 0,
+      requiredList: cov.required,
+      orphans: cov.orphans,
+      requiredOrphans: cov.requiredOrphans,
+    },
+  };
+}
+
+/**
+ * A check that could not run is not a check that passed. This is its own function so
+ * the claim is testable: a mutation that made the catch branch report `ok: true` was
+ * invisible while nothing ever drove the failure path.
+ */
+export function reportFailure(error: string) {
+  return {
+    content: [{ type: "text" as const, text: `evidence coverage could not be checked: ${error}` }],
+    details: { ...details(), error },
+  };
+}
+
+export function registerEvidenceCheckTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "asf_evidence_check",
+    label: "ASF Evidence Coverage",
+    description:
+      "Check whether the installed ASF can actually produce every kind of evidence its gates demand. " +
+      "Call this when a run keeps being steered at the same evidence gap and you cannot close it — an " +
+      "unproducible kind is a broken install, not unfinished work, and no amount of effort closes it. " +
+      "Reads ASF's own installed files, never the user's project.",
+    promptSnippet: "Check that every gate-required evidence kind has a producer in this install",
+    parameters: Type.Object({
+      kind: Type.Optional(
+        Type.String({
+          description: "Report only this evidence kind (e.g. 'browser-verify'); omit for the whole picture.",
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId: string, params: { kind?: unknown }) {
+      try {
+        const { coverage: cov, gap, root } = await coverage();
+        const kind = typeof params.kind === "string" ? params.kind.trim() : "";
+        return kind ? reportKind(cov, kind) : reportAll(cov, gap, root);
+      } catch (e) {
+        return reportFailure(String((e as Error)?.message || e));
+      }
+    },
+  });
+}

package/lib/extension/tools/health.ts

@@ -27,12 +27,12 @@ interface HealthResult {
 
 async function runHealthGate(scope: string): Promise<HealthResult> {
   const { runHealth } = await import("../../code-health/index.mjs");
-  const { runRoot } = await import("../paths.ts");
+  const { measureRoot } = await import("../run.ts");
   const args = scope ? [`--scope=${scope}`] : [];
-  // Measure the RUN's project, not process.cwd(): a session started in $HOME
-  // (or any parent) would otherwise measure everything under it — 960 phantom
-  // findings from site-packages, on a repo that is actually healthy.
-  return (await runHealth(runRoot(), args)) as HealthResult;
+  // Measure the project the RUN is about, not process.cwd() and not the session
+  // cwd's git root: a session started in $HOME (which is itself a repo here) would
+  // otherwise measure every checkout underneath it.
+  return (await runHealth(await measureRoot(), args)) as HealthResult;
 }
 
 /**

package/lib/gates/evidence-coverage.d.mts

@@ -0,0 +1,19 @@
+export interface EvidenceCoverage {
+  kinds: string[];
+  required: string[];
+  producers: Record<string, string[]>;
+  orphans: string[];
+  requiredOrphans: string[];
+  files: number;
+}
+
+export interface CoverageGap {
+  gap: string;
+  remedy: string;
+}
+
+/** Does every ledger kind have a producer in the package at `root`? */
+export function evidenceCoverage(root: string, entryKinds: string[]): EvidenceCoverage;
+
+/** The coverage result as a completion gap, or null when the install is sound. */
+export function coverageGap(coverage: EvidenceCoverage): CoverageGap | null;

package/lib/gates/evidence-coverage.mjs

@@ -0,0 +1,124 @@
+/**
+ * Does every piece of evidence a gate demands have something that can produce it?
+ *
+ * Three tickets in a row were one bug wearing different clothes: the health gate
+ * demanded a verdict only a pi slash command could produce; the completion gate
+ * demanded browser verification no registered tool could record; the delivery report
+ * rendered sections whose kinds nothing ever wrote. Each time a run was steered at a
+ * gap its own hands could not close — the unwarranted loop the process rules forbid.
+ *
+ * The invariant is stated here, once, as a pure function over a package root, because
+ * three different callers need to ask the same question and a second definition would
+ * drift from the first:
+ *
+ *   - `test/test-evidence-kinds.mjs` asserts it against the repository;
+ *   - `scripts/verify-published.mjs` asserts it against the copy npm just installed
+ *     (the test directory is not shipped, so this is the only place the installed
+ *     artifact's coverage can be checked);
+ *   - `asf_evidence_check` answers it at runtime, so a session that suspects a broken
+ *     install can ask instead of guessing.
+ *
+ * `root` is the package directory, not a project: this is a question about ASF's own
+ * shipped code, and asking it about a user's repository would be meaningless.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** Files that could create a ledger entry. `.d.mts` are declarations, not code. */
+function sourceFiles(root) {
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(path.join(root, dir), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const rel = dir ? `${dir}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(rel);
+      else if (/\.(ts|mjs)$/.test(e.name) && !e.name.endsWith(".d.mts")) out.push(rel);
+    }
+  };
+  walk("lib");
+  if (fs.existsSync(path.join(root, "index.ts"))) out.push("index.ts");
+  return out;
+}
+
+/**
+ * The kinds a gate actually blocks on.
+ *
+ * Derived from the two files that make completion decisions, not from a list someone
+ * maintains: a hand-kept list rots the first time a gate starts requiring a kind and
+ * nobody updates the list next door.
+ */
+function requiredKinds(root, entryKinds) {
+  let text = "";
+  for (const rel of ["lib/gates/ledger.mjs", "lib/gates/settle.mjs"]) {
+    try {
+      text += fs.readFileSync(path.join(root, rel), "utf8") + "\n";
+    } catch {
+      /* a missing gate file is reported by the shipped-file check, not here */
+    }
+  }
+  const required = new Set(["suite-run", "health-run"]);
+  for (const m of text.matchAll(/(?:has|kind ===)\s*\(\s*"([a-z-]+)"/g)) required.add(m[1]);
+  for (const m of text.matchAll(/"([a-z-]+)"/g)) {
+    const k = m[1];
+    if (entryKinds.includes(k) && new RegExp(`(has|missing|latest|kind ===)[^\\n]*"${k}"`).test(text)) required.add(k);
+  }
+  return required;
+}
+
+/**
+ * @param {string} root      the ASF package directory (contains lib/ and index.ts)
+ * @param {string[]} entryKinds ENTRY_KINDS from the ledger — passed in rather than
+ *                             imported so this stays a question about files, and so a
+ *                             caller can ask it of any version's package directory
+ * @returns {{orphans: string[], requiredOrphans: string[], producers: Record<string,string[]>,
+ *            required: string[], kinds: string[], files: number}}
+ */
+export function evidenceCoverage(root, entryKinds) {
+  // ledger.mjs only defines, validates and renders its own kinds, so counting it as a
+  // producer would let the ledger certify itself.
+  const files = sourceFiles(root).filter((f) => !f.endsWith("gates/ledger.mjs"));
+  const sources = files.map((f) => ({ f, src: fs.readFileSync(path.join(root, f), "utf8") }));
+  const producers = {};
+  for (const kind of entryKinds) {
+    producers[kind] = sources.filter(({ src }) => new RegExp(`kind:\\s*"${kind}"`).test(src)).map(({ f }) => f);
+  }
+  const orphans = entryKinds.filter((k) => producers[k].length === 0);
+  const required = [...requiredKinds(root, entryKinds)];
+  return {
+    kinds: [...entryKinds],
+    required,
+    producers,
+    orphans,
+    requiredOrphans: required.filter((k) => !entryKinds.includes(k) || producers[k].length === 0),
+    files: files.length,
+  };
+}
+
+/**
+ * A coverage result expressed as a gap, or null when the install is sound.
+ *
+ * An orphan a gate requires is the serious case: the run is steered at evidence it has
+ * no hands to produce, which is the loop this module exists to prevent. An orphan
+ * nothing requires is dead weight — reported, never blocking.
+ */
+export function coverageGap(coverage) {
+  if (coverage.requiredOrphans.length) {
+    return {
+      gap: `the completion gate requires evidence of kind ${coverage.requiredOrphans.join(", ")}, but nothing in the installed package can record it`,
+      remedy: "that evidence can never be produced, so no run can close on it — this is a broken ASF install, not unfinished work",
+    };
+  }
+  if (coverage.orphans.length) {
+    return {
+      gap: `ledger kinds ${coverage.orphans.join(", ")} have no producer in the installed package`,
+      remedy: "reported, not blocking: nothing requires them, so they are dead weight rather than an unclosable gap",
+    };
+  }
+  return null;
+}

package/lib/home.mjs

@@ -41,6 +41,7 @@ export const GITIGNORE_BODY = "# ASF telemetry: append-only, machine-local, neve
 export const FILES = {
   config: { home: "config.json", legacy: ".asf-config.json" },
   baseline: { home: "code-health-baseline.json", legacy: ".asf-code-health-baseline.json" },
+  healthConfig: { home: "code-health.json", legacy: ".asf-code-health.json" },
   plan: { home: "PLAN.md", legacy: "PLAN.md" },
 };
 

package/package.json

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

@@ -166,5 +166,34 @@ installs anything.
 3. **The gate is a floor, not a ceiling.** Passing thresholds does not mean
    the code is good — 06c rules still apply.
 4. **Never disable the gate to ship.** If a metric is genuinely inapplicable,
-   disable that metric in `.asf-code-health.json` with a comment in the
-   commit message, not the whole gate.
+   disable that metric in `.asf/code-health.json` (the old root
+   `.asf-code-health.json` is still read, so projects configured before the move
+   keep their thresholds) with a comment in the commit message, not the whole gate.
+
+## When the gate itself is the problem: `asf_evidence_check`
+
+Every rule above has the same shape: the gate demands evidence, and there is an agent
+action that produces it. When that symmetry breaks, the run does not fail — it is
+steered, and steered, and steered, at a gap its own hands cannot close. That is the
+2026-11-07 loop, and it has reappeared three times in different clothes: a health
+verdict only a slash command could record, browser verification no tool could write, a
+delivery report rendering sections nothing ever produced.
+
+So the symmetry is now checked rather than hoped for. `asf_evidence_check` reads
+ASF's own installed files and answers one question: does every evidence kind a gate
+requires have something in the package that can record it?
+
+```
+asf_evidence_check                       # whole picture: sound, or broken and how
+asf_evidence_check { kind: "browser-verify" }   # who records this kind, or nobody
+```
+
+**If it reports an unproducible required kind, stop trying to close the gap.** That is
+a broken install, not unfinished work — no amount of effort produces evidence nothing
+in the package can write. Say so, and say what it named.
+
+The same invariant is asserted against the repository in
+`test/test-evidence-kinds.mjs`, and against the copy npm actually serves in
+`scripts/verify-published.mjs` — the test directory is not shipped, so without that
+last one a broken tarball would reproduce the loop for every user while the repo
+stayed green.