pi-aia-asf 0.17.7 → 0.17.8

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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/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/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.8",
   "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/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