@gtrabanco/pi-agentic-workflow 0.8.0 → 0.9.1

package/README.es.md

@@ -77,7 +77,8 @@ Dos archivos JSON, ambos opcionales:
     "plan-feature": { "model": ["anthropic/claude-sonnet-4-5", "openai/gpt-5.2"], "thinking": "medium" },
     "review-change": { "thinking": "max" }
   },
-  "onUnavailableRoute": "stop"
+  "onUnavailableRoute": "stop",
+  "onSettle": "keep"
 }
 ```
 
@@ -97,6 +98,8 @@ que ya tuviera la sesión, porque la ruta por defecto del paquete es
   prueba `anthropic/claude-sonnet-4-5` primero y luego `openai/gpt-5.2`.
 - `thinking` es uno de `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`,
   o `"inherit"`.
+- `` `onSettle` `` es uno de `"keep"` (el default) o `"restore"` — ver
+  [Tu sesión después de un comando](#tu-sesión-después-de-un-comando).
 - Claves desconocidas, `null` y referencias mal formadas se **rechazan**, no se
   ignoran: un error tipográfico que no hace nada en silencio es el bug que nunca
   encuentras.
@@ -116,14 +119,28 @@ aun así:
 { "onUnavailableRoute": "inherit" }
 ```
 
-## Tu sesión vuelve
+## Tu sesión después de un comando
 
-El enrutamiento dura un comando. Cuando el turno termina, la sesión vuelve a
-como estaba — el modelo *y* el nivel de thinking, porque seleccionar un modelo
-puede mover el nivel. Si cambias el modelo tú mismo a mitad de turno, con
-`/model` por ejemplo, no se restaura nada: tu elección gana, y el comando lo
-dice. Si mueves solo el nivel de thinking, lo conservas mientras el modelo
-vuelve.
+Por defecto (**`onSettle: "keep"`**), el modelo enrutado y el nivel de thinking
+**se quedan** en la ventana de chat abierta cuando el comando termina. Si
+`plan-feature` corre en `glm-5` y quieres retocar el plan que produjo, tu siguiente
+prompt sigue corriendo en `glm-5` — igual con una pregunta posterior. Cuando no
+necesitas el modelo pesado, lo cambias tú con `/model` (o Ctrl+P) a algo más
+barato; nada restaura sobre tu elección.
+
+Para volver a traer el modelo y el nivel de thinking previos al comando cuando este
+termina, pon:
+
+```json
+{ "onSettle": "restore" }
+```
+
+(El modo `restore` es el histórico contrato AC8: tras un comando enrutado la
+sesión vuelve a como estaba — el modelo *y* el nivel de thinking, porque
+seleccionar un modelo puede mover el nivel. Si cambias el modelo tú mismo a
+mitad de turno, con `/model` por ejemplo, no se restaura nada: tu elección gana,
+y el comando lo dice. Si mueves solo el nivel de thinking, lo conservas mientras
+el modelo vuelve.)
 
 ## Consola de configuración
 
@@ -159,7 +176,7 @@ consola nunca se queda sin salida.
 | `could not be selected` | Pi rechazó el cambio. El comando se detiene con el motivo — salvo que `onUnavailableRoute` sea `inherit`, en cuyo caso avisa y se ejecuta con tu modelo actual. |
 | `refused: the agent is busy` | Hay un turno en ejecución. Espera a que termine. |
 | `is still routed` | El comando enrutado anterior no ha terminado. |
-| `leaving the model you chose in place` | Cambiaste el modelo durante el turno enrutado, así que no se restauró nada: tu elección ganó. |
+| `leaving the model you chose in place` | (en modo `restore`) Cambiaste el modelo durante un turno enrutado, así que no se restauró nada: tu elección ganó. |
 | `these configured routes match no command` | Una clave de `commands` no nombra nada. Corrige la escritura o elimina la entrada. |
 
 ## Notas

package/README.md

@@ -75,7 +75,8 @@ Two JSON files, both optional:
     "plan-feature": { "model": ["anthropic/claude-sonnet-4-5", "openai/gpt-5.2"], "thinking": "medium" },
     "review-change": { "thinking": "max" }
   },
-  "onUnavailableRoute": "stop"
+  "onUnavailableRoute": "stop",
+  "onSettle": "keep"
 }
 ```
 
@@ -95,6 +96,8 @@ whatever the session already had, because the shipped default route is
   then `openai/gpt-5.2`.
 - `thinking` is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`,
   or `"inherit"`.
