@gtrabanco/pi-agentic-workflow 0.1.0 → 0.2.0

package/skills/review-spec/references/CHECKS.md

@@ -0,0 +1,105 @@
+## Snapshot, prompt, and Product checks
+
+Run in this order: build the snapshot, then falsify, then check. Nothing below
+writes to the reviewed artifact.
+
+### 1. Build the snapshot (exact bytes, one revision)
+
+```bash
+git rev-parse HEAD                       # sourceRevision — one value for the whole review
+```
+
+Construct `PreExecutionArtifactSnapshot v1` (`agentic-workflow/
+pre-execution-artifact-snapshot@1`) over the bytes just read. The authoritative
+validator is `@gtrabanco/agentic-workflow-schema`'s
+`validatePreExecutionArtifactSnapshotV1`; the generated JSON Schema is a
+structural projection, never the authority. Where that package is unavailable,
+record the same fields by hand and state `validated: manual` in the receipt note.
+
+A SPEC-stage snapshot is deliberately narrow:
+
+| Field | Value for this stage |
+|---|---|
+| `stage` | `spec` |
+| `unitKind` | `feature` (a `fix` unit is refused here — no Product half) |
+| `unitId` | the roadmap unit id, e.g. `28-evidence-grounded-spec-plan-review` |
+| `sourceRevision` | the exact revision read above |
+| `artifactRevisionId` | the author's current revision id from the handoff |
+| `artifacts` | **exactly one row**: `kind: spec`, `path` normalized repo-relative, `selector: spec-product-v1`, `byteLength`, lowercase SHA-256 `digest` |
+| `parentSpecSnapshotDigest` | `null` — a SPEC snapshot roots its own lineage |
+| `contexts` | each authoritative source actually consulted: `roadmap-row`, `governing-issue`, `normalized-repository-state`, `architectural-invariants`, `dependency-unit`, `project-guide` — `present` with its exact digest, or `absent` with `null` |
+
+`spec-product-v1` selects the title, `## Goal`, `## Branch`, `## Size`,
+`## Dependencies`, the whole Product half, and `## Design status` — never the
+empty or future Engineering half, so planning writes cannot invalidate this
+review by themselves. Contexts are all-or-nothing on purpose: "I did not look"
+is not representable, so an unread authority must appear as `absent` and is then
+visible to whoever reads the receipt.
+
+Ordering is normative, not cosmetic: artifact rows sort by UTF-8 path bytes,
+context rows by `kind` then `identifier`, and each `(kind, identifier)` context
+appears once. Duplicate kinds, out-of-order rows, or extra artifact rows are
+contract failures, not style.
+
+Then build the snapshot with the recipe owner —
+`pre-execution-review`'s [`SKILL.md`](<../../pre-execution-review/SKILL.md>) →
+SNAPSHOT reference: `node scripts/pre-execution-snapshot.mjs build --stage spec
+--unit <unitId>` (canonical serializer: sorted keys, context rows ordered by kind
+then identifier, UTF-8, lowercase SHA-256). The digest is stdout's first line, so
+this recipe writes no file; `--json` is in-repository only. Paste the digest it
+prints. Every verdict below is bound to that digest, and a refused build
+(partial binding) ends this turn in the refusal form [`OUTPUT.md`](OUTPUT.md) fixes —
+`Snapshot: refused` beside the builder's own code, never a hand-computed substitute.
+
+### 2. Clean-context falsification prompt
+
+Read the snapshot's Product bytes as if the document were adversarial, then
+answer, in writing, before checking anything:
+
+```text
+FALSIFICATION — <unitId> @ <sourceRevision short>
+- Name 3 specific product decisions in this half that a hostile reader could
+  call invented rather than recorded: <section/row pointers or "none found">
+- Name the user outcome the SPEC promises that has no observable check: <row>
+- Name one role the matrix leaves unspecified for a capability it does list:
+  <row or "none">
+- What would have to be true in the repository for this half to be wrong, and is
+  it true? <evidence pointer>
+- Verdict stance before checking: <CONFIRMED-GAPS | NO-CONFIRMED-GAPS>
+```
+
+The point is to try to break the document, not to summarize it. A gap this pass
+confirms is a finding; a suspicion it cannot evidence is not.
+
+### 3. Product checks (fixed list — one row each, in order)
+
+| # | Check | PASS only if |
+|---|---|---|
+| C1 | Outcome ownership | the user outcome each in-scope item produces is stated and observable, not "improve X" |
+| C2 | Actors and roles | every actor that can trigger or be affected is named, and the role matrix covers every inventory role per capability with no unlisted role |
+| C3 | Entity closure | every entity introduced or touched resolves CRUD + state transitions to UI/API/test or an explicit `n/a: <reason>`; zero blank rows |
+| C4 | Limits and failure states | size/failure/empty/concurrency limits are stated or explicitly out of scope; each named failure state has a resolution |
+| C5 | Scope and non-goals | every out-of-scope bullet names an owner or a non-goal; nothing is excluded by silence |
+| C6 | Integration closure | one resolved row per subsystem of the derived capability inventory; none skipped; the inventory is recorded when `docs/CAPABILITIES.md` is absent |
+| C7 | Expectation sweep | ≥ 10 rows (M/L) / ≥ 5 (XS/S), each forced to in-scope/out-of-scope/deferred with a pointer |
+| C8 | Acceptance objectivity | every criterion is objective and labelled command-verified or read-verified, and every in-scope bullet maps to ≥ 1 criterion |
+| C9 | Internal contradiction | no two sections of the half assert incompatible behaviour, counts, or ownership |
+| C10 | Repository contradiction | the half's claims about existing surfaces match what is in the repository now (cited `path:line`, roadmap row, or frozen ledger fact) |
+| C11 | Evidence integrity | material claims resolve to `proven`/`decision` rows that are `current`; every `unknown` names an owner and next evidence; no `drifted`/`stale` row survives |
+| C12 | Open product choices | `Deferred decisions` is `none`, or each open item is genuinely product-owned and flagged for the human |
+| C13 | Engineering leakage | the Product half pre-fills no architecture, phases, tasks, or validators (that is the Plan stage's authority) |
+| C14 | Obligation containment | no current-unit obligation is exported to a future issue or "later" — the unit's own scope carries it |
+
+Every row gets exactly one result: `pass`, `finding`, or `n/a: <reason>`. `n/a`
+requires a reason that does not contradict scope (an accessibility row is `n/a`
+when no UI exists; "skipped because large" is not `n/a`).
+
+### 4. Assemble findings
+
+Each finding is one row of the receipt's `findings` array: stable `id`,
+`severity` (`info | low | medium | high | critical`), `class` (`product | plan |
+source | environment | runtime`), `claim` (what is wrong, with the section
+pointer), `evidenceRefs` (≥ 1 — a finding without evidence is a hunch and gets
+dropped), `verification` (`verified | unverified`), `resolution` (`open` on
+emission). Material = anything above `info`; a `PASS` may not carry an open or
+unverified material row.

package/skills/review-spec/references/OUTPUT.md

@@ -0,0 +1,126 @@
+## Verdicts, receipt, and routes
+
+### Persist the receipt first, then report
+
+Append the receipt to the unit's `docs/features/<NN>-<slug>/progress.md` **and
+each finding row to the unit's `planning-findings.md`** with
+`stage: spec` (ledger contract: `pre-execution-review/references/LEDGERS.md`);
+create the file from that contract when the unit has none. A findings ledger the
+reviewer cannot write is not a ledger. Any later write to a reviewed artifact
+rotates `artifactRevisionId` and makes this receipt stale — that is the contract
+working, not a mistake.
+
+One `PreExecutionReviewReceipt v1`
+(`agentic-workflow/pre-execution-review-receipt@1`) per review, in a fenced block:
+
+```text
+## Pre-execution review receipt v1 — spec
+- Review: <receipt-id> · Snapshot: <64-hex|refused> · Verdict: <spec-review-pass|spec-review-fail|needs-design>
+- Unit: <unitId> · Stage: spec · Unit kind: <feature|fix> · Parent: null
+- Source revision: <40-hex> · Artifact revision: <artifactRevisionId>
+- Reviewer: <id> · Session: <id> · Role: reviewer · Author: <id>
+- Author exclusion: <enforced|not-enforceable> · Context clean: <true|false>
+- Model diversity: <same-model|cross-model|not-applicable> · Policy: <policyVersion>
+- Started/finished: <UTC>/<UTC> · Findings: <n> (material open: <n>)
+```
+
+Fields the runtime can enforce but a manual review must still state:
+`contextClean`, `authorExclusion`, `modelDiversity`. If context cleanliness is
+false or the reviewer identity equals the author's under an enforced exclusion,
+a PASS is not emit-able — return `SPEC-REVIEW-FAIL` and name the reason.
+
+A `Snapshot:` line carries the digest the builder printed, or the one form a refused
+build may take — `refused`, with the builder's own code beside it, never a value
+computed here instead:
+
+```text
+- Snapshot: refused · Build: refused (<the reason code the builder printed>)
+```
+
+Write that pair in place of the `Snapshot:` line, end the turn with this stage's FAIL
+verdict, and file one finding row per refused artifact carrying its code verbatim: the
+checks bind to a snapshot, so with no snapshot none of them ran. `SNAPSHOT.md` owns why
+a refusal prints no digest and what a consumer then reads this receipt as.
+
+### Verdict blocks — return exactly one
+
+```text
+SPEC-REVIEW-PASS — <NN-slug>
+- Snapshot: <digest> · Artifact revision: <artifactRevisionId> · Checks: 14/14
+- Material findings open: 0 · Read-only: no reviewed artifact modified
+- Authority: planning may bind this receipt as its Product parent
+```
+
+```text
+SPEC-REVIEW-FAIL — <NN-slug> BLOCKED
+- Snapshot: <digest> · Artifact revision: <artifactRevisionId>
+- Failed checks: <Cnn, …>
+- Findings (unioned, one row each):
+  | id | severity | class | check | claim | evidence | verification |
+- Repair owner: `design-feature <NN-slug>` — one batch over this whole set
+```
+
+```text
+NEEDS-DESIGN — <NN-slug>
+- Snapshot: <digest> · Blocking rows: <Cnn / decision id>
+- Missing product choice (product authority only): <one bounded question>
+- Recommended default: <the smallest coherent answer>
+- Downstream: any Plan evidence bound to this unit is now invalid and must be
+  re-reviewed after the answer lands
+```
+
+`NEEDS-DESIGN` when the answer requires inventing product intent, scope, role,
+authority, or user outcome; `SPEC-REVIEW-FAIL` when the half is decidable but
+incomplete, contradictory, or unsupported. Never blend them, and never emit a
+fourth verdict.
+
+### Routes
+
+| Verdict | Who repairs | What happens next |
+|---|---|---|
+| `SPEC-REVIEW-PASS` | nobody | `/plan-feature <NN-slug>` binds this receipt + exact snapshot digest |
+| `SPEC-REVIEW-FAIL` | `design-feature` (the author) | one root-caused repair batch → new revision → re-review of the new snapshot |
+| `NEEDS-DESIGN` | the human, through `design-feature` | dated `## Amendments`/`Product decisions` entry → new revision → re-review |
+
+A finding whose `class` is `plan`, `source`, `environment`, or `runtime` does not
+become work here: record it, keep it open, and route it to its owner (`review-plan`
+for plan defects, the executor for source defects). This skill repairs nothing and
+schedules nothing.
+
+Repeating this review follows the no-progress and convergence rules in
+`pre-execution-review/references/POLICY.md` §4: a repeat needs a
+changed snapshot or a named falsifiable question plus a new evidence route, and
+entering a second repair/re-review cycle prints `CONVERGENCE-ANOMALY` before any
+further edit. A `design-feature` repair turn re-reads the union of open findings
+from `planning-findings.md`, not just the newest receipt, so nothing recorded here
+is ever lost between cycles.
+
+### Skill-specific turn-contract boxes
+
+```text
+✓ Snapshot digest computed from one revision and pasted; no mixed-revision bytes
+✓ All 14 Product checks resolved to pass / finding / n/a with a reason
+✓ One verdict block returned verbatim from the closed set
+✓ Receipt appended to the unit's progress.md before the report was printed
+✓ `git status --porcelain` shows no change to any reviewed artifact
+✓ Closing `→ Next:` printed as the absolute last output
+```
+
+### Closing recommendation
+
+On PASS:
+
+```
+→ Next: /plan-feature <NN-slug> — Product half reviewed; the plan binds this receipt
+  · design changed underneath → re-run /review-spec <NN-slug> first
+  · recurring closure gaps across units → /product-audit (a systemic pattern, not one SPEC)
+```
+
+On FAIL or NEEDS-DESIGN, name every finding id once, in order, joined with ` + `:
+
+```
+→ Next: /design-feature <NN-slug> "<instruction>" — one repair batch for F1 + F2 + F4,
+    then /review-spec <NN-slug> re-reviews the new artifact revision
+  · a product choice is missing → answer it in the instruction; nothing here chooses for you
+  · finding class is plan/source/environment/runtime → route to its owner, do not edit the SPEC
+```

package/skills/ship-roadmap/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ship-roadmap
 user-invocable: true
-version: 4.0.2
+version: 5.0.0
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 argument-hint: "[--fullauto] | --continue [--fullauto]"

package/skills/ship-roadmap/references/ADVANCE.md

@@ -21,14 +21,34 @@
      undesignable unit is picked back up only by a human answering the
      recorded question and re-running `/design-feature <slug> "<answer>"`
      directly — the autopilot never re-asks it.
+   - **REVIEW-SPEC** (only between DESIGN and PLAN) — compose `review-spec` in a
+     clean context at the routed tier (opus/high), never in the turn that wrote the
+     product half. `SPEC-REVIEW-PASS` releases the unit into PLAN. A FAIL whose
+     findings are common-root-cause or wording-only returns to the same unit's
+     author for one root-caused repair batch, then a fresh review. `NEEDS-DESIGN`
+     means a product choice is open that this run's locked record cannot answer:
+     **park the unit** with the exact question (`NEEDS_INPUT`, same shape as the
+     undesignable park above) — the autopilot never answers a product question
+     itself, and `SELECT` continues with the next startable unit.
    - **PLAN** — compose `plan-feature` in-turn via its scoped path (equal
-     tier). Every unit reaching PLAN is already `planned`-bound (DESIGN ran
-     first for any `idea`/`defined` unit), so `plan-feature`'s own redirect
-     gate always passes here. The interview path is **forbidden** mid-run:
+     tier). Every unit reaching PLAN holds a current `SPEC-REVIEW-PASS` (REVIEW-SPEC
+     ran first, or the unit was already planned before this gate existed and its
+     own Product receipt is current), so `plan-feature`'s PRODUCT-REVIEW gate passes
+     here. The interview path is **forbidden** mid-run:
      SPEC gaps are resolved silently from the decision record and logged. JIT
      planning that reveals the feature's premise is wrong (obsolete, absorbed,
      impossible on this stack) → mark it blocked with the contradiction
      recorded; never re-ask.
