@gtrabanco/pi-agentic-workflow 0.9.0 → 0.9.2

package/README.es.md

@@ -164,7 +164,11 @@ byte a byte idéntico; el campo de modelo puede construir una cadena de respaldo
 ordenada (`a/m1 → b/m2`); y una sola pasada puede aplicar o limpiar una ruta en
 varios comandos, avisando por comando cuando una referencia falta del registro
 vivo. Fuera de una sesión TUI los selectores caen a un prompt simple, así que la
-consola nunca se queda sin salida.
+consola nunca se queda sin salida. Las listas de más de 24 opciones tampoco
+llegan nunca a un solo diálogo: por encima del tope el selector de modelo
+pregunta primero el proveedor, y una lista de proveedores o de modelos
+demasiado larga pagina (`More options…` / `◀ Previous page`) en vez de tumbar
+el diálogo de select del host.
 
 ## Diagnóstico
 

package/README.md

@@ -158,7 +158,11 @@ you are, and the value currently in force is pre-selected and labelled
 model field can build an ordered fallback chain (`a/m1 → b/m2`); and one pass
 can apply or clear a route across several commands, warning per command when a
 reference is missing from the live registry. Outside a TUI session the pickers
-fall back to a plain prompt, so the console never dead-ends.
+fall back to a plain prompt, so the console never dead-ends. Lists longer than
+24 options never reach a single dialog either: over the cap the model picker
+asks for the provider first, and an overlong provider or model list pages
+(`More options…` / `◀ Previous page`) instead of crashing the host's select
+dialog.
 
 ## Troubleshooting
 

package/dist/extension/index.d.ts

@@ -1,4 +1,13 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SettingsUi } from "../routing/types.js";
 import { SETTINGS_COMMAND } from "../routing/types.js";
+/**
+ * The interactive slice the settings console sees: Pi's own `ui` plus the rich
+ * picker (P4). The picker is terminal-only, so a non-TUI mode (headless/RPC)
+ * gets the plain `select` path — the console never dead-ends (OB-12, PE-004).
+ * Exported as a test seam: the fallback's bounded paging (AC8) is exercised
+ * directly, without standing up the whole extension.
+ */
+export declare function richUi(ctx: ExtensionContext): SettingsUi;
 export default function extension(pi: ExtensionAPI): void;
 export { SETTINGS_COMMAND };

package/dist/extension/index.js

@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "../config/load.js";
 import { createExtension } from "./factory.js";
-import { createPickerComponent, PICKER_MAX_VISIBLE } from "../settings/picker.js";
+import { createPickerComponent, PICKER_MAX_VISIBLE, pagedSelect } from "../settings/picker.js";
 import { createHintStore, stateFilePath } from "../routing/state.js";
 import { runSettingsConsole } from "../settings/console.js";
 import { readConfigFile, writeConfigFile } from "../settings/store.js";
@@ -25,8 +25,10 @@ const thinkingLevelsInSyncWithPi = true;
  * The interactive slice the settings console sees: Pi's own `ui` plus the rich
  * picker (P4). The picker is terminal-only, so a non-TUI mode (headless/RPC)
  * gets the plain `select` path — the console never dead-ends (OB-12, PE-004).
+ * Exported as a test seam: the fallback's bounded paging (AC8) is exercised
+ * directly, without standing up the whole extension.
  */
