pi-aia-asf 0.17.13 → 0.18.0

package/CHANGELOG.md

@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-11-10
+
+### Added — a run can be completed, and tests can no longer corrupt one
+
+Two defects from the same blind spot: ASF tracked runs but had no honest way to finish
+one, and nothing stopped a test suite from writing into the run state a real user reads.
+
+**`asf_run_complete`.** A run used to close only when the completion gate happened to
+pass at settle time, or when a human typed `/asf abort`. There was no action the agent
+could take, so a run that had genuinely finished stayed open and swallowed the next
+piece of work. This project carried a single run opened three days earlier that had
+absorbed several releases and unrelated changes in its `filesTouched` — the gate was
+judging today's work against Monday's evidence, so nothing settled and the loop never
+closed. The user's instruction was to "properly complete and mark as completed every
+run, so you judge the next run separately again".
+
+- The tool asks the **same question the gate asks**: `evaluateRun()` is now the single
+  judge, called by both `judgeAndSettle` and the tool. Two implementations of "is this
+  run done" drift, and the drift reads as a run the agent closed that the gate still
+  counts as open.
+- It **fails closed**. An unfinished run is refused with its gaps listed and stays open
+  with its evidence. A tool that closed runs on request would be an exit around the
+  completion gate, which is worse than the bug it fixes.
+- `closeRun()` is the only writer of run history and the only clearer of `current`, and
+  it records `by` — `auto` from the gate, `asf_run_complete` from the agent — so a close
+  that happened outside the gate is visible in evidence.
+
+### Changed — the decision register follows the code
+
+`asf_decisions` wrote to the session workspace. Working in a repository opened from a
+parent directory (a home directory that is itself a checkout is the common case) put the
+ADRs one level above the project they describe, where nothing would ever read them. The
+register is durable knowledge *about* the code, so it now resolves through `measureRoot()`
+like every other measurement. `currentRegister()` was deleted: it announced itself as
+"exposed for the handlers" and had no callers.
+
+### Fixed — a test suite could not touch a live run
+
+A suite that forgot to `chdir` wrote into the developer's real run state: `/etc/passwd`
+and a scratch path appeared in the live run's `filesTouched`, and the reviewer saw them
+in the run card. State is the one thing a test corrupts with no visible failure — the
+assertion passes and the user's screen is wrong.
+
+- `homeStateDir()` honours `ASF_STATE_ROOT`, and `test/harness.mjs` sets it to a fresh
+  temp directory before the extension loads. The whole suite is now provably inert
+  against real state, verified by diffing the state tree across a full `run-all`.
+- `test-decisions.mjs` pins **both** behaviours — the real `.asf/state/<key>` layout when
+  unset, the override when set — so the isolation cannot silently defeat the assertion
+  it was added next to.
+
+`scripts/verify-published.mjs` also states its own boundary: `scripts/` does not ship, so
+a user cannot run it, which is fine only because every assertion it makes delegates to
+shipped code (`lib/gates/evidence-coverage.mjs`, the same module behind
+`asf_evidence_check`). A check added there that cannot be reproduced from an install is a
+check only a releaser can run.
+
 ## [0.17.13] - 2026-11-10
 
 ### Changed — no scale means small (PO policy)

package/index.ts