+   - **REVIEW-PLAN** (only between PLAN and EXECUTE) — compose `review-plan` in a
+     clean context at the routed tier over the plan the previous stage just froze.
+     `PLAN-REVIEW-PASS` releases EXECUTE. A FAIL routes by root cause: plan-local
+     (bad phase cut, blank validator, ledger drift) → one root-caused re-cut by the
+     planning author and a fresh review; product-rooted or an assumption this record
+     cannot settle → `NEEDS-DESIGN` → park as in REVIEW-SPEC. A second local cycle
+     that changes nothing stops editing and reports `CONVERGENCE-ANOMALY` instead of
+     burning a third budget. **No stage between PLAN and EXECUTE may create a forge
+     issue or defer an obligation to one** — an unmet obligation fails this stage, it
+     is never exported.
    - **EXECUTE** — run each unfinished **implementation phase** in a **fresh cheap-tier context**: on Claude
      Code, spawn one subagent per phase with `model: sonnet` (the override is
      the only mechanism that runs *below* the conductor's turn tier); on an
@@ -81,10 +101,18 @@
      parked and the loop moves on); the fixer's cycle ends committed AND
      pushed (step 5), so the re-audit judges the real branch.
 
-   The stage sequence is per-feature and size-dependent — always **one stage
+   Fix units take the same pair in miniature: **plan-fix → REVIEW-PLAN → EXECUTE
+   (`--fix`)** — a fix has no Product hop to wait on (D6), so its plan review is the
+   only pre-execution gate it can have. The stage sequence is per-feature and size-dependent — always **one stage
    per iteration**: a feature starting at `idea`/`defined` gets a DESIGN stage
    first; one already `planned` (including the founding-scaffolded feature 01)