-function richUi(ctx) {
+export function richUi(ctx) {
     const base = ctx.ui;
     return {
         select: (title, options) => base.select(title, [...options]),
@@ -35,7 +37,10 @@ function richUi(ctx) {
         notify: (message, kind) => base.notify(message, kind),
         pick: async (title, options, opts = {}) => {
             if (ctx.mode !== "tui") {
-                const picked = await base.select(title, [...options]);
+                // Non-TUI: the host's `select` dialog carries the same 24-option cap, so
+                // an over-cap list pages instead of crashing `pick` (AC8, PE-002). A
+                // list within the cap is one call with the same options, in order.
+                const picked = await pagedSelect((selectTitle, selectOptions) => base.select(selectTitle, [...selectOptions]), title, [...options]);
                 if (opts.multiple)
                     return picked ? [picked] : undefined;
                 return picked;
@@ -53,6 +58,7 @@ function richUi(ctx) {
                     items,
                     maxVisible: PICKER_MAX_VISIBLE,
                     theme: selectListTheme,
+                    initial: opts.initial,
                     onSelect: (value) => done(value),
                     onCancel: () => done(undefined),
                 });

package/dist/settings/console.d.ts

@@ -55,6 +55,7 @@ export declare const prompts: {
     readonly cancel: "Cancel";
     readonly model: (target: string) => string;
     readonly modelPicked: (target: string) => string;
+    readonly modelProvider: (target: string) => string;
     readonly thinking: (target: string) => string;
     readonly fields: "Which fields should change?";
     readonly fieldsBoth: "model and thinking";

package/dist/settings/console.js

@@ -12,6 +12,7 @@ import { effectiveRoute } from "../config/merge.js";
 import { parseConfigFile, parseModelReference } from "../config/schema.js";
 import { MAX_MODEL_CHAIN, SETTLE_POLICIES, THINKING_LEVELS, UNAVAILABLE_ROUTE_POLICIES } from "../config/types.js";
 import { renderMergedConfig, routePath, DEFAULT_ROUTE } from "./view.js";
+import { SELECT_OPTION_LIMIT, pagedSelect, providerOf } from "./picker.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
  * silently re-sequencing them. */
@@ -38,6 +39,7 @@ export const prompts = {
     cancel: "Cancel",
     model: (target) => `Model for ${target}?`,
     modelPicked: (target) => `Which model for ${target}?`,
+    modelProvider: (target) => `Provider for ${target}?`,
     thinking: (target) => `Thinking level for ${target}?`,
     fields: "Which fields should change?",
     fieldsBoth: "model and thinking",
@@ -225,18 +227,25 @@ async function askFields(deps) {
 }
 /** Ask for one model entry; `undefined` means cancelled/skipped, `"inherit"` means the whole-route setting. */
 async function pickModelEntry(deps, target, current) {
+    const models = deps.models ?? [];
     let answer;
-    if (typeof deps.ui.pick === "function" && deps.models && deps.models.length > 0) {
+    if (models.length > SELECT_OPTION_LIMIT - 1) {
+        // Over the cap: TYPED occupies one dialog slot, so 24 models + TYPED would
+        // still crash (Decision 1). The issue's provider-first two-step keeps every
+        // dialog bounded in every UI mode (Decision 3).
+        answer = await askModelOverCap(deps, target, models, current);
+    }
+    else if (typeof deps.ui.pick === "function" && 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], {
+        const picked = await deps.ui.pick(prompts.modelPicked(target), [...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]);
+    else if (models.length > 0) {
+        answer = await deps.ui.select(prompts.modelPicked(target), [...models, TYPED]);
         if (answer === TYPED || answer === undefined)
             answer = await deps.ui.input(prompts.model(target), "provider/modelId or inherit");
     }
@@ -257,6 +266,60 @@ async function pickModelEntry(deps, target, current) {
     }
     return `${parts.provider}/${parts.id}`;
 }
+/**
+ * The provider-first two-step the issue prescribes when the live registry exceeds
+ * the single-dialog cap (PE-003, PE-014). Unique providers (prefix before the
+ * first `/`, `localeCompare`-sorted) come first — through the rich picker while
+ * it fits, `pagedSelect` otherwise — then that provider's models in registry
+ * order. "Type another reference…" is the trailing entry of every dialog and
+ * still reaches the text input, so a pick-less UI completes the flow (OB-12).
+ */
+async function askModelOverCap(deps, target, models, current) {
+    const currentProvider = typeof current === "string" ? providerOf(current) : undefined;
+    const providers = [...new Set(models.map((model) => providerOf(model)))].sort((a, b) => a.localeCompare(b));
+    const provider = await askProvider(deps, target, providers, currentProvider);
+    if (provider === TYPED || provider === undefined) {
+        return await deps.ui.input(prompts.model(target), "provider/modelId or inherit");
+    }
+    const providerModels = models.filter((model) => providerOf(model) === provider);
+    const picked = await askModelWithinProvider(deps, target, providerModels, provider, current);
+    if (picked === TYPED || picked === undefined) {
+        return await deps.ui.input(prompts.model(target), "provider/modelId or inherit");
+    }
+    return picked;
+}
+/**
+ * Ask which provider. The rich picker handles it while `providers + TYPED` fits
+ * the cap (preselected to the value in force's provider); over the cap — Pi
+ * imposes no provider ceiling, so a > 24-provider registry is real (PE-014) —
+ * the dialog pages instead of crashing.
+ */
+async function askProvider(deps, target, providers, currentProvider) {
+    const title = prompts.modelProvider(target);
+    if (typeof deps.ui.pick === "function" && providers.length + 1 <= SELECT_OPTION_LIMIT) {
+        const picked = await deps.ui.pick(title, [...providers, TYPED], {
+            ...(currentProvider !== undefined ? { initial: currentProvider } : {}),
+        });
+        return typeof picked === "string" ? picked : undefined;
+    }
+    return pagedSelect((selectTitle, options) => deps.ui.select(selectTitle, options), title, providers, { trailing: TYPED });
+}
+/**
+ * Ask the model within one provider. The rich picker handles it while `models +
+ * TYPED` fits the cap (preselected only when the value in force belongs to this
+ * provider); over the cap the dialog pages.
+ */
+async function askModelWithinProvider(deps, target, models, provider, current) {
+    const title = prompts.modelPicked(target);
+    if (typeof deps.ui.pick === "function" && models.length + 1 <= SELECT_OPTION_LIMIT) {
+        const initial = typeof current === "string" && providerOf(current) === provider ? current : undefined;
+        const picked = await deps.ui.pick(title, [...models, TYPED], {
+            ...(initial !== undefined ? { initial } : {}),
+        });
+        return typeof picked === "string" ? picked : undefined;
+    }
+    return pagedSelect((selectTitle, options) => deps.ui.select(selectTitle, options), title, models, { trailing: TYPED });
+}
 /** 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
@@ -334,7 +397,8 @@ async function pickCommand(deps, options) {
         deps.ui.notify("There is no command to pick here.", "warning");
         return undefined;
     }
-    return deps.ui.select(prompts.command, [...options].sort((a, b) => a.localeCompare(b)));
+    const sorted = [...options].sort((a, b) => a.localeCompare(b));
+    return pagedSelect((title, list) => deps.ui.select(title, list), prompts.command, sorted);
 }
 /** 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) {
@@ -355,7 +419,7 @@ async function pickCommandsMulti(deps, options) {
         const remaining = sorted.filter((option) => !chosen.includes(option));
         if (remaining.length === 0)
             break;
-        const picked = await deps.ui.select(prompts.command, remaining);
+        const picked = await pagedSelect((title, list) => deps.ui.select(title, list), prompts.command, remaining);
         if (picked === undefined)
             break;
         chosen.push(picked);

package/dist/settings/picker.d.ts

@@ -1,6 +1,51 @@
 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;
+/**
+ * The host dialog cap this package must never exceed (PE-001): pi-web rejects a
+ * `select` dialog offering more than 24 options with "A select dialog must not
+ * offer more than 24 options". It is the single knob if a future host enforces a
+ * different bound.
+ */
+export declare const SELECT_OPTION_LIMIT = 24;
+/** Pager entry offered on every page but the first. */
+export declare const PAGED_SELECT_PREV = "\u25C0 Previous page";
+/** Pager entry offered on every page but the last. */
+export declare const PAGED_SELECT_NEXT = "More options\u2026";
+/** The plain-dialog shape `pagedSelect` drives (Pi's `ctx.ui.select`). */
+export type SelectFn = (title: string, options: readonly string[]) => string | undefined | Promise<string | undefined>;
+/**
+ * Present `options` through `select` without ever offering more than
+ * `SELECT_OPTION_LIMIT` entries in one dialog (AC6, PE-001, PE-012).
+ *
+ * - A list that fits — data plus `trailing` — opens exactly one dialog, in the
+ *   caller's order with `trailing` last, so a ≤ cap flow is byte-identical to a
+ *   plain `select` call.
+ * - A longer list pages `PAGED_SELECT_PAGE_SIZE` data entries at a time —
+ *   `SELECT_OPTION_LIMIT - 3`, so the derived page never hardcodes the cap —
+ *   appending `PAGED_SELECT_PREV` and/or `PAGED_SELECT_NEXT` before `trailing`.
+ *   Pager entries navigate; `trailing` and data entries are returned to the
+ *   caller; `undefined` (cancel) passes straight through.
+ *
+ * The two pager labels are reserved: a data value (or a `trailing` value) that
+ * spells one is indistinguishable from the pager entry in the string `select`
+ * answers with, so a colliding pager label is decorated until it names nothing
+ * else on the dialog — the data value stays selectable and so does the pager.
+ */
+export declare function pagedSelect(select: SelectFn, title: string, options: readonly string[], { trailing }?: {
+    trailing?: string;
+}): Promise<string | undefined>;
+/**
+ * The provider prefix Pi resolves a reference by — everything before the first
+ * `/` (SPEC Decision 6).
+ *
+ * Lenient on purpose, and deliberately distinct from the strict
+ * `parseModelReference` in `../config/schema.js`, which validates and rejects:
+ * this split must answer for any registry string. Both the console's
+ * provider-first grouping and the slash-aware filter below take their provider
+ * from here, so the two settings-side consumers cannot drift apart.
+ */
+export declare function providerOf(reference: string): string;
 /**
  * Token/subsequence, slash-aware reference filter (OB-2).
  *
@@ -19,11 +64,16 @@ export declare function filterReferences(query: string, refs: readonly string[])
  * `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.
+ *
+ * `initial` — the value in force — is selected in the window the picker opens
+ * with, through the SelectList's own `setSelectedIndex` (OB-3).
  */
 export declare function createPickerComponent(options: {
     items: readonly SelectItem[];
     maxVisible: number;
     theme: SelectListTheme;
+    /** The value in force, selected in the window the picker opens with (OB-3). */
+    initial?: string;
     onSelect: (value: string) => void;
     onCancel?: () => void;
 }): Component & {

package/dist/settings/picker.js

@@ -10,6 +10,10 @@
 //    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.
+//  - `pagedSelect` is the plain-`select` counterpart: the host's dialog cap
+//    (pi-web rejects > 24 options, PE-001) is never a picker concern — a UI
+//    without the rich seam still gets a bounded dialog, and an over-cap list
+//    pages instead of crashing.
 //
 // The filter is implemented in this package (not imported from Pi): PE-004
 // confirmed pi-coding-agent's `fuzzyFilter` is internal, so the same
@@ -17,6 +21,99 @@
 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;
+/**
+ * The host dialog cap this package must never exceed (PE-001): pi-web rejects a
+ * `select` dialog offering more than 24 options with "A select dialog must not
+ * offer more than 24 options". It is the single knob if a future host enforces a
+ * different bound.
+ */
+export const SELECT_OPTION_LIMIT = 24;
+/** Pager entry offered on every page but the first. */
+export const PAGED_SELECT_PREV = "◀ Previous page";
+/** Pager entry offered on every page but the last. */
+export const PAGED_SELECT_NEXT = "More options…";
+/**
+ * Data entries per page: `SELECT_OPTION_LIMIT - 3` — room inside one dialog for
+ * both pager entries and the caller's trailing option.
+ */
+const PAGED_SELECT_PAGE_SIZE = SELECT_OPTION_LIMIT - 3;
+/**
+ * The pager label actually offered: `base`, decorated with `marker` while some
+ * value in the dialog spells it, so a label-colliding data entry can never be
+ * swallowed by the navigation guard (see the contract above).
+ */
+function pagerLabel(base, marker, spoken) {
+    let label = base;
+    while (spoken.includes(label))
+        label += marker;
+    return label;
+}
+/**
+ * Present `options` through `select` without ever offering more than
+ * `SELECT_OPTION_LIMIT` entries in one dialog (AC6, PE-001, PE-012).
+ *
+ * - A list that fits — data plus `trailing` — opens exactly one dialog, in the
+ *   caller's order with `trailing` last, so a ≤ cap flow is byte-identical to a
+ *   plain `select` call.
+ * - A longer list pages `PAGED_SELECT_PAGE_SIZE` data entries at a time —
+ *   `SELECT_OPTION_LIMIT - 3`, so the derived page never hardcodes the cap —
+ *   appending `PAGED_SELECT_PREV` and/or `PAGED_SELECT_NEXT` before `trailing`.
+ *   Pager entries navigate; `trailing` and data entries are returned to the
+ *   caller; `undefined` (cancel) passes straight through.
+ *
+ * The two pager labels are reserved: a data value (or a `trailing` value) that
+ * spells one is indistinguishable from the pager entry in the string `select`
+ * answers with, so a colliding pager label is decorated until it names nothing
+ * else on the dialog — the data value stays selectable and so does the pager.
+ */
+export async function pagedSelect(select, title, options, { trailing } = {}) {
+    const items = [...options];
+    if (items.length + (trailing !== undefined ? 1 : 0) <= SELECT_OPTION_LIMIT) {
+        return await select(title, trailing !== undefined ? [...items, trailing] : items);
+    }
+    // A label-colliding data value must stay reachable, so compute the offered
+    // pager labels once against every string that can appear in a dialog.
+    const spoken = trailing !== undefined ? [...items, trailing] : items;
+    const prevLabel = pagerLabel(PAGED_SELECT_PREV, " ‹", spoken);
+    const nextLabel = pagerLabel(PAGED_SELECT_NEXT, " ›", spoken);
+    const pageCount = Math.ceil(items.length / PAGED_SELECT_PAGE_SIZE);
+    let page = 0;
+    for (;;) {
+        const start = page * PAGED_SELECT_PAGE_SIZE;
+        const entries = [
+            ...items.slice(start, start + PAGED_SELECT_PAGE_SIZE),
+            ...(page > 0 ? [prevLabel] : []),
+            ...(page < pageCount - 1 ? [nextLabel] : []),
+            ...(trailing !== undefined ? [trailing] : []),
+        ];
+        const answer = await select(title, entries);
+        if (answer === undefined)
+            return undefined;
+        if (answer === nextLabel && page < pageCount - 1) {
+            page += 1;
+            continue;
+        }
+        if (answer === prevLabel && page > 0) {
+            page -= 1;
+            continue;
+        }
+        return answer;
+    }
+}
+/**
+ * The provider prefix Pi resolves a reference by — everything before the first
+ * `/` (SPEC Decision 6).
+ *
+ * Lenient on purpose, and deliberately distinct from the strict
+ * `parseModelReference` in `../config/schema.js`, which validates and rejects:
+ * this split must answer for any registry string. Both the console's
+ * provider-first grouping and the slash-aware filter below take their provider
+ * from here, so the two settings-side consumers cannot drift apart.
+ */
+export function providerOf(reference) {
+    const slash = reference.indexOf("/");
+    return slash === -1 ? reference : reference.slice(0, slash);
+}
 /**
  * Token/subsequence, slash-aware reference filter (OB-2).
  *
@@ -41,7 +138,7 @@ function matchesToken(token, ref) {
         const provider = token.slice(0, -1);
         if (provider === "")
             return true;
-        const refProvider = ref.split("/")[0] ?? "";
+        const refProvider = providerOf(ref);
         return refProvider.startsWith(provider);
     }
     return isSubsequence(token, ref);
@@ -60,14 +157,27 @@ function isSubsequence(needle, haystack) {
  * `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.
+ *
+ * `initial` — the value in force — is selected in the window the picker opens
+ * with, through the SelectList's own `setSelectedIndex` (OB-3).
  */
 export function createPickerComponent(options) {
-    const { items, maxVisible, theme, onSelect, onCancel } = options;
+    const { items, maxVisible, theme, initial, onSelect, onCancel } = options;
     let filterText = "";
+    let openSelectionApplied = false;
     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);
+        // Preselection is an open-time concern (OB-3): the value in force applies to
+        // the first window only, so narrowing afterwards keeps the narrowed window's
+        // own first match instead of yanking the selection to a filtered-out value.
+        if (!openSelectionApplied) {
+            openSelectionApplied = true;
+            const index = initial === undefined ? -1 : visible.findIndex((item) => item.value === initial);
+            if (index > 0)
+                list.setSelectedIndex(index); // index 0 is already the SelectList default
+        }
         list.onSelect = (item) => onSelect(item.value);
         list.onCancel = onCancel;
         return list;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",

package/skills/workflow-status/SKILL.md

@@ -1,62 +1,52 @@
 ---
 name: workflow-status
 user-invocable: true
-version: 3.2.1
+version: 3.4.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 argument-hint: "[--json-only] [--last-envelope <json|path>]"
 description: >
-  Read-only workflow sensor: compute repository, roadmap, dependency, PR,
-  finding, and recovery state, then emit the fixed machine envelope. Never
-  edits. Triggers: "workflow-status", "workflow status", "what can I build
-  next", "state of the run".
+  Read-only workflow sensor: run the deterministic script, read the fixed
+  machine envelope, interpret the recommendation. Never edits. Triggers:
+  "workflow-status", "workflow status", "what can I build next".
 ---
 
 # Workflow Status (the orchestrator's sensor)
 
-One read-only pass over the project that answers, in a single fixed JSON
-envelope: **what exists, what is blocked on what, what is startable right now,
-and what the recommended next command is.** Built for external orchestrators
-(see `docs/workflow/ORCHESTRATION.md`) but equally useful to a human asking
-"where do we stand?".
+One read-only pass that answers, in a single fixed JSON envelope: **what exists,
+what is blocked on what, what is startable right now, and what the recommended
+next command is.** The **script is the deterministic producer**:
+`scripts/workflow-status.mjs` executes the published `SENSOR_CORE` sequence
+(steps 1–9 including 6a) and prints the envelope. This skill runs the script,
+reads the JSON, interprets it against the references below, and prints the human
+report — it never assembles the envelope by hand.
 
 ## Turn contract — verify before ending the turn
 
 ```
-✓ Every claim comes from a RUN command or a READ file (git/forge output, roadmap,
-  fix index, feature folders) — nothing inferred from memory
+✓ The script was RUN — `bun scripts/workflow-status.mjs [--json-only]
+  [--last-envelope <json|path>]` (node is the fallback when bun is absent, per
+  the repository's runtime convention); the envelope is the script's stdout, never
+  assembled by the model
 ✓ Nothing was edited, committed, pushed, or created — read-only, always
 ✓ `next.recommended` is non-bare (carries the unit's slug/NN, never a bare
-  `/plan-feature`) AND staged by the target unit's resolved status **and** its
-  current pre-execution evidence: `idea`/undesigned → `/design-feature <slug>`;
-  `defined` → `/plan-feature <slug>` only on a current `SPEC-REVIEW-PASS`, else
-  `/review-spec <slug>`; `planned`/`in-progress` → `/execute-phase <NN>` only on a
+  `/plan-feature`) AND the script computed it from the unit's resolved status
+  **and** its current pre-execution evidence: `idea`/undesigned →
+  `/design-feature <slug>`; `defined` → `/plan-feature <slug>` only on a current
+  `SPEC-REVIEW-PASS`, else `/review-spec <slug>`; `planned`/`in-progress` → `/execute-phase <NN>` only on a
   current `PLAN-REVIEW-PASS`, else `/review-plan <NN>` (step 6a)
-✓ A missing or non-frozen repository-state ledger emits a machine-readable
-  substrate blocker and routes to discovery or resolution before any unit is
-  listed as startable
-✓ Every `detail.design_candidates[].next` begins with `/design-feature ` — design
-  candidates always route to design, regardless of anything else
-✓ When `--last-envelope` is supplied: the no-progress guard ran (crash-recovery
-  checklist) — a hint that recommended `/plan-feature`/`/design-feature` for a
-  unit still at its pre-advance status produces a `workflow_observations` note,
-  never a silently repeated bland recommendation
-✓ `recommendations.product_audit` was computed by the step-16 mechanical
-  two-condition check (never guessed), and `next.tier` was derived from the
-  resolved `next.recommended` command via the command→tier map in
-  `## Machine envelope` (never guessed)
-✓ Per-unit `review`/`closure`/`issues_born` (steps 10–12) were computed per
-  their fixed rules — `adversarial.ran`/`n` stayed `null` unless real
-  evidence exists, never guessed — and any fired `next.suggested[]` entries
-  (step 13) quote their owning skill's condition verbatim, never a second
-  copy of the trigger logic
-✓ The envelope is emitted on **every** invocation of this skill, including a
-  same-session natural-language follow-up about state — never replaced by prose
-✓ The emitted envelope was checked against the shape reminders in
-  `## Machine envelope` (mirroring
-  `packages/agentic-workflow-schema/envelope.schema.json`) before printing
-✓ The human-readable summary is printed, then the machine envelope (fenced
-  ```json — see ## Machine envelope) is the ABSOLUTE last output
+✓ `detail.crash_recovery` carries a verdict from the decision table and the
+  envelope `state` matches it (CLEAN→OK, RESUMABLE→CONTINUE,
+  AMBIGUOUS→NEEDS_INPUT)
+✓ Every `detail.design_candidates[].next` begins with `/design-feature `
+✓ Every degraded dimension is named in `detail.degradations` as
+  `unavailable-<source>-<cause>` — and, when `--last-envelope` was supplied, the
+  no-progress guard's `workflow_observations` note is present (never a silently
+  repeated bland recommendation)
+✓ The envelope is emitted on **every** invocation, including a same-session
+  natural-language follow-up about state — never replaced by prose
+✓ The human-readable summary is printed, then the machine envelope (the script's
+  JSON) is the ABSOLUTE last output
 ```
 
 With `--json-only`, skip the human-readable summary: print the envelope alone.
@@ -66,43 +56,35 @@ With `--json-only`, skip the human-readable summary: print the envelope alone.
 - Between orchestration steps: an external driver runs it to decide the next
   command and model tier without parsing prose.
 - Before picking work manually: "what can I start right now?"
-- **Not** for judging quality (that's `review-change`/`audit-pr`) or product
-  health (that's `product-audit`) — this skill reports state, it never judges.
+- **Not** for judging quality (`review-change`/`audit-pr`) or product health
+  (`product-audit`) — this skill reports state, it never judges.
 
 ## Step 0 — Discover the project (always first)
 
-Per the agent guide's **Workflow conventions** + **documentation map**, then
-read what THIS skill needs: `docs/features/ROADMAP.md`, the fix index
-(`docs/fix/README.md`), every in-flight feature folder's `TASKS.md` +
-`progress.md` + `known-issues.md`, and `docs/features/SHIP_DECISIONS.md` if a
-ship-roadmap run exists.
-
+Per the agent guide's **Workflow conventions** + **documentation map**. The
+script reads what THIS skill needs (`docs/features/ROADMAP.md`, the fix index
+`docs/fix/README.md`, every in-flight feature folder's `TASKS.md` +
+`progress.md` + `review-findings.md`, and `docs/workflow/REPOSITORY_STATE.md`);
+read them yourself only to interpret a field the script emitted.
 
 ## Progressive loading — fixed sensor route
 
 The reference allowlist is exactly the seven linked paths below. Never invent or
-read another `references/` path. This skill is a read-only sensor. Every
-invocation loads this baseline in order:
+read another `references/` path. This skill is a read-only sensor.
 
-1. [sensor core](references/SENSOR_CORE.md)
+1. [sensor core](references/SENSOR_CORE.md) — the sequence the script executes
 2. [crash recovery](references/CRASH_RECOVERY.md)
 3. [envelope core](references/ENVELOPE_CORE.md)
 4. [envelope fields](references/ENVELOPE_FIELDS.md)
 5. [pre-execution evidence](references/PRE_EXECUTION.md)
 6. [guardrails](references/GUARDRAILS.md)
 
-Add [pre-execution evidence](references/PRE_EXECUTION.md) whenever a unit is
-`defined`, `planned` or `in-progress` — it defines step 6a (receipt sensing, the
-one-label-per-stage table, and the legacy-adoption route).
 Add [sensor signals](references/SENSOR_SIGNALS.md) only when a unit, issue,
 finding, or recommendation exists; an empty project skips that file but still
 emits the empty shapes defined by envelope fields. Add
 [portability](references/PORTABILITY.md) only when the platform actually lacks a
 named primitive. `--json-only` does not skip any baseline file.
 
-All resources are one hop from this file. Missing required detail means
-`BLOCKED`; do not fabricate a partial envelope.
-
 ## Portability
 
 The sensor uses repository and forge commands only. When a named agent feature
@@ -122,28 +104,21 @@ the JSON contract.
 
 ## Done when
 
-- Every roadmap/fix row, open PR, and in-flight folder was actually read, the
-  dependency closures are computed transitively, and inconsistencies are
-  reported (never repaired).
-- The `CRASH RECOVERY` sub-block was printed with a verdict from the decision
-  table, and the envelope `state` matches it (CLEAN→OK, RESUMABLE→CONTINUE,
-  AMBIGUOUS→NEEDS_INPUT).
+- The script ran and every claim in the report comes from its envelope — nothing
+  inferred from memory, nothing assembled by hand.
+- `detail.design_candidates`, `detail.features`, `detail.fixes`,
+  `detail.startable_now`, `detail.blocked_units`, `detail.open_prs`,
+  `detail.untriaged_issues`, `detail.urgent`, `detail.degradations`, and
+  `detail.crash_recovery` were read from the envelope, and the envelope `state`
+  matches the crash-recovery verdict.
 - With `--last-envelope` supplied: the no-progress guard ran — a stalled
   `/plan-feature`/`/design-feature` hint surfaces as a `workflow_observations`
   note, never a silent bland repeat, with no new write path introduced.
-- The human summary (unless `--json-only`) and the envelope — with
-  `detail` carrying design_candidates, features, fixes, startable_now,
-  blocked_units, open_prs, pending_triage, `untriaged_issues`
-  (count + oldest_open) and `urgent` (labels-only issue list +
-  interruptibility facts) — are printed, envelope last.
-- Each `detail.features[]`/`detail.fixes[]` entry additionally carries
-  `review`, `closure`, and `issues_born` (steps 10–12) — `detail`-scoped, no
-  schema change — and any fired triggers appear in a top-level
-  `next.suggested[]` (step 13), single-sourced from the owning skill's own
-  condition text.
+- The human summary (unless `--json-only`) and the envelope are printed, envelope
+  last.
 - Nothing was modified anywhere.
 
 → Next: the envelope's `next.recommended` command — it is computed from the
   actual state, so it IS the recommendation
   · a human overview → read the printed table
-  · orchestrating programmatically → parse the last fenced json block
+  · orchestrating programmatically → parse the script's JSON

package/skills/workflow-status/references/ENVELOPE_CORE.md

@@ -1,6 +1,10 @@
 ## Machine envelope
 
-Schema and placement per the installed `orchestration-envelope` skill. The
+`scripts/workflow-status.mjs` is the **deterministic producer** of this
+envelope: it performs the assembly, runs the `validateEnvelope` self-check
+(diagnostic only, exit 0), and prints the one JSON document. The skill runs the
+script and interprets the JSON — it never assembles the envelope. Schema and
+placement per the installed `orchestration-envelope` skill. The
 `state` maps 1:1 from the crash-recovery verdict — **no new schema fields or
 states** (the schema package needs no release):
 
@@ -68,6 +72,15 @@ these need **no package change**:
   scope-bleed detection (widened by `#79`/`#89` to also match an issue
   linked from an `## Amendments` row).
 
+**Not yet mechanized (read this before consuming the three fields above).** The
+`scripts/workflow-status.mjs` sensor does **not** emit `review`, `closure`, or
+`issues_born` today: they are steps 10–12 of the published sequence and remain
+skill-side work, so no `detail.features[]`/`detail.fixes[]` entry carries them
+until a sensor phase owns them. A consumer must treat their absence as "not
+computed", never as "empty": absence is not a `closure: absent-legacy` verdict
+and not an `issues_born.n: 0`. Same discipline for `next.suggested[]` (step 13),
+which is optional by contract and omitted when no trigger fired.
+
 **`next.suggested[]`** — step 13's trigger-attributed suggestion surface,
 `{command, trigger, source_skill}[]`, **optional** (mirrors
 `packages/agentic-workflow-schema` 2.1.0's optional `EnvelopeSuggestion[]`).
@@ -77,7 +90,7 @@ second, drifting copy of that skill's logic. Advisory only: it rides beside
 trigger this run → `next.suggested` is omitted entirely (an empty/absent
 field, not an error).
 
-**Envelope shape reminders (self-check before printing — mirrors
+**Envelope shape reminders (the script validates these before printing — mirrors
 `packages/agentic-workflow-schema/envelope.schema.json`):**
 
 - `blockers[].scope` ∈ `{"unit","run"}` — there is **no** `"code"` value;
@@ -101,6 +114,8 @@ field, not an error).
 | `/triage-issue` | `strong` |
 | `/product-audit` | `strong` |
 | `/execute-phase` | `cheap` |
+| `/review-spec` | `strong` |
+| `/review-plan` | `strong` |
 
 `next.tier` is read off this map by matching the resolved `next.recommended`
 command's name (ignoring its arguments) — never guessed and never copied from

package/skills/workflow-status/references/ENVELOPE_FIELDS.md

@@ -9,6 +9,15 @@ exact shape:
 (swap `defined`/`/plan-feature` for `idea`/`/design-feature` on the design
 side). The recommendation itself is unaffected — this only adds visibility.
 
+**Shape vs. current output — read this before trusting the example below.** The
+example is the envelope's **intended shape**, not everything the deterministic
+producer emits today: per-unit `review`, `closure`, and `issues_born` (steps
+10–12) and the `next.suggested[]` surface (step 13) are **not yet mechanized**
+by `scripts/workflow-status.mjs` and do not appear in its output. A consumer
+must read their absence as "not computed", never as `closure:
+absent-legacy` or `issues_born.n: 0`; the owning note is
+`ENVELOPE_CORE.md` §Not yet mechanized.
+
 ```json
 {
   "skill": "workflow-status",

package/skills/workflow-status/references/SENSOR_CORE.md

@@ -1,4 +1,12 @@
-## Process (fixed sequence — run the commands, don't infer)
+## Process (fixed sequence — executed by the script)
+
+`bun scripts/workflow-status.mjs` (node when bun is absent — the repository's
+runtime convention) executes this whole sequence (git/forge
+collection, urgency labels-only scan, roadmap + fix-index parse, dependency
+closure, readiness + step-6a receipt sensing, phase progress, review-mark
+currency, fix-now fold projection) and prints the fixed Envelope v2 JSON. The
+numbered blocks below state the semantics the script implements; the model reads
+the JSON and interprets it.
 
 ### Normalized Repository State
 
@@ -12,14 +20,6 @@ readiness classification, if the ledger is missing, `draft`, `contradicted`, or
 sensor remains read-only; it never edits or resolves the ledger. Conflicting
 live evidence against a frozen ledger remains a contradiction candidate.
 
-1. **Git state.** `git branch --show-current`, `git status --porcelain`,
-   `git fetch` + `git status -sb`. A dirty tree or unpushed branch is reported
-   as-is (a `workflow`-kind observation in `detail`), never cleaned up.
-2. **Forge state.** List open + recently merged PRs and open issues with the
-   declared forge CLI (examples use `gh`):
-   `gh pr list --state open --json number,title,headRefName,url,statusCheckRollup`,
-   `gh pr list --state merged --limit 20 --json number,headRefName`,
-   `gh issue list --state open --json number,title,labels`.
 3. **Urgency labels (`detail.urgent`) — labels-only, presence-only, never
    decides.** Reuse the open-issue list from step 2 (`gh issue list --json
    labels` — the JSON labels array already carried by that call); no separate

package/skills/workflow-status/references/SENSOR_SIGNALS.md

@@ -28,16 +28,16 @@
       persisted marker, see `#76`") — never infer `true`/`false` from
       absence of evidence.
 11. **Per-unit closure state (`detail.*.closure`).** `{state}` ∈
-    `present | absent-legacy | blocked` — reuse `audit-pr`'s own mechanical
-    check verbatim (`skills/audit-pr/SKILL.md` "Closure integrity — fixed
-    output"): grep the governing SPEC for a `Capability closure` heading.
+    `present | absent-legacy | blocked` — reuse `audit-pr`'s own check
+    verbatim (`skills/audit-pr/SKILL.md`, "Closure integrity"): grep the SPEC
+    for a `Capability closure` heading.
     Fix-governed unit → `n/a` (fix SPECs carry no closure block by design,
     same carve-out `audit-pr` applies). Feature SPEC, block absent →
     `absent-legacy`. Feature SPEC, block present with any blank row or a
     resolved non-`n/a` row unmapped to an acceptance criterion → `blocked`.
     Feature SPEC, block present and every row filled or `n/a`-justified and
-    mapped → `present`. Single-sourced: never re-derive the three-box logic
-    here, just re-run `audit-pr`'s own grep.
+    mapped → `present`. Single-sourced: never re-derive it — re-run
+    `audit-pr`'s grep.
 12. **Per-unit descope provenance (`detail.*.issues_born`).**
     `{n, with_descope_amendment}` — reuse `audit-pr`'s scope-bleed gate
     detection verbatim (`skills/audit-pr/SKILL.md` "Scope integrity
@@ -50,6 +50,9 @@
     slug/number text match `audit-pr` itself defines — **never** an issue's
     free-text body beyond that defined match (injection-safety, mirrors
     `detail.urgent`'s labels-only discipline).
+
+*Steps 10–12's fields are **not yet emitted** — see `ENVELOPE_CORE.md` §Not yet
+mechanized.*
 13. **`next.suggested[]` — single-sourced trigger surface.** One entry per
     **fired** trigger the driver can act on now, `{command, trigger,
     source_skill}` — the `trigger` string **quotes**, never paraphrases, the