@gtrabanco/pi-agentic-workflow 0.9.0 → 0.9.1

package/package.json

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