@@ -20,6 +20,7 @@ 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 { registerRunCompleteTool } from "./lib/extension/tools/run-complete.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";
@@ -34,6 +35,7 @@ export default function register(pi: ExtensionAPI): void {
   registerDecisionsTool(pi);
   registerBrowserTools(pi);
   registerEvidenceCheckTool(pi);
+  registerRunCompleteTool(pi);
   registerCommands(pi);
   registerToolCallHandler(pi);
   registerToolResultHandler(pi);

package/lib/extension/handlers/settle.ts

@@ -135,10 +135,21 @@ async function handleBlock(
   return { entries, continue: true };
 }
 
-/** An auto-opened run whose floor is met closes itself. */
-async function closeAutoRun(state: AsfState, project: string, file: ProjectStateFile): Promise<void> {
+/**
+ * Close a run: archive it to history and clear `current`.
+ *
+ * The next piece of work then opens its own run and is judged on its own facts. A run
+ * that is never closed accretes everything the session does — this project once carried
+ * a single run opened three days earlier, with four releases and several unrelated
+ * changes inside its `filesTouched`, so the gate was judging today's work against
+ * Monday's evidence and nothing could settle.
+ *
+ * `by` records who closed it: the gate itself (`auto`) or the agent asking
+ * (`asf_run_complete`), so a run that closed without the gate passing is visible.
+ */
+export async function closeRun(state: AsfState, file: ProjectStateFile, { project, by = "auto" }: { project: string; by?: string }): Promise<void> {
   file.history.push({ workType: state.workType || "auto", phase: state.phase, startedAt: state.startedAt || state.updatedAt, endedAt: new Date().toISOString() });
-  appendEvidence({ kind: "run-close", runId: state.runId, auto: true });
+  appendEvidence({ kind: "run-close", runId: state.runId, auto: by === "auto", by });
   file.current = null;
   await saveState(project, file);
 }
@@ -179,8 +190,15 @@ function decisionFacts(state: AsfState) {
   }
 }
 
-async function judgeAndSettle(ctx: SettleContext, priorCount: number): Promise<SettleResult> {
-  const { project, file, state, entries } = ctx;
+/**
+ * Judge a run: the same decision the completion gate makes, in one place.
+ *
+ * Exported because the agent needs to ask the same question before it claims a run is
+ * finished (`asf_run_complete`). Two implementations of "is this run done" drift, and
+ * the drift shows up as a run the agent closed and the gate still thinks is open —
+ * which is how a run from three days ago was still being carried into new work.
+ */
+export async function evaluateRun(project: string, state: AsfState) {
   // Only a passing test that STARTED after the last source change validates it.
   const since = typeof state.lastMutationAt === "number" ? state.lastMutationAt : 0;
   const testRunRecorded = suiteRuns.some((r) => r.exitCode === 0 && (r.at ?? 0) >= since);
@@ -189,7 +207,7 @@ async function judgeAndSettle(ctx: SettleContext, priorCount: number): Promise<S
   // stale, raced or hand-edited. max() means a counter can never go down.
   const mem = steerLedgerFor(`${project}|${state.runId || "run"}`);
   sanitizeSteerFields(state);
-  const decision = decideSettlement(ledger, {
+  return decideSettlement(ledger, {
     untracedMet,
     scale: currentScale(state),
     webTouched: runtime.webTouched,
@@ -200,12 +218,18 @@ async function judgeAndSettle(ctx: SettleContext, priorCount: number): Promise<S
     tracked: runtime.tracked,
     decisionGaps: decisionFacts(state),
   });
+}
+
+async function judgeAndSettle(ctx: SettleContext, priorCount: number): Promise<SettleResult> {
+  const { project, file, state, entries } = ctx;
+  const mem = steerLedgerFor(`${project}|${state.runId || "run"}`);
+  const decision = await evaluateRun(project, state);
   runtime.lastSettleDecision = decision;
   appendEvidence({ kind: "gate-verdict", gate: "completion", fired: decision.missing.length > 0, missing: decision.missing });
 
   if (decision.park) return await handlePark(ctx, decision.park as { reason: string; question: string });
   if (decision.block) return await handleBlock({ ...ctx, mem }, decision as BlockRequest);
-  if (decision.missing.length === 0 && state.auto) await closeAutoRun(state, project, file);
+  if (decision.missing.length === 0 && state.auto) await closeRun(state, file, { project });
   // A continuation for guidance alone is also bounded: an agent that keeps
   // producing new distinct steers must not be kept alive by its own advice.
   if (entries.length > priorCount && steerContinuationsAllowed(mem)) return { entries, continue: true };

package/lib/extension/tools/decisions.ts

@@ -21,6 +21,7 @@ import { registerAt, addDecision, supersedeDecision, relativeTo } from "../../de
 import { matchesAny } from "../../decisions/glob.mjs";
 import { readProjectConfig } from "../../gates/config.mjs";
 import { runRoot, projectName } from "../paths.ts";
+import { measureRoot } from "../run.ts";
 import { loadState } from "../state.ts";
 import { runtime } from "../runtime.ts";
 import { appendEvidence } from "../evidence.ts";
@@ -43,9 +44,12 @@ async function planApproved(): Promise<boolean> {
   }
 }
 
-function config(): Record<string, unknown> {
+function config(root: string): Record<string, unknown> {
   try {
-    return readProjectConfig(runRoot());
+    // The register is durable knowledge ABOUT the code, so it follows the code the
+    // run is changing — not the session workspace, which for a repo opened from a
+    // parent directory would put the ADRs one level above the project they describe.
+    return readProjectConfig(root);
   } catch {
     return {};
   }
@@ -88,14 +92,14 @@ function renderProblems(problems: { severity: string; file?: string; field?: str
 }
 
 async function listAction(root: string): Promise<ActionOut> {
-  const { dir, records, problems } = registerAt(root, config());
+  const { dir, records, problems } = registerAt(root, config(root));
   const errors = problems.filter((p) => p.severity === "error");
   const text = `${dir}\n\n${renderList(records)}${errors.length ? `\n\n${renderProblems(errors)}` : ""}`;
   return { text, ok: errors.length === 0, count: records.length };
 }
 
 async function getAction(root: string, id: string): Promise<ActionOut> {
-  const { records } = registerAt(root, config());
+  const { records } = registerAt(root, config(root));
   const found = records.find((r) => String(r.id).toLowerCase() === id.toLowerCase());
   if (!found) return { text: `No ${id} in the register.`, ok: false, count: 0 };
   if (!runtime.decisionsRead.includes(String(found.id))) runtime.decisionsRead.push(String(found.id));
@@ -106,7 +110,7 @@ async function getAction(root: string, id: string): Promise<ActionOut> {
 }
 
 async function matchAction(root: string, filePath: string): Promise<ActionOut> {
-  const { records } = registerAt(root, config());
+  const { records } = registerAt(root, config(root));
   const hit = records.filter((r) => r.status === "accepted" && matches(r, filePath));
   const text = hit.length
     ? `${filePath} is governed by:\n${renderList(hit)}\n\nRead them with action=get before changing the file.`
@@ -121,11 +125,11 @@ function matches(r: DecisionRecord, filePath: string): boolean {
 
 async function recordAction(root: string, p: Record<string, unknown>): Promise<ActionOut> {
   const approved = await planApproved();
-  const { records } = registerAt(root, config());
+  const { records } = registerAt(root, config(root));
   const out = addDecision(root, {
     record: recordFrom(p),
     body: str(p.body),
-    config: config(),
+    config: config(root),
     planApproved: approved,
     read: records,
   });
@@ -140,7 +144,7 @@ async function recordAction(root: string, p: Record<string, unknown>): Promise<A
 
 async function supersedeAction(root: string, p: Record<string, unknown>): Promise<ActionOut> {
   const approved = await planApproved();
-  const { records } = registerAt(root, config());
+  const { records } = registerAt(root, config(root));
   // The `id` parameter names the decision being REPLACED; the record built from
   // the same params must not carry it, or the new decision is written with the old
   // decision's id and the register ends up with two claimants for one number.
@@ -150,7 +154,7 @@ async function supersedeAction(root: string, p: Record<string, unknown>): Promis
     by: "agent",
     record: recordFrom(recordParams),
     body: str(p.body),
-    config: config(),
+    config: config(root),
     planApproved: approved,
     read: records,
   });
@@ -161,7 +165,7 @@ async function supersedeAction(root: string, p: Record<string, unknown>): Promis
 }
 
 async function checkAction(root: string): Promise<ActionOut> {
-  const { dir, records, problems } = registerAt(root, config());
+  const { dir, records, problems } = registerAt(root, config(root));
   const errors = problems.filter((p) => p.severity === "error");
   const notices = problems.filter((p) => p.severity === "notice");
   // What the completion floor believes about THIS run. Without it the citation rules
@@ -228,7 +232,7 @@ export function registerDecisionsTool(pi: ExtensionAPI): void {
     promptSnippet: "Consult or record the project's architecture decisions",
     parameters: Type.Object(DECISION_PARAMS),
     async execute(_toolCallId: string, params: Record<string, unknown>) {
-      const root = runRoot();
+      const root = await measureRoot();
       const action = str(params?.action);
       try {
         return toolResult(action, await runAction(root, action, params));
@@ -245,7 +249,3 @@ export function registerDecisionsTool(pi: ExtensionAPI): void {
   });
 }
 
-/** Exposed for the handlers: the register as the rest of ASF sees it. */
-export function currentRegister() {
-  return registerAt(runRoot(), config());
-}

package/lib/extension/tools/run-complete.ts

@@ -0,0 +1,95 @@
+/**
+ * asf_run_complete — the agent's way to finish a run.
+ *
+ * A run used to close only when the completion gate happened to pass at settle time,
+ * or when a human typed `/asf abort`. Neither is an action the agent can take, so a run
+ * that had genuinely finished stayed open and swallowed the next piece of work: this
+ * project carried one run opened three days earlier, holding four releases and several
+ * unrelated changes in its `filesTouched`, and the gate judged today's work against
+ * Monday's evidence. Nothing settled, and the loop never closed.
+ *
+ * It asks the SAME question the gate asks (`evaluateRun`), so the tool and the gate
+ * cannot disagree about what "done" means. And it fails closed: an unfinished run is
+ * refused with the gaps listed. A tool that closed runs on request would be an exit
+ * around the completion gate, which is worse than the bug it fixes.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { projectName } from "../paths.ts";
+import { loadState } from "../state.ts";
+import { evaluateRun, closeRun } from "../handlers/settle.ts";
+
+/** One details shape for every branch: branches that disagree about which fields
+ *  exist make the host read `error` as required and reject the tool. */
+function details() {
+  return {
+    action: "run-complete",
+    ok: false,
+    closed: false,
+    error: "",
+    runId: "",
+    note: "",
+    missing: [] as string[],
+  };
+}
+
+async function completeRun(note: string) {
+  const project = projectName();
+  const file = await loadState(project);
+  const state = file.current;
+  if (!state || state.phase === "none") {
+    return {
+      text: "No active ASF run to complete — the next piece of work opens a fresh one.",
+      res: { ...details(), error: "no-run" },
+    };
+  }
+
+  const decision = await evaluateRun(project, state);
+  const missing = decision.missing || [];
+  if (missing.length > 0) {
+    // Refusing is the whole point: this is the gate's own verdict, not a formality.
+    return {
+      text:
+        `Run ${state.runId} is NOT complete — the definition of done still has ${missing.length} gap(s):\n` +
+        missing.map((m: string) => `- ${m}`).join("\n") +
+        `\n\nClose those and call it again. The run stays open and keeps its evidence.`,
+      res: { ...details(), runId: state.runId || "", missing },
+    };
+  }
+
+  const runId = state.runId || "run";
+  await closeRun(state, file, { project, by: "asf_run_complete" });
+  return {
+    text:
+      `Run ${runId} complete (${state.phase}${state.scale ? `, ${state.scale}` : ""})` +
+      `${note ? ` — ${note}` : ""}. It is archived to history and the next piece of work ` +
+      `opens a fresh run, judged on its own facts.`,
+    res: { ...details(), ok: true, closed: true, runId, note },
+  };
+}
+
+export function registerRunCompleteTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "asf_run_complete",
+    label: "ASF Complete Run",
+    description:
+      "Finish the current ASF run so the NEXT piece of work is judged on its own facts. " +
+      "Call it when the work this run was opened for is genuinely done — tests run, evidence " +
+      "recorded, released if it was a release. It asks the same question the completion gate " +
+      "asks, so it cannot be used to get around the gate: an unfinished run is refused with " +
+      "the gaps listed, and the run stays open.",
+    promptSnippet: "Mark the current run complete (only if its definition of done is met)",
+    parameters: Type.Object({
+      note: Type.Optional(
+        Type.String({ description: "One line on what the run delivered; recorded with the closure." }),
+      ),
+    }),
+
+    async execute(_toolCallId: string, params: { note?: unknown }) {
+      const note = typeof params?.note === "string" ? params.note.trim() : "";
+      const { text, res } = await completeRun(note);
+      return { content: [{ type: "text" as const, text }], details: res };
+    },
+  });
+}

package/lib/home.mjs

@@ -49,8 +49,20 @@ export function asfDir(root) {
   return path.join(root, ASF_DIR);
 }
 
-/** Where the run state lives now. `key` is the project key (git-root based). */
+/**
+ * Where the run state lives now. `key` is the project key (git-root based).
+ *
+ * `ASF_STATE_ROOT` redirects the whole tree. It exists for one reason: a suite that
+ * forgets to `chdir` was writing into the developer's LIVE run state, and the garbage
+ * (a `/etc/passwd` entry in `filesTouched`) showed up in the run card the reviewer
+ * reads. State is the one piece of ASF that a test can corrupt without noticing, so
+ * the test harness points it at a temp directory and no suite can reach the real one.
+ */
 export function homeStateDir(root, key) {
+  const override = process.env.ASF_STATE_ROOT;
+  // The key is derived from the git root, so it is already unique per project;
+  // nesting the root under the override again would only make the path unreadable.
+  if (typeof override === "string" && override.trim()) return path.join(path.resolve(override), key);
   return path.join(asfDir(root), STATE_SUBDIR, key);
 }
 

package/package.json

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