@gtrabanco/pi-agentic-workflow 0.7.1 → 0.8.0

package/dist/settings/console.js

@@ -8,8 +8,9 @@
 // the operator must fix, not noise to clobber), and the project scope is refused
 // while the project is untrusted — the same gate the loader applies (AC13).
 import { loadConfig, configFilePaths } from "../config/load.js";
+import { effectiveRoute } from "../config/merge.js";
 import { parseConfigFile, parseModelReference } from "../config/schema.js";
-import { THINKING_LEVELS, UNAVAILABLE_ROUTE_POLICIES } from "../config/types.js";
+import { MAX_MODEL_CHAIN, THINKING_LEVELS, UNAVAILABLE_ROUTE_POLICIES } from "../config/types.js";
 import { renderMergedConfig, routePath, DEFAULT_ROUTE } from "./view.js";
 /** The console's questions. `test/settings-console.test.mjs` drives the flow
  * through these strings, so renaming one fails the tests that use it rather than
@@ -27,12 +28,23 @@ export const prompts = {
     setDefaultRoute: "Set the default route",
     setOverride: "Set a command override",
     clearOverride: "Clear a command override",
+    bulkApply: "Apply one route to several commands",
+    bulkClear: "Clear several overrides",
+    addAnother: "Add another?",
     policy: "Set the unavailable-route policy",
     save: "Save",
     cancel: "Cancel",
     model: (target) => `Model for ${target}?`,
     modelPicked: (target) => `Which model for ${target}?`,
     thinking: (target) => `Thinking level for ${target}?`,
+    fields: "Which fields should change?",
+    fieldsBoth: "model and thinking",
+    fieldsModel: "model only",
+    fieldsThinking: "thinking only",
+    chainAction: (target) => `Model chain for ${target}?`,
+    chainAppend: "Add a fallback",
+    chainRemoveLast: "Remove the last",
+    chainDone: "Done",
 };
 const GLOBAL_LABEL = "Global";
 const PROJECT_LABEL = "Project";
@@ -40,7 +52,10 @@ const TYPED = "Type another reference…";
 const INHERIT = "inherit";
 export async function runSettingsConsole(deps) {
     const paths = configFilePaths(deps.agentDir, deps.cwd);
-    deps.ui.notify(renderMergedConfig(loadConfig({ agentDir: deps.agentDir, cwd: deps.cwd, projectTrusted: deps.projectTrusted, readFile: deps.readFile }), deps.commands).join("\n"), "info");
+    const merged = loadConfig({ agentDir: deps.agentDir, cwd: deps.cwd, projectTrusted: deps.projectTrusted, readFile: deps.readFile });
+    deps.ui.notify(renderMergedConfig(merged, deps.commands).join("\n"), "info");
+    /** The value in force for a target (the merged route, or the default when the target is "the default route"). */
+    const currentFor = (target) => effectiveRoute(merged.config, target);
     const opened = await openAScope(deps, paths.global, paths.project);
     if (!opened)
         return { status: "cancelled", edited: false };
