@gtrabanco/pi-agentic-workflow 0.1.0 → 0.3.0

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

@@ -27,6 +27,7 @@ side). The recommendation itself is unaffected — this only adds visibility.
            "suggested": [{"command": "/review-change", "trigger": "accumulation: 420 changed lines since last-reviewed sha", "source_skill": "execute-phase"}]},
   "detail": {
     "design_candidates": [{"id": "08-billing-webhooks", "status": "idea", "next": "/design-feature 08-billing-webhooks"}],
+    "pre_execution": [{"unit": "12-export-api", "stage": "plan", "label": "stale", "verdict": "PLAN-REVIEW-PASS", "boundDigest": "sha256:9f2c…", "observedDigest": "sha256:41ab…", "recommended": "/review-plan 12-export-api", "reason": "docs/features/12-export-api/ACCEPTANCE.md changed after the review"}],
     "features": [
       {"id": "07-csv-export", "status": "in-progress", "deps": ["01"], "deps_unmet": [],
        "phase": {"current": "P2", "total": 4}, "pr": null,
@@ -68,8 +69,11 @@ side). The recommendation itself is unaffected — this only adds visibility.
 ```
 
 `detail.startable_now`, `detail.blocked_units` (with build orders),
-`detail.design_candidates`, and `detail.pending_triage` are the keys an
-orchestrator routes on; every id in `startable_now`/`blocked_units` must appear
+`detail.design_candidates`, `detail.pre_execution` (one row per sensed unit from step
+6a, `{unit, stage, label, verdict, boundDigest, observedDigest, recommended, reason}`,
+`verdict`/`reason` null when absent) and `detail.pending_triage` are the keys an
+orchestrator routes on; a unit appears in `startable_now` only when its
+`pre_execution[].label` is `current` for the stage it is about to enter; every id in `startable_now`/`blocked_units` must appear
 fully in `features`/`fixes` — an `idea` unit appears ONLY in
 `design_candidates` (and `detail.features`), never in `startable_now`, since
 it has no deps-met check to pass (design precedes dependency startability).

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

@@ -0,0 +1,78 @@
+## Pre-execution receipt sensing (step 6a)
+
+Roadmap status says what exists; only a receipt bound to the current bytes says
+whether the unit may be executed. Sense it like every other signal — read the file,
+recompute the digest, never trust the prose sitting around the block.
+
+### What is read
+
+For every unit whose resolved status is `defined`, `planned` or `in-progress`:
+
+1. The newest `## Pre-execution review receipt v1 — spec` and `… — plan` block in the
+   unit's `progress.md` (no `progress.md`, or no block for that stage → `missing`).
+2. The `snapshot` line — the `sha256:` digest the receipt binds — and each bound
+   artifact's current bytes: re-derive the digest with the recipe owner's verify
+   mode — `node scripts/pre-execution-snapshot.mjs verify --stage <spec|plan> --unit
+   <id> [--parent <64-hex>]` (`pre-execution-review` owns the recipe; a feature plan
+   check needs the Product digest it descended from, a fix check binds no parent).
+   Read `structural.reasonCode` and `structural.changedPaths` out of the JSON — they
+   name the dimension that stopped being true, which is what the sensor labels
+   `stale`. A snapshot digest is a canonical
+   SHA-256 over the snapshot object, so `git hash-object` is never a substitute: it
+   stays correct only for the frozen `ACCEPTANCE.md` manifest blob.
+3. The verdict, the reviewed `unit`, the stage, and the author fields
+   (`reviewer` and `authorId` — the receipt's `Reviewer:` / `Author:` lines — and
+   `authorExclusion`).
+
+### What proves a review ran (step 8)
+
+One artifact later, the same discipline: step 8's `review_pending` keys on the
+unit's **durable review mark** — the `REVIEW-RAN` row of its `review-findings.md`
+ledger, whose shape and writer `pre-execution-review`'s `LEDGERS.md` owns — and
+judges it by step 8's currency rule in `SENSOR_CORE.md`, never by a keying
+invented here. A findings ledger with rows and no mark leaves the unit
+review-pending: its rows prove findings were folded against
+some state, which is a different fact from *this* state being reviewed, so the
+sensor reports a missing gate, never a verdict that no review ever happened.
+
+### One label per stage, and the command it recommends
+
+| Label | Evidence | Recommended |
+|---|---|---|
+| `current` | stage PASS verdict **and** recomputed digest = bound digest | spec: `/plan-feature <slug>` · plan: `/execute-phase <NN>` |
+| `missing` | no receipt block for the stage | `defined` → `/review-spec <slug>` · planned/in-progress → `/review-plan <NN>` |
+| `stale` | bound digest differs, or a bound context row moved | re-run **that stage's** review |
+| `wrong-stage` | the only PASS belongs to the other stage | the stage that is missing — never the stage that passed |
+| `substitute` | prose verdict, legacy block, or internal attestation stands where a receipt should be | that stage's review, and report the substitute as a blocker detail |
+| `self-approved` | the author of the artifact recorded the PASS | that stage's review in a clean context |
+| `author-readiness` | an authoring readiness result sits where a verdict should be | that stage's review — readiness never licenses execution |
+| `legacy` | `planned`/`in-progress` unit with no ledgers and no receipt (predates feature 28) | the adoption route below |
+
+A stale receipt re-runs the **review**, not the authoring skill: the artifacts may be
+exactly right and simply need re-judging in a clean context. A missing verdict block,
+or a verdict outside the stage's fixed set, is `missing` with the reason recorded —
+never a guess in the recommended direction.
+
+### Envelope projection
+
+- A unit that is otherwise startable but lacks a current PASS for the stage it is
+  about to enter becomes a `gate` blocker (`scope: unit`, detail names stage +
+  label). `startable_now` keeps only units whose next command is genuinely runnable,
+  so `next.recommended` never points a human at `execute-phase` on an unreviewed plan.
+- `detail.pre_execution[]` gains one row per sensed unit: `{unit, stage, label,
+  verdict, boundDigest, observedDigest, recommended, reason}` — `verdict`/`reason`
+  are `null` when absent, `observedDigest` is always the digest computed **now**.
+  `detail` is opaque to the envelope schema, so no field outside it changes.
+- Nothing is inferred from the *absence* of a block: an unreadable artifact is
+  `missing` with the failure in `reason`, never a carried-forward claim from the
+  receipt itself.
+
+### Legacy units
+
+A `planned`/`in-progress` unit with no ledgers and no receipt predates the gate; it
+reports as `legacy`, which is a different fact from `missing` ("never reviewed") and
+routes the human differently. `pre-execution-review` owns the adoption rule —
+construct the ledgers, never coerce old evidence, keep frozen acceptance and every
+past commit byte-identical, and resume only on a current `PLAN-REVIEW-PASS`. This
+sensor only reports the label and the command; it never edits a unit to make the
+label disappear, and it files nothing.

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

@@ -64,16 +64,36 @@ live evidence against a frozen ledger remains a contradiction candidate.
      command matched to the exact status: `defined` → `/plan-feature <slug>`,
      `planned` → `/execute-phase <NN>`.
    - deps unmet (any status ≥ `defined`) → `blocked_units` (unchanged).
+6a. **Sense the pre-execution receipts** for every unit at `defined`, `planned` or
+   `in-progress` ([pre-execution evidence](PRE_EXECUTION.md)): read the stage's
+   newest receipt block, re-derive the bound digest with the recipe owner's
+   verify mode (`node scripts/pre-execution-snapshot.mjs verify --stage
+   <spec|plan> --unit <id> [--parent <64-hex>]` — a snapshot digest is a canonical SHA-256, never a
+   git blob id; `structural.reasonCode` names the dimension that drifted), and
+   label the stage `current`/`missing`/`stale`/`wrong-stage`/`substitute`/
+   `self-approved`/`author-readiness`/`legacy`. The label **overrides step 6's
+   status-only command**: a unit without a current PASS for the stage it is about to
+   enter is demoted out of `startable_now` into a `gate` blocker naming the missing
+   review, and `detail.pre_execution[]` records the row. A roadmap row is never
+   edited here — sensing only reads.
 7. **Phase progress.** For each in-progress feature, read `TASKS.md`: current
    phase, total phases, per-phase checkbox completion.
 8. **Pending quality gates.** For each unit with commits: has the mandatory
-   `review-change` for its current state run (review report present in the
-   feature folder — the unit's `review-findings.md` fold ledger, when
-   present, IS that artifact: its presence, with any rows at all, proves
-   `review-change` ran for the unit's current state)? Has `audit-pr` a
+   `review-change` for its current state run? The artifact is the unit's
+   **durable review mark** — the `REVIEW-RAN` row of its `review-findings.md`
+   fold ledger, whose shape and writer `pre-execution-review`'s `LEDGERS.md`
+   owns — and it counts while the sha it names is an ancestor of the unit's head
+   and no commit after it touched a bound input of that review, over the paths
+   `pre-execution-review`'s `SNAPSHOT.md` binds:
+   `git log <mark-sha>..HEAD -- <bound paths>` prints nothing. Equality with the
+   head is not the test and cannot be: carrying the mark is a commit, and that
+   commit moves the head, so a rule keyed on equality calls every review that
+   finished its own turn unreviewed. The ledger's presence is never that proof: a
+   review that found nothing writes no finding row, so presence would call a
+   reviewed unit unreviewed and an unreviewed one reviewed. Has `audit-pr` a
    MERGE-READY bound to the PR's current head SHA (look for the audit
-   comment marker on the PR)? Derive `review_pending` / `audit_pending` /
-   `merge_ready` per unit.
+   comment marker on the PR)? Derive `review_pending` (no current mark) /
+   `audit_pending` / `merge_ready` per unit.
 9. **Fix-now fold ledger → `findings.fix_now[]`.** For each in-flight unit
    (feature or fix) that has a `review-findings.md` ledger, read only its
    `folded: no` rows and emit each as a structured item:
@@ -93,3 +113,23 @@ live evidence against a frozen ledger remains a contradiction candidate.
    error); no unit in the run has one → `findings.fix_now: []`, same as
    today. **Read-only**: this step only projects the ledger's current
    unfolded rows — never writes, ticks `folded`, or judges.
+
+### Envelope fields the sensor projects (versioned grammar)
+
+Steps 1-9 print these keys and no others; each row must be a field the schema
+package's envelope validator declares for that object.
+
+```text
+sensor-fields@1
+# machine: envelope
+object | field
+unit | type
+pr | merge_ready
+gates | review_pending
+gates | audit_pending
+findings | fix_now
+findings.fix_now | suggested_tier
+dependencies | unmet
+blockers | kind
+recommendations | product_audit
+```