-   skips straight to PLAN. Every size follows [DESIGN] → PLAN → EXECUTE
+   goes to its missing review stage, and skips to EXECUTE only when a current
+   `PLAN-REVIEW-PASS` is bound to its bytes. Every size follows
+   **[DESIGN → REVIEW-SPEC] → PLAN → REVIEW-PLAN → EXECUTE**
    (implementation phases, fresh cheap worker per phase) → PR (explicit
    `Hardening & PR`) → REVIEW (bounded final loop) → AUDIT. Risk changes final
-   review strength, not phase cadence.
+   review strength, not phase cadence. The two review stages are the pre-execution
+   pair: they judge documents in a clean context and are **not** the post-code
+   REVIEW loop, which stays exactly as described below. Merge policy is unchanged —
+   the human (or the `--fullauto` wrapper behind its recorded floors) still owns the
+   merge, and neither review stage may merge, close, or file anything.

package/skills/ship-roadmap/references/CLOSEOUT_AND_LOG.md

@@ -10,7 +10,8 @@
    A subagent that "finished" but left the tree dirty or the branch unpushed
    did NOT finish: the conductor commits/pushes the remainder itself (same
    stage, same iteration) or marks the stage partial. This check is
-   unconditional for EXECUTE, REVIEW fix cycles, PR, and AUDIT fix cycles.
+   unconditional for REVIEW-SPEC/REVIEW-PLAN repairs, EXECUTE, REVIEW fix cycles,
+   PR, and AUDIT fix cycles.
 6. **LOG** one line to `.ship-run.log`; print `→ Next: <unit> (CONTINUE)` (the
    canonical next-step shape; `CONTINUE` stays the loop's keep-going signal).
    **Say WHY the turn is ending** — one explicit

package/skills/ship-roadmap/references/MODEL_ROUTING.md

@@ -6,6 +6,8 @@
 | Recovery, routing, logging | opus/high | in-turn (tiny token volume; a subagent would add cost, not save it) |
 | JIT feature design (mid-run `idea`/`defined` unit) | opus/high | compose `design-feature` + `plan-feature-scaffold` in-turn (equal tier, deriving only from `SHIP_DECISIONS.md` — no new questions) |
 | JIT feature planning | opus/high | compose `plan-feature` in-turn (its internals are opus/high–medium: ≥ holds) |
+| Product review (REVIEW-SPEC) | opus/high | `review-spec` in a **clean context** (fresh subagent or outside headless call) — never the turn that wrote the product half; tier equals or exceeds the author's, so the ≥ rule holds |
+| Plan review (REVIEW-PLAN) | opus/high | `review-plan` in a **clean context**, same rule; it judges the plan the previous stage froze |
 | Phase execution, single-pass, fixes | **cheap worker** | fresh context per phase following `execute-phase`; Claude branch maps this role to `sonnet`, portable drivers use their validated worker tier |
 | Final review/correction loop | opus/high | compose `loop-review-fold`; it selects review or fold from persisted evidence and routes unresolved findings to `triage-issue --prioritize-now` |
 | Merge gate | opus/high | compose `audit-pr` in-turn (the highest-stakes automated verdict; must share one turn with the floor checks) |

package/skills/ship-roadmap/references/RECOVERY_AND_SELECTION.md

@@ -61,7 +61,8 @@ turns:
       **Verify the closure transitively:** a dep row marked merged whose own
       dependencies aren't merged means the roadmap's statuses are inconsistent
       → `SHIP: STOPPED` (substrate invariant broken), never build on top of it.
-      → `idea`/`defined`: DESIGN first (see ADVANCE). `planned`: → PLAN
+      → `idea`/`defined`: DESIGN first (see ADVANCE). `planned`: → REVIEW-SPEC/
+         REVIEW-PLAN if its receipt for that stage is missing or stale, else PLAN/EXECUTE
       directly.
    5. **Issue sweep — features exhausted, run NOT over.** Every roadmap feature
       is `done` **and merged** but the sweep hasn't completed → the run
@@ -81,7 +82,7 @@ turns:
          report (promotions and untracked residue become report proposals,
          never in-run scope or automatically-created issues).
       3. **SHIP the fix-now issues** one unit at a time through the normal
-         stages (`plan-fix` → EXECUTE (`--fix`) → PR → REVIEW → AUDIT), same
+         stages (`plan-fix` → REVIEW-PLAN → EXECUTE (`--fix`) → PR → REVIEW → AUDIT), same
          budget caps, floors, and merge policy as features.
    6. Nothing startable → `SHIP: BLOCKED` with the **unblock map** ("merging
       #12 unblocks 05 and 07") and the resume command.

package/skills/workflow-status/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: workflow-status
 user-invocable: true
-version: 2.0.0
+version: 3.1.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 argument-hint: "[--json-only] [--last-envelope <json|path>]"
@@ -27,9 +27,11 @@ and what the recommended next command is.** Built for external orchestrators
   fix index, feature folders) — nothing inferred from memory
 ✓ 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:
-  `idea`/undesigned → `/design-feature <slug>`; `defined` → `/plan-feature
-  <slug>`; `planned` → `/execute-phase <NN>`
+  `/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
+  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
@@ -86,8 +88,12 @@ invocation loads this baseline in order:
 2. [crash recovery](references/CRASH_RECOVERY.md)
 3. [envelope core](references/ENVELOPE_CORE.md)
 4. [envelope fields](references/ENVELOPE_FIELDS.md)
-5. [guardrails](references/GUARDRAILS.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

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
+```