@@ -53,6 +68,8 @@ export async function runSettingsConsole(deps) {
             prompts.setDefaultRoute,
             prompts.setOverride,
             prompts.clearOverride,
+            prompts.bulkApply,
+            prompts.bulkClear,
             prompts.policy,
             ...(deps.routing?.inFlight() ? [prompts.undoInFlight] : []),
             prompts.save,
@@ -67,7 +84,7 @@ export async function runSettingsConsole(deps) {
             return { status: "cancelled", edited: dirty(draft, original) ? await discard(deps.ui) : false };
         }
         if (choice === prompts.setDefaultRoute) {
-            const edited = await editRoute(deps, DEFAULT_ROUTE);
+            const edited = await editRoute(deps, DEFAULT_ROUTE, currentFor(DEFAULT_ROUTE));
             if (edited)
                 draft = { ...draft, default: edited };
             continue;
@@ -76,7 +93,7 @@ export async function runSettingsConsole(deps) {
             const name = await pickCommand(deps, commandChoices(deps, draft));
             if (name === undefined)
                 continue;
-            const route = await editRoute(deps, name);
+            const route = await editRoute(deps, name, currentFor(name));
             if (route)
                 draft = { ...draft, commands: { ...draft.commands, [name]: route } };
             continue;
@@ -90,6 +107,35 @@ export async function runSettingsConsole(deps) {
             draft = { ...draft, commands: rest };
             continue;
         }
+        if (choice === prompts.bulkApply) {
+            // One field pass (model via the chain builder + thinking), applied to every
+            // selected command. A reference missing from the live registry warns per
+            // command but never blocks the write (OB-4 — dispatch's probe stays the
+            // authoritative availability gate).
+            const selected = await pickCommandsMulti(deps, commandChoices(deps, draft));
+            if (selected === undefined || selected.length === 0)
+                continue;
+            const route = await editRoute(deps, selected[0], currentFor(selected[0]));
+            if (route === undefined)
+                continue;
+            const nextCommands = { ...draft.commands };
+            for (const name of selected) {
+                nextCommands[name] = route;
+                warnMissingModel(deps, name, route.model ?? INHERIT);
+            }
+            draft = { ...draft, commands: nextCommands };
+            continue;
+        }
+        if (choice === prompts.bulkClear) {
+            const names = await pickCommandsMulti(deps, Object.keys(draft.commands ?? {}));
+            if (names === undefined || names.length === 0)
+                continue;
+            const rest = { ...draft.commands };
+            for (const name of names)
+                delete rest[name];
+            draft = { ...draft, commands: rest };
+            continue;
+        }
         if (choice === prompts.policy) {
             const picked = await deps.ui.select(prompts.policyChoice, [...UNAVAILABLE_ROUTE_POLICIES]);
             if (isPolicy(picked))
@@ -133,18 +179,54 @@ async function openAScope(deps, globalPath, projectPath) {
     }
 }
 /** Ask for a model and a thinking level; `undefined` means nothing changed. */
-async function editRoute(deps, target) {
-    const model = await askModel(deps, target);
-    if (model === undefined)
-        return undefined;
-    const thinking = await askThinking(deps, target);
-    if (thinking === undefined)
-        return undefined;
-    return { model, thinking };
+async function editRoute(deps, target, current) {
+    const fields = await askFields(deps);
+    if (fields === undefined)
+        return undefined; // nothing marked — the route is left untouched (OB-3)
+    // Start from the value in force so only the marked field is replaced; the other
+    // keeps its merged value (AC4: changing only model asks no thinking question).
+    const route = {
+        ...(current.model !== undefined ? { model: current.model } : {}),
+        ...(current.thinking !== undefined ? { thinking: current.thinking } : {}),
+    };
+    if (fields.model) {
+        const model = await askModel(deps, target, current.model);
+        if (model === undefined)
+            return undefined;
+        route.model = model;
+    }
+    if (fields.thinking) {
+        const thinking = await askThinking(deps, target, current.thinking);
+        if (thinking === undefined)
+            return undefined;
+        route.thinking = thinking;
+    }
+    return route;
+}
+/** Which fields the operator wants to change; `undefined` means none (leave untouched). */
+async function askFields(deps) {
+    const choice = await deps.ui.select(prompts.fields, [prompts.fieldsBoth, prompts.fieldsModel, prompts.fieldsThinking]);
+    if (choice === prompts.fieldsBoth)
+        return { model: true, thinking: true };
+    if (choice === prompts.fieldsModel)
+        return { model: true, thinking: false };
+    if (choice === prompts.fieldsThinking)
+        return { model: false, thinking: true };
+    return undefined;
 }
-async function askModel(deps, target) {
+/** Ask for one model entry; `undefined` means cancelled/skipped, `"inherit"` means the whole-route setting. */
+async function pickModelEntry(deps, target, current) {
     let answer;
-    if (deps.models && deps.models.length > 0) {
+    if (typeof deps.ui.pick === "function" && deps.models && deps.models.length > 0) {
+        // Rich seam: filterable, windowed, preselected to the value in force (OB-1).
+        const picked = await deps.ui.pick(prompts.modelPicked(target), [...deps.models, TYPED], {
+            initial: typeof current === "string" ? current : undefined,
+        });
+        answer = typeof picked === "string" ? picked : undefined;
+        if (answer === TYPED || answer === undefined)
+            answer = await deps.ui.input(prompts.model(target), "provider/modelId or inherit");
+    }
+    else if (deps.models && deps.models.length > 0) {
         answer = await deps.ui.select(prompts.modelPicked(target), [...deps.models, TYPED]);
         if (answer === TYPED || answer === undefined)
             answer = await deps.ui.input(prompts.model(target), "provider/modelId or inherit");
@@ -157,17 +239,80 @@ async function askModel(deps, target) {
     const value = answer.trim();
     if (value === INHERIT)
         return INHERIT;
-    if (!/^[^/\s]+\/[^/\s]+$/.test(value)) {
+    const parts = parseModelReference(value);
+    if (!parts) {
         // Rejected in the operator's terms and in the schema's: the value, and the
         // field path the loader would name for the same mistake in a file (AC5).
         deps.ui.notify(`Rejected: model must be "provider/modelId" or "inherit" — nothing was changed (${routePath(target)}.model).`, "error");
         return undefined;
     }
-    const parts = parseModelReference(value);
-    return parts ? `${parts.provider}/${parts.id}` : undefined;
+    return `${parts.provider}/${parts.id}`;
+}
+/** Ask for a model; a lone reference is returned as-is, several references are returned as an ordered chain. */
+async function askModel(deps, target, current) {
+    // The value in force (OB-3). For a route whose model is already a chain, seed
+    // the builder with the current references so the operator sees and edits the
+    // chain instead of rebuilding it blind (OB-17 / F2, amendment A1). Fresh and
+    // single-string editing keep the existing flow: the picker is preselected to
+    // the string value in force.
+    const seed = Array.isArray(current) ? [...current] : [];
+    if (seed.length > 0) {
+        // Already a chain: label the current chain, then let the operator append,
+        // trim, or keep it. Done with no change leaves the chain byte-identical.
+        deps.ui.notify(`Current ${target} model chain: ${seed.join(" → ")}`, "info");
+        return buildModelChain(deps, target, [...seed]);
+    }
+    const first = await pickModelEntry(deps, target, typeof current === "string" ? current : undefined);
+    if (first === undefined)
+        return undefined;
+    if (first === INHERIT)
+        return INHERIT;
+    return buildModelChain(deps, target, [first]);
 }
-async function askThinking(deps, target) {
-    const answer = await deps.ui.select(prompts.thinking(target), [...THINKING_LEVELS, INHERIT]);
+/** Drive the ordered chain builder over the given starting chain; a single entry collapses to a bare reference. */
+async function buildModelChain(deps, target, chain) {
+    for (;;) {
+        const atCap = chain.length >= MAX_MODEL_CHAIN;
+        if (atCap) {
+            deps.ui.notify(`A model chain is capped at ${MAX_MODEL_CHAIN} references — remove the last to make room (${routePath(target)}.model).`, "info");
+        }
+        const action = await deps.ui.select(prompts.chainAction(target), [
+            ...(atCap ? [] : [prompts.chainAppend]),
+            prompts.chainRemoveLast,
+            prompts.chainDone,
+        ]);
+        if (action === prompts.chainAppend) {
+            const next = await pickModelEntry(deps, target);
+            if (next === undefined)
+                continue;
+            if (next === INHERIT) {
+                deps.ui.notify(`Only "provider/modelId" references can be chain entries; "inherit" is a whole-route setting (${routePath(target)}.model).`, "error");
+                continue;
+            }
+            chain.push(next);
+        }
+        else if (action === prompts.chainRemoveLast) {
+            if (chain.length > 1)
+                chain.pop();
+        }
+        else {
+            break;
+        }
+    }
+    return chain.length === 1 ? chain[0] : chain;
+}
+async function askThinking(deps, target, current) {
+    const options = [...THINKING_LEVELS, INHERIT];
+    let answer;
+    if (typeof deps.ui.pick === "function") {
+        const picked = await deps.ui.pick(prompts.thinking(target), options, {
+            initial: typeof current === "string" ? current : undefined,
+        });
+        answer = typeof picked === "string" ? picked : undefined;
+    }
+    else {
+        answer = await deps.ui.select(prompts.thinking(target), options);
+    }
     if (answer === undefined)
         return undefined;
     if (answer === INHERIT || isThinkingLevel(answer))
@@ -182,6 +327,45 @@ async function pickCommand(deps, options) {
     }
     return deps.ui.select(prompts.command, [...options].sort((a, b) => a.localeCompare(b)));
 }
+/** Multi-select command picker over the seam's `multiple` mode; a non-rich UI falls back to repeated single selects. */
+async function pickCommandsMulti(deps, options) {
+    if (options.length === 0) {
+        deps.ui.notify("There is no command to pick here.", "warning");
+        return undefined;
+    }
+    const sorted = [...options].sort((a, b) => a.localeCompare(b));
+    if (typeof deps.ui.pick === "function") {
+        const picked = await deps.ui.pick(prompts.command, sorted, { multiple: true });
+        if (picked === undefined)
+            return undefined;
+        return typeof picked === "string" ? [picked] : picked;
+    }
+    // Non-rich fallback: repeatedly select one candidate until the operator stops.
+    const chosen = [];
+    for (;;) {
+        const remaining = sorted.filter((option) => !chosen.includes(option));
+        if (remaining.length === 0)
+            break;
+        const picked = await deps.ui.select(prompts.command, remaining);
+        if (picked === undefined)
+            break;
+        chosen.push(picked);
+        if (!(await deps.ui.confirm(prompts.addAnother, `Picked ${chosen.join(", ")}.`)))
+            break;
+    }
+    return chosen.length > 0 ? chosen : undefined;
+}
+/** Advisory per-command warning when a chosen reference is absent from the live registry (OB-4). */
+function warnMissingModel(deps, target, model) {
+    if (!deps.models || deps.models.length === 0)
+        return;
+    const refs = typeof model === "string" ? [model] : model;
+    for (const ref of refs) {
+        if (ref !== INHERIT && !deps.models.includes(ref)) {
+            deps.ui.notify(`/${target}: ${ref} is not in the live model registry — dispatch will decide availability when the route runs.`, "warning");
+        }
+    }
+}
 function commandChoices(deps, draft) {
     return [...new Set([...deps.commands, ...Object.keys(draft.commands ?? {})])];
 }

package/dist/settings/picker.d.ts

@@ -0,0 +1,31 @@
+import { type Component, type SelectItem, type SelectListTheme } from "@earendil-works/pi-tui";
+/** Default window height for the SelectList (the built-in position indicator scales to the list). */
+export declare const PICKER_MAX_VISIBLE = 10;
+/**
+ * Token/subsequence, slash-aware reference filter (OB-2).
+ *
+ * - An empty query returns every reference.
+ * - The query is split on whitespace; every token must match for a reference to
+ *   survive.
+ * - A token matched as a *subsequence* (characters in order, not necessarily
+ *   contiguous): `flash` matches any reference containing `flash`, `a/c`
+ *   matches `anthropic/claude`.
+ * - A token ending in `/` constrains to the provider: `nan/` matches provider
+ *   `nan` only, never a model id that merely contains `nan`.
+ */
+export declare function filterReferences(query: string, refs: readonly string[]): string[];
+/**
+ * Wrap a `SelectList` as a pi-tui `Component`, rebuilding it client-side from
+ * `filterReferences` as the operator types so the subsequence/slash-aware
+ * filter (OB-2) — not `SelectList`'s own prefix `setFilter` — drives what the
+ * window shows. Control keys (arrows, Enter, Escape) forward to the list.
+ */
+export declare function createPickerComponent(options: {
+    items: readonly SelectItem[];
+    maxVisible: number;
+    theme: SelectListTheme;
+    onSelect: (value: string) => void;
+    onCancel?: () => void;
+}): Component & {
+    dispose?(): void;
+};

package/dist/settings/picker.js

@@ -0,0 +1,93 @@
+// src/settings/picker.ts
+// The searchable windowed picker primitive (OB-1, OB-2, OB-12, PE-004).
+//
+// Two concerns live here on purpose:
+//  - `filterReferences` is the pure, session-free subsequence/slash-aware filter
+//    (OB-2). It is unit-tested in `test/picker-filter.test.mjs`.
+//  - `createPickerComponent` wraps `@earendil-works/pi-tui`'s `SelectList` as a
+//    `Component` so the adapter (extension/index.ts) can drive it through
+//    `ctx.ui.custom()` — windowed rendering with a position indicator, typing
+//    to narrow the list, selection, and cancel. The Pi-free `SettingsUi.pick`
+//    seam stays separated so the filter and the component are exercisable
+//    without a live session.
+//
+// The filter is implemented in this package (not imported from Pi): PE-004
+// confirmed pi-coding-agent's `fuzzyFilter` is internal, so the same
+// token/subsequence, slash-aware semantics the acceptance criteria pin live here.
+import { SelectList } from "@earendil-works/pi-tui";
+/** Default window height for the SelectList (the built-in position indicator scales to the list). */
+export const PICKER_MAX_VISIBLE = 10;
+/**
+ * Token/subsequence, slash-aware reference filter (OB-2).
+ *
+ * - An empty query returns every reference.
+ * - The query is split on whitespace; every token must match for a reference to
+ *   survive.
+ * - A token matched as a *subsequence* (characters in order, not necessarily
+ *   contiguous): `flash` matches any reference containing `flash`, `a/c`
+ *   matches `anthropic/claude`.
+ * - A token ending in `/` constrains to the provider: `nan/` matches provider
+ *   `nan` only, never a model id that merely contains `nan`.
+ */
+export function filterReferences(query, refs) {
+    const tokens = query.trim().split(/\s+/u).filter((token) => token !== "");
+    if (tokens.length === 0)
+        return [...refs];
+    return refs.filter((ref) => tokens.every((token) => matchesToken(token, ref)));
+}
+function matchesToken(token, ref) {
+    // Slash-aware: a trailing slash makes the token a provider prefix.
+    if (token.endsWith("/")) {
+        const provider = token.slice(0, -1);
+        if (provider === "")
+            return true;
+        const refProvider = ref.split("/")[0] ?? "";
+        return refProvider.startsWith(provider);
+    }
+    return isSubsequence(token, ref);
+}
+/** True when `needle` appears in `haystack` with its characters in order. */
+function isSubsequence(needle, haystack) {
+    let i = 0;
+    for (let j = 0; j < haystack.length && i < needle.length; j += 1) {
+        if (haystack.charCodeAt(j) === needle.charCodeAt(i))
+            i += 1;
+    }
+    return i === needle.length;
+}
+/**
+ * Wrap a `SelectList` as a pi-tui `Component`, rebuilding it client-side from
+ * `filterReferences` as the operator types so the subsequence/slash-aware
+ * filter (OB-2) — not `SelectList`'s own prefix `setFilter` — drives what the
+ * window shows. Control keys (arrows, Enter, Escape) forward to the list.
+ */
+export function createPickerComponent(options) {
+    const { items, maxVisible, theme, onSelect, onCancel } = options;
+    let filterText = "";
+    const byValue = new Map(items.map((item) => [item.value, item]));
+    const buildList = () => {
+        const visible = filterReferences(filterText, items.map((item) => item.value)).map((value) => byValue.get(value) ?? { value, label: value });
+        const list = new SelectList(visible, maxVisible, theme);
+        list.onSelect = (item) => onSelect(item.value);
+        list.onCancel = onCancel;
+        return list;
+    };
+    let list = buildList();
+    return {
+        render: (width) => list.render(width),
+        invalidate: () => list.invalidate(),
+        handleInput(data) {
+            // Enter / Ctrl+C / ANSI sequences (arrows) go to the SelectList; any other
+            // single character narrows the in-package filter and rebuilds the window.
+            if (data === "\r" || data === "\u0003" || data.startsWith("\u001b") || data.length > 1) {
+                list.handleInput(data);
+                return;
+            }
+            filterText += data;
+            list = buildList();
+        },
+        dispose: () => {
+            // The SelectList holds no resources beyond the rendered lines.
+        },
+    };
+}

package/dist/settings/view.js

@@ -34,7 +34,10 @@ function configLines(config, commands) {
     ];
 }
 function route(value) {
-    return `${value.model} / ${value.thinking}`;
+    // A chain renders its references in order, with the fallback arrow the spec
+    // names (OB-14); a single reference and `inherit` keep their existing render.
+    const model = Array.isArray(value.model) ? value.model.join(" → ") : value.model;
+    return `${model} / ${value.thinking}`;
 }
 function problems(list) {
     if (list.length === 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",
@@ -36,24 +36,29 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=18",
+    "bun": ">=1.4"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "tsc",
-    "bundle:skills": "node scripts/bundle-skills.mjs",
-    "test": "tsc && node --test test/*.test.mjs",
-    "prepublishOnly": "npm run build && npm test",
-    "mutation": "node scripts/mutation-check.mjs",
-    "prepare": "npm run build"
+    "bundle:skills": "bun scripts/bundle-skills.mjs",
+    "test": "tsc && bun test test/*.test.mjs",
+    "test:node": "tsc && node --test test/*.test.mjs",
+    "prepublishOnly": "bun run build && bun run test",
+    "mutation": "bun scripts/mutation-check.mjs",
+    "prepare": "bun run build"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.85.1"
   },
+  "dependencies": {
+    "@earendil-works/pi-tui": "0.85.1"
+  },
   "devDependencies": {
-    "@types/node": "^24",
+    "@types/node": "24.13.3",
     "typescript": "6"
   }
 }

package/skills/execute-phase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: execute-phase
 user-invocable: true
-version: 4.4.0
+version: 4.4.1
 argument-hint: <NN> [P<k>] | --fix <n> [P<k>] | [--max-attempts N] [--force]
 allowed-tools: [Bash, Read, Edit, Write, MultiEdit]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
@@ -115,8 +115,9 @@ use its fallback; never skip the workflow step.
 Planned by `plan-feature`/`plan-fix`; executes their SPEC. Explicit phases may
 hand off to `review-change` at layer/accumulation/sensitivity checkpoints and must
 at unit end. Unit-loop skips intermediate checkpoints and recommends the manual
-`/fold-findings` → re-run `/review-change` path after opening the PR; direct
-`review-change` remains the manual entry.
+`/review-change` → `/fold-findings` (only on `REVIEW-FAIL`) → re-run
+`/review-change` path after opening the PR; `review-change` remains the manual
+entry.
 Independent work stays a proposal. A finished unit always opens its PR and flips
 to `done`; `audit-pr` gates merge. Every invocation prints the next step.
 
@@ -127,5 +128,6 @@ to `done`; `audit-pr` gates merge. Every invocation prints the next step.
   committed on the correct branch with nothing bundled beyond scope.
 - `git status --porcelain` is empty and an open-PR branch has nothing unpushed.
 - A finished unit is `done`, has an opened PR (URL printed), and recommends the
-  mandatory `/fold-findings` → re-run `/review-change` hand-off, with `/audit-pr`
+  mandatory `/review-change` end review, then `/fold-findings` (only on
+  `REVIEW-FAIL`) and a re-run `/review-change`, with `/audit-pr`
   as the merge gate.

package/skills/execute-phase/references/BATCH_AND_PORTABILITY.md

@@ -9,7 +9,8 @@ The normal omitted-phase command is already the batch:
 
 It selects every unfinished phase, gates and commits each one, skips
 intermediate review stops, opens the PR, then recommends the manual
-`/fold-findings` → re-run `/review-change` path. An explicit `P<n>` keeps the
+`/review-change` → `/fold-findings` (only on `REVIEW-FAIL`) → re-run
+`/review-change` path. An explicit `P<n>` keeps the
 atomic/manual path.
 
 ### Fresh-context driver (recommended for cheap models)
@@ -20,8 +21,9 @@ slice, and compact receipts. An external driver may implement the same contract:
 
 1. Call `workflow-status` and choose the next unfinished phase.
 2. Invoke `/execute-phase <unit> P<n>` on the cheap tool-capable tier.
-3. Repeat `CONTINUE`; route `READY_FOR_REVIEW` to `/fold-findings`, then re-run
-   `/review-change`, on the required review/fold tiers.
+3. Repeat `CONTINUE`; route `READY_FOR_REVIEW` to `/review-change`, then
+   `/fold-findings` (only on `REVIEW-FAIL`), then re-run `/review-change`, on
+   the required review/fold tiers.
 4. Stop on `NEEDS_INPUT`, `HALT`, repeated unchanged evidence, or the declared
    attempt budget.
 

package/skills/execute-phase/references/CLOSEOUT.md

@@ -22,9 +22,10 @@ Write `docs/features/<NN>-<slug>/CHECKLIST.md`: schema migration applied (if any
 ## Review checkpoint & finishing a unit
 
 **Independent final review is mandatory — every unit gets one before merge.**
-Recommend the manual `/fold-findings` → re-run `/review-change` path because it
-preserves fresh review contexts while handling bounded corrections; direct
-`review-change` remains the manual entry. Review
+Recommend the mandatory `/review-change` → `/fold-findings` (only on
+`REVIEW-FAIL`) → re-run `/review-change` path because it preserves fresh review
+contexts while handling bounded corrections; direct `review-change` remains the
+manual entry. Review
 runs in its own turn (hand-off, not composed): a skill's model and
 effort are fixed at turn start, so invoking `review-change` from here would run it at
 execute-phase's `sonnet`/`medium` rather than its own `opus`/`high` — under-powering
@@ -46,7 +47,8 @@ one).
 **Finishing a unit (single-pass, `--fix`, or a feature's final phase): the last step
 is always an open PR.** Mark the unit `done`, commit the flip, push, and `gh pr create`
 (see the mode steps above) — regardless of the review/audit still to come. Then hand
-off to `/fold-findings`, then re-run `/review-change`, which feeds `audit-pr`
+off to `/review-change` (the mandatory end review) → `/fold-findings` (only
+on `REVIEW-FAIL`) → re-run `/review-change`, which feeds `audit-pr`
 (the merge gate).
 
 **Adversarial pass at that mandatory end review.** `review-change` evaluates its

package/skills/execute-phase/references/FOLDING.md

@@ -41,7 +41,8 @@ Final-phase / single-pass / fix hand-off:
 <unit> implemented, gate green, marked done.
 PR opened: <FULL PR URL — always printed here; not every agent shows open PRs>
 Roadmap/fix-index row: done · #<n> (linked and pushed)
-→ Next: /fold-findings, then re-run /review-change (unresolved findings go to triage/replan)
+→ Next: /review-change on the changed HEAD (the mandatory end review)
+  · REVIEW-FAIL → /fold-findings (only on a REVIEW-FAIL), then re-run /review-change (unresolved findings go to triage/replan)
   · clean    → /audit-pr (merge gate) → human merges
   · findings → fold fix-now into this PR; independent work remains a proposal until user triage; re-review
   · docs site declared (documentation map has a `Docs site` block) →

package/skills/execute-phase/references/UNIT_LOOP.md

@@ -82,6 +82,7 @@ UNIT LOOP — <unit> COMPLETE
 Phases: <n> · Commits: <sha list> · Acceptance: <blob> · Gate: PASS
 PR: <url>
 
-→ Next: /fold-findings, then re-run /review-change on the changed HEAD — triage or replan unresolved findings
+→ Next: /review-change on the changed HEAD — the mandatory end review (fold-findings only after a REVIEW-FAIL)
+  · findings → /fold-findings (only on a REVIEW-FAIL), then re-run /review-change — triage or replan unresolved findings
   · merge gate after REVIEW-PASS → /audit-pr
 ```

package/skills/pre-execution-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pre-execution-review
 user-invocable: false
-version: 2.2.0
+version: 2.2.1
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >

package/skills/pre-execution-review/references/LEDGERS.md

@@ -130,17 +130,20 @@ durable ledger its row does not name it for. Cells carry bare values: ` · ` joi
 ledgers, ` + ` joins owners, an owner is `<skill>:<column-set>` (the literal
 `human-owner` marks the person, the only authority for an amendment), and a `#`
 line is a directive. A script that writes only generated artifacts names no ledger
-and is out of scope; a copy or shell rewrite stays the reviewer's job.
+and is out of scope; a copy or shell rewrite stays the reviewer's job. Validator
+commands follow the repository's runtime convention: **bun first** (`bun test …`),
+with the same command under `node --test …` when bun is absent — both runtimes
+must pass; the CI node-compat job enforces the fallback.
 
 ```text
 ledger-ownership@1
 truth-class | ledger | owner | annotator | annotator-token | validator
-review-findings | docs/features/<NN>-<slug>/review-findings.md · docs/fix/<issue>-<topic>/review-findings.md | review-change:finding-rows + review-change:finding-mark + review-change:review-mark + audit-pr:audit-rows + triage-issue:triage-rows + fold-findings:folded-flag | scripts/ledger-provenance.mjs | · fold <sha> + · ticked <sha> + · REOPENED | node --test scripts/ledger-provenance.test.mjs
-planning-findings | docs/features/<NN>-<slug>/planning-findings.md · docs/fix/<issue>-<topic>/planning-findings.md | review-spec:spec-stage-rows + review-plan:plan-stage-rows + design-feature:product-class-resolutions + plan-feature:plan-class-resolutions + plan-fix:fix-plan-class-resolutions + fold-findings:source-class-resolutions | none | none | node --test scripts/pre-execution-quality.test.mjs
-progress | docs/features/<NN>-<slug>/progress.md · docs/fix/<issue>-<topic>/progress.md | plan-feature-scaffold:create + execute-phase:phase-entries + execute-phase:gate-rejection-traces + review-spec:product-receipt + review-plan:plan-receipt | none | none | node --test scripts/pre-execution-sensor.test.mjs
-known-issues | docs/features/<NN>-<slug>/known-issues.md · docs/fix/<issue>-<topic>/known-issues.md | plan-feature-scaffold:create + execute-phase:blocker-entries-and-status | none | none | node --test scripts/ledger-ownership.test.mjs
-decisions | docs/features/<NN>-<slug>/decisions.md · docs/fix/<issue>-<topic>/decisions.md | plan-feature-scaffold:create + design-feature:product-decisions + plan-feature:engineering-decisions + execute-phase:phase-decisions + human-owner:ratified-verdicts | none | none | node --test scripts/ledger-ownership.test.mjs
-roadmap | docs/features/ROADMAP.md · docs/fix/README.md | design-feature:idea-or-defined-row + plan-feature-scaffold:planned-row + plan-fix:fix-index-row + execute-phase:status-and-pr-link + ship-roadmap:founding-and-flip + audit-docs:low-risk-row-repair | none | none | node --test scripts/bounded-delivery-loops.test.mjs
+review-findings | docs/features/<NN>-<slug>/review-findings.md · docs/fix/<issue>-<topic>/review-findings.md | review-change:finding-rows + review-change:finding-mark + review-change:review-mark + audit-pr:audit-rows + triage-issue:triage-rows + fold-findings:folded-flag | scripts/ledger-provenance.mjs | · fold <sha> + · ticked <sha> + · REOPENED | bun test scripts/ledger-provenance.test.mjs
+planning-findings | docs/features/<NN>-<slug>/planning-findings.md · docs/fix/<issue>-<topic>/planning-findings.md | review-spec:spec-stage-rows + review-plan:plan-stage-rows + design-feature:product-class-resolutions + plan-feature:plan-class-resolutions + plan-fix:fix-plan-class-resolutions + fold-findings:source-class-resolutions | none | none | bun test scripts/pre-execution-quality.test.mjs
+progress | docs/features/<NN>-<slug>/progress.md · docs/fix/<issue>-<topic>/progress.md | plan-feature-scaffold:create + execute-phase:phase-entries + execute-phase:gate-rejection-traces + review-spec:product-receipt + review-plan:plan-receipt | none | none | bun test scripts/pre-execution-sensor.test.mjs
+known-issues | docs/features/<NN>-<slug>/known-issues.md · docs/fix/<issue>-<topic>/known-issues.md | plan-feature-scaffold:create + execute-phase:blocker-entries-and-status | none | none | bun test scripts/ledger-ownership.test.mjs
+decisions | docs/features/<NN>-<slug>/decisions.md · docs/fix/<issue>-<topic>/decisions.md | plan-feature-scaffold:create + design-feature:product-decisions + plan-feature:engineering-decisions + execute-phase:phase-decisions + human-owner:ratified-verdicts | none | none | bun test scripts/ledger-ownership.test.mjs
+roadmap | docs/features/ROADMAP.md · docs/fix/README.md | design-feature:idea-or-defined-row + plan-feature-scaffold:planned-row + plan-fix:fix-index-row + execute-phase:status-and-pr-link + ship-roadmap:founding-and-flip + audit-docs:low-risk-row-repair | none | none | bun test scripts/bounded-delivery-loops.test.mjs
 acceptance-manifest | docs/features/<NN>-<slug>/ACCEPTANCE.md · docs/fix/<issue>-<topic>/ACCEPTANCE.md | plan-feature-scaffold:feature-freeze + plan-fix:fix-freeze + human-owner:approved-amendment | none | none | git hash-object docs/features/<NN>-<slug>/ACCEPTANCE.md
 # no-script-writer: SPEC.md · PLAN.md · TASKS.md · CHECKLIST.md · testing.md · architecture-notes.md · planning-evidence.md · planning-obligations.md · delegated-evidence.md
 ```