+- `` `onSettle` `` is one of `"keep"` (the default) or `"restore"` — see
+  [Your session after a command](#your-session-after-a-command).
 - Unknown keys, `null`s and malformed references are **rejected**, not ignored: a
   typo that silently did nothing is the bug you would never find.
 
@@ -112,13 +115,28 @@ nothing runs on a model you did not pick. To run anyway on the current model, se
 { "onUnavailableRoute": "inherit" }
 ```
 
-## Your session comes back
+## Your session after a command
 
-Routing lasts one command. When the turn settles, the session is put back the way
-you had it — the model *and* the thinking level, because selecting a model can
-move the level. If you change the model yourself mid-turn, with `/model`, say,
-nothing is restored: your choice wins, and the command says so. Change only the
-thinking level and you keep it while the model still comes back.
+By default (**`onSettle: "keep"`**), the routed model and thinking level **stay**
+in the open chat window once the command settles. If `plan-feature` runs on
+`glm-5` and you want to tweak the plan it produced, your next prompt keeps
+running on `glm-5` — same for a follow-up question. When you don't need the
+heavy model, switch it yourself with `/model` (or Ctrl+P) to something cheaper;
+nothing restores over your choice.
+
+To bring back the pre-command model and thinking level after a command settles,
+set:
+
+```json
+{ "onSettle": "restore" }
+```
+
+(The `restore` mode is the historical AC8 contract: after a routed command the
+session is put back the way you had it — the model *and* the thinking level,
+because selecting a model can move the level. If you change the model yourself
+mid-turn, with `/model` say, nothing is restored: your choice wins, and the
+command says so. Change only the thinking level and you keep it while the model
+still comes back.)
 
 ## Settings console
 
@@ -152,7 +170,7 @@ fall back to a plain prompt, so the console never dead-ends.
 | `could not be selected` | Pi refused the switch. The command stops with the reason — unless `onUnavailableRoute` is `inherit`, in which case it warns and runs on your current model. |
 | `refused: the agent is busy` | A turn is running. Wait for it to settle. |
 | `is still routed` | The previous routed command has not settled yet. |
-| `leaving the model you chose in place` | You changed the model during a routed turn, so nothing was restored — your choice won. |
+| `leaving the model you chose in place` | (in `restore` mode) You changed the model during a routed turn, so nothing was restored — your choice won. |
 | `these configured routes match no command` | A `commands` key names nothing. Fix the spelling or delete the entry. |
 
 ## Notes

package/dist/config/defaults.js

@@ -8,4 +8,5 @@ export const DEFAULT_CONFIG = {
     default: { ...DEFAULT_ROUTE },
     commands: {},
     onUnavailableRoute: "stop",
+    onSettle: "keep",
 };

package/dist/config/merge.js

@@ -35,6 +35,7 @@ export function mergeConfigs(globalFile = {}, projectFile = {}) {
         default: effectiveDefault,
         commands,
         onUnavailableRoute: projectFile.onUnavailableRoute ?? globalFile.onUnavailableRoute ?? DEFAULT_CONFIG.onUnavailableRoute,
+        onSettle: projectFile.onSettle ?? globalFile.onSettle ?? DEFAULT_CONFIG.onSettle,
     };
 }
 /** The route a command runs under: its own resolved override, else the default route. */

package/dist/config/schema.js

@@ -1,4 +1,4 @@
-import { MAX_MODEL_CHAIN, THINKING_LEVELS, UNAVAILABLE_ROUTE_POLICIES } from "./types.js";
+import { MAX_MODEL_CHAIN, SETTLE_POLICIES, THINKING_LEVELS, UNAVAILABLE_ROUTE_POLICIES } from "./types.js";
 /**
  * Strict validator for one config file (SPEC S5-S8, D-E5).
  *
@@ -8,7 +8,7 @@ import { MAX_MODEL_CHAIN, THINKING_LEVELS, UNAVAILABLE_ROUTE_POLICIES } from "./
  * strong model ran when it did not. Only a *missing* file resolves to the
  * default, and that decision belongs to the loader.
  */
-const ROOT_KEYS = new Set(["default", "commands", "onUnavailableRoute"]);
+const ROOT_KEYS = new Set(["default", "commands", "onUnavailableRoute", "onSettle"]);
 const ROUTE_KEYS = new Set(["model", "thinking"]);
 const COMMAND_NAME = /^[a-z0-9][a-z0-9._-]*$/u;
 function isRecord(value) {
@@ -37,6 +37,9 @@ function isThinkingSetting(value) {
 function isUnavailableRoutePolicy(value) {
     return UNAVAILABLE_ROUTE_POLICIES.includes(value);
 }
+function isSettlePolicy(value) {
+    return SETTLE_POLICIES.includes(value);
+}
 function describe(value) {
     return typeof value === "string" ? `"${value}"` : JSON.stringify(value) ?? String(value);
 }
@@ -115,7 +118,7 @@ function validateConfig(value) {
         if (!ROOT_KEYS.has(key)) {
             issues.push({
                 path: `$.${displayKey(key)}`,
-                message: `unknown config key "${key}" (allowed: default, commands, onUnavailableRoute)`,
+                message: `unknown config key "${key}" (allowed: default, commands, onUnavailableRoute, onSettle)`,
             });
         }
     }
@@ -153,6 +156,17 @@ function validateConfig(value) {
             config.onUnavailableRoute = value.onUnavailableRoute;
         }
     }
+    if (value.onSettle !== undefined) {
+        if (!isSettlePolicy(value.onSettle)) {
+            issues.push({
+                path: "$.onSettle",
+                message: `must be "keep" or "restore", got ${describe(value.onSettle)}`,
+            });
+        }
+        else {
+            config.onSettle = value.onSettle;
+        }
+    }
     return issues.length > 0 ? { ok: false, issues } : { ok: true, config };
 }
 /**

package/dist/config/types.d.ts

@@ -37,18 +37,29 @@ export interface ConfigFile {
     default?: RouteFile;
     commands?: Record<string, RouteFile>;
     onUnavailableRoute?: UnavailableRoutePolicy;
+    /** What happens to the routed model and thinking level after the command settles. */
+    onSettle?: SettlePolicy;
 }
 export type UnavailableRoutePolicy = "stop" | "inherit";
+/**
+ * What the session holds after a routed command settles.
+ *  - `"keep"` — the routed model and thinking level stay in the open chat window,
+ *    so a follow-up edit or question keeps running on the model that planned it.
+ *  - `"restore"` — the pre-dispatch model and thinking level come back (AC8).
+ */
+export type SettlePolicy = "keep" | "restore";
 /** One rejected field inside one config file, addressed by a JSON-path-ish string. */
 export interface ConfigIssue {
     path: string;
     message: string;
 }
 export declare const UNAVAILABLE_ROUTE_POLICIES: readonly UnavailableRoutePolicy[];
+export declare const SETTLE_POLICIES: readonly SettlePolicy[];
 export interface EffectiveConfig {
     default: Route;
     commands: Record<string, Route>;
     onUnavailableRoute: UnavailableRoutePolicy;
+    onSettle: SettlePolicy;
 }
 export interface ConfigProblem {
     scope: "global" | "project";

package/dist/config/types.js

@@ -12,3 +12,4 @@ export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhig
 /** Cap on chain length (issue deliberation: 8 was "almost certainly a mistake"; 4 keeps the view readable). */
 export const MAX_MODEL_CHAIN = 4;
 export const UNAVAILABLE_ROUTE_POLICIES = ["stop", "inherit"];
+export const SETTLE_POLICIES = ["keep", "restore"];

package/dist/routing/dispatch.js

@@ -79,6 +79,12 @@ export function createRouter({ surface, loadConfig, hint, settingsCommand, known
             // Cleared first: the restore fires its own select events, and a turn that is
             // already over must not read them as operator changes.
             pending = undefined;
+            // `keep`: leave the routed model and thinking level in the open chat window,
+            // so a follow-up edit or question keeps running on the model that planned it.
+            // The operator's own mid-turn choice is still untouched (nothing is restored,
+            // so it cannot be overwritten). Only "restore" puts the snapshot back (AC8).
+            if (turn.settlePolicy === "keep")
+                return;
             await restore(turn, surface(ctx), ctx, "finished");
         },
         async dispatch(command, args, ctx) {
@@ -198,7 +204,14 @@ export function createRouter({ surface, loadConfig, hint, settingsCommand, known
                 ctx.notify(`/${command.name} is running. Per-command models are optional: configure them with /${settingsCommand} or the pi-agentic-workflow.json files. This hint appears once.`, "info");
             }
             if (applied.model || applied.thinking) {
-                pending = { command: command.name, snapshot, applied, userChangedModel: false, userChangedThinking: false };
+                pending = {
+                    command: command.name,
+                    snapshot,
+                    applied,
+                    settlePolicy: loaded.config.onSettle,
+                    userChangedModel: false,
+                    userChangedThinking: false,
+                };
             }
             // Pi expands `/skill:<x>` by the skill's frontmatter `name:`, and passes an
             // unknown key through as literal text — so the name is the only correct
@@ -217,7 +230,16 @@ export function createRouter({ surface, loadConfig, hint, settingsCommand, known
                 pending = undefined;
                 const rolledBack = Boolean(applied.model || applied.thinking);
                 if (rolledBack) {
-                    await restore({ command: command.name, snapshot, applied, userChangedModel: false, userChangedThinking: false }, session, ctx, `dispatch failed (${error.message}); the session was put back`);
+                    await restore({
+                        command: command.name,
+                        snapshot,
+                        applied,
+                        // The turn never started, so the rollback always restores — it is not a
+                        // settle, and `onSettle` does not apply. Explicit, not read from config.
+                        settlePolicy: "restore",
+                        userChangedModel: false,
+                        userChangedThinking: false,
+                    }, session, ctx, `dispatch failed (${error.message}); the session was put back`);
                 }
                 return refuse(ctx, "dispatch-failed", `/${command.name} was not dispatched: ${error.message}. Nothing was sent${rolledBack ? ", and the session model was put back" : ""}.`);
             }

package/dist/settings/console.d.ts

@@ -40,6 +40,7 @@ export declare const prompts: {
     readonly undone: "The routing was undone and the session put back.";
     readonly command: "Which command?";
     readonly policyChoice: "What should happen when a configured model is unavailable?";
+    readonly settleChoice: "What should happen after a routed command settles?";
     readonly saveTo: (path: string) => string;
     readonly discard: "Discard the draft?";
     readonly setDefaultRoute: "Set the default route";
@@ -49,6 +50,7 @@ export declare const prompts: {
     readonly bulkClear: "Clear several overrides";
     readonly addAnother: "Add another?";
     readonly policy: "Set the unavailable-route policy";
+    readonly settle: "Set the post-command model keep/restore policy";
     readonly save: "Save";
     readonly cancel: "Cancel";
     readonly model: (target: string) => string;

package/dist/settings/console.js

@@ -10,7 +10,7 @@
 import { loadConfig, configFilePaths } from "../config/load.js";
 import { effectiveRoute } from "../config/merge.js";
 import { parseConfigFile, parseModelReference } from "../config/schema.js";
-import { MAX_MODEL_CHAIN, THINKING_LEVELS, UNAVAILABLE_ROUTE_POLICIES } from "../config/types.js";
+import { MAX_MODEL_CHAIN, SETTLE_POLICIES, 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
@@ -23,6 +23,7 @@ export const prompts = {
     undone: "The routing was undone and the session put back.",
     command: "Which command?",
     policyChoice: "What should happen when a configured model is unavailable?",
+    settleChoice: "What should happen after a routed command settles?",
     saveTo: (path) => `Save the draft to ${path}?`,
     discard: "Discard the draft?",
     setDefaultRoute: "Set the default route",
@@ -32,6 +33,7 @@ export const prompts = {
     bulkClear: "Clear several overrides",
     addAnother: "Add another?",
     policy: "Set the unavailable-route policy",
+    settle: "Set the post-command model keep/restore policy",
     save: "Save",
     cancel: "Cancel",
     model: (target) => `Model for ${target}?`,
@@ -71,6 +73,7 @@ export async function runSettingsConsole(deps) {
             prompts.bulkApply,
             prompts.bulkClear,
             prompts.policy,
+            prompts.settle,
             ...(deps.routing?.inFlight() ? [prompts.undoInFlight] : []),
             prompts.save,
             prompts.cancel,
@@ -142,6 +145,12 @@ export async function runSettingsConsole(deps) {
                 draft = { ...draft, onUnavailableRoute: picked };
             continue;
         }
+        if (choice === prompts.settle) {
+            const picked = await deps.ui.select(prompts.settleChoice, [...SETTLE_POLICIES]);
+            if (isSettle(picked))
+                draft = { ...draft, onSettle: picked };
+            continue;
+        }
         if (choice === prompts.save) {
             const saved = await saveScope(deps, scope, path, draft);
             if (saved)
@@ -405,6 +414,7 @@ function describeRouting(file) {
         file.default ? `default: ${file.default.model ?? "inherit"} / ${file.default.thinking ?? "inherit"}` : "default: inherit / inherit",
         ...Object.entries(file.commands ?? {}).map(([name, route]) => `${name}: ${route.model ?? "inherit"} / ${route.thinking ?? "inherit"}`),
         `unavailable: ${file.onUnavailableRoute ?? "stop"}`,
+        `settle: ${file.onSettle ?? "keep"}`,
     ];
     return routes.join(" · ");
 }
@@ -428,6 +438,8 @@ function clean(draft) {
         file.commands = commands;
     if (draft.onUnavailableRoute)
         file.onUnavailableRoute = draft.onUnavailableRoute;
+    if (draft.onSettle)
+        file.onSettle = draft.onSettle;
     return file;
 }
 function parseFile(text, scope) {
@@ -448,3 +460,6 @@ function isThinkingLevel(value) {
 function isPolicy(value) {
     return value === "stop" || value === "inherit";
 }
+function isSettle(value) {
+    return value === "keep" || value === "restore";
+}

package/dist/settings/view.js

@@ -31,6 +31,7 @@ function configLines(config, commands) {
                 `  ${overrides.length} of ${total} commands override the default route`,
             ]),
         `  when a configured model is unavailable: ${config.onUnavailableRoute}`,
+        `  after a routed command settles: ${config.onSettle}`,
     ];
 }
 function route(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "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