@gtrabanco/pi-agentic-workflow 0.12.0 → 0.13.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.12.0",
+  "version": "0.13.2",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",
@@ -11,7 +11,7 @@
     "model-routing"
   ],
   "license": "MIT",
-  "author": "Gabriel Trabanco <gtrabanco@users.noreply.github.com>",
+  "author": "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/gtrabanco/agentic-workflow.git",
@@ -44,6 +44,7 @@
   "scripts": {
     "build": "tsc",
     "bundle:skills": "bun scripts/bundle-skills.mjs",
+    "bundle:skills:check": "bun scripts/bundle-skills.mjs --check",
     "test": "tsc && bun test test/*.test.mjs",
     "test:node": "tsc && node --test test/*.test.mjs",
     "prepublishOnly": "bun run build && bun run test",
@@ -51,10 +52,10 @@
     "prepare": "bun run build"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.85.1"
+    "@earendil-works/pi-coding-agent": ">=0.87.0"
   },
   "dependencies": {
-    "@earendil-works/pi-tui": "0.85.1"
+    "@earendil-works/pi-tui": "0.87.0"
   },
   "devDependencies": {
     "@types/node": "24.13.3",

package/skills/audit-docs/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: audit-docs
 user-invocable: true
-version: 2.0.1
+version: 2.1.0
 argument-hint: "[--fix]"
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Audit cross-document coherence: docs ↔ roadmap ↔ code ↔ fix index ↔ issues.
@@ -95,7 +95,7 @@ run the command shown, don't infer.
     `Docs site` block; otherwise state n/a).** Scan the declared content dir
     for pages carrying `generated-by: agentic-workflow/generate-docs`. For
     each: (a) its `source-unit` exists in the roadmap or fix index — no match
-    is an **orphan** (MEDIUM: propose deletion or re-attribution); (b) the
+    is an **orphan** (low: propose deletion or re-attribution); (b) the
     unit's PR merged **after** the page's `updated` date with commits touching
     the page's subject paths — that page is **stale** (LOW: propose
     `/generate-docs <unit>` to refresh). Cite page path + unit per finding.
@@ -118,16 +118,17 @@ say so.
    ```
    AUDIT DOCS — scope: <docs tree / roadmap / fix index / issues checked>
 
-   | # | Check (1-13) | Finding | Sev | Evidence | Proposed fix |
+   | # | Check (1-14) | Finding | Sev | Evidence | Proposed fix |
    |---|-------------|---------|-----|----------|--------------|
    | 1 | <which>     | <what>  | high|low | <path:line / #issue> | <smallest action> |
 
-   Checks run: <n>/13 (skipped: <which + why — absent structures only>)
+   Checks run: <n>/14 (skipped: <which + why — absent structures only>)
    Summary: <1-2 sentences>
    Decision: PASS | FAIL   (FAIL if any high-severity finding is open)
    ```
 
    Sev: **high** = misleading or broken; **low** = cosmetic.
+   Only `high` and `low` are defined in this legend
 3. **Fix only on request.** With explicit `--fix` (or user go-ahead), apply the
    low-risk corrections (remove a merged fix-index row, fix a dead link, register
    a missing roadmap entry, add a verified PR link to a bare `done` row). Leave judgment calls to the user.

package/skills/audit-pr/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: audit-pr
 user-invocable: true
-version: 5.2.1
+version: 5.3.0
 argument-hint: <pr-number> (optional — defaults to the current branch's PR)
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -51,7 +51,7 @@ independently evaluates only the delivery gates below.
 ✓ No review pass was composed or reconstructed: a missing/stale receipt is a
   blocker, never a prompt to re-run review axes from this skill
 ✓ Closure integrity was evaluated and its result stated explicitly: pass /
-  blocker / warning / n-a (fix-governed PRs are always n-a; never skipped
+  blocker / n-a (fix-governed PRs are always n-a; never skipped
   silently)
 ✓ Scope integrity (descope) was evaluated and its result stated explicitly:
   pass / blocker / n-a (no unit-referencing issues born on the branch → n-a;

package/skills/design-feature/SKILL.md

@@ -3,7 +3,7 @@ name: design-feature
 user-invocable: true
 version: 3.5.0
 argument-hint: <idea | NN-slug> [<instruction>]
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Turn a raw idea or existing feature into a designed product SPEC by completing

package/skills/evidence-grounding/SKILL.md

@@ -2,7 +2,7 @@
 name: evidence-grounding
 user-invocable: false
 version: 1.6.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal shared owner of evidence-grounded authoring: the fixed

package/skills/execute-phase/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: execute-phase
 user-invocable: true
-version: 4.6.0
+version: 4.7.0
 argument-hint: <NN> [P<k>] | --fix <n> [P<k>] | [--max-attempts N] [--force]
 allowed-tools: [Bash, Read, Edit, Write, MultiEdit]
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Implement all remaining phases of a planned feature/fix by default, or one

package/skills/execute-phase/references/EXECUTION_CONTRACT.md

@@ -57,6 +57,25 @@ never treat a missing marker as a blocker or crash condition.
 Something forbidden looks necessary → stop, record it in `decisions.md` or
 `known-issues.md`, and surface it — never do it silently.
 
+## Gate-run mark
+
+The phase completion gate records a `GATE-RAN` mark at the head it ran and
+consumes an identical-head green mark instead of re-running. The mark's shape,
+ownership, and reuse rule are declared in `LEDGERS.md` (§gate-ran@1).
+
+```text
+GATE-RAN | HEAD <40-hex sha> | <cmds> | exit <code>
+```
+
+- **Record**: whoever runs the project gate records a mark at the head the gate
+  actually ran. A green run is recorded; a red run is also recorded (exit code
+  ≠ 0 is evidence, not silence).
+- **Consume**: any skill may consume a green run only at the identical HEAD. A
+  changed head ⇒ re-run the gate.
+- **Recorder column-sets**: `execute-phase:gate-ran-marks` (executor phase gates)
+  and `review-change:review-gate-ran-marks` (reviewer gate runs) are declared in
+  the `review-findings` truth-class row's owner cell.
+
 ## Phase completion gate — pass only if (every box, every phase)
 
 ```

package/skills/execute-phase/references/FOLDING.md

@@ -23,8 +23,8 @@ end up "solved" locally but absent from the merged PR:
   (known-issues.md entry resolved? progress.md notes the fold)
 ✓ Each folded finding's row in the unit's `review-findings.md` ledger (if one
   exists — the ledger is optional; a unit with no fix-now findings has none)
-  flipped `folded: no → yes` — the one and only ledger state transition, owned
-  solely by this fold cycle
+  flipped `folded: no → yes` — the one and only ledger state transition,
+  `ledger-ownership@1` / `fold-findings:folded-flag` is the sole writer
 ✓ `git add` + `git commit` RUN (sha pasted) — e.g.
   `fix(<scope>): fold review findings — <summary>`
 ✓ `git push` RUN (PR is open → every commit pushes immediately)
@@ -35,6 +35,13 @@ Then hand back to the gate that sent you (`/review-change` re-review, or
 `/audit-pr` re-audit). Never report findings as resolved while any box is
 unchecked — an unpushed fix does not exist for CI, the reviewer, or the merge.
 
+## Gate-run mark (P4)
+
+A `GATE-RAN` mark is appended to the unit's `review-findings.md` ledger at the
+head the gate actually ran. The mark's shape and ownership rule are declared in
+`LEDGERS.md` (§gate-ran@1). A green run is recorded; a red run is also recorded.
+The identical-head reuse rule is documented in `EXECUTION_CONTRACT.md` (§gate-ran).
+
 Final-phase / single-pass / fix hand-off:
 
 ```

package/skills/fold-findings/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: fold-findings
 user-invocable: true
-version: 1.5.1
+version: 1.6.0
 argument-hint: [finding-id …]
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Repair persisted fix-now findings in compatible atomic batches: root-cause
@@ -154,8 +154,10 @@ audit-pr ──BLOCKED─────┼──▶ fold-findings ──FOLDED─
                        │                  ──BLOCKED──▶ user supplies missing input
 ```
 
-`review-change`/`audit-pr` classify and persist; this skill only flips
-`folded: no` to `yes` after a real fix. `execute-phase`'s embedded fold checklist
+`review-change`/`audit-pr` classify and persist;
+`ledger-ownership@1` / `fold-findings:folded-flag` is the sole writer of
+the `folded: no → yes` flip — this skill only flips that flag after a real
+fix. `execute-phase`'s embedded fold checklist
 is the inline fallback; this standalone path keeps frozen classification and its
 forbidden list and never runs above its tier. `DISPUTED` stops for user evidence;
 no issue is created.

package/skills/generate-docs/SKILL.md

@@ -3,7 +3,7 @@ name: generate-docs
 user-invocable: true
 version: 2.0.1
 argument-hint: "[NN-slug | fix-n | path/glob] [--review]"
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Generate incremental, diff-driven developer guides through the project's

package/skills/implementation-discovery/SKILL.md

@@ -2,7 +2,7 @@
 name: implementation-discovery
 user-invocable: false
 version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal contract: the single owner of the bounded pre-write implementation

package/skills/init-workspace/SKILL.md

@@ -3,7 +3,7 @@ name: init-workspace
 user-invocable: true
 version: 2.9.0
 argument-hint: <target-dir>
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Adapt the workflow scaffold to a new repository or add only missing substrate

package/skills/log-session/SKILL.md

@@ -3,7 +3,7 @@ name: log-session
 user-invocable: true
 version: 2.2.0
 argument-hint: "[note to prepend to the entry]"
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Append a structured entry to the project's session log (`docs/LOGS.md`):

package/skills/orchestration-envelope/SKILL.md

@@ -2,7 +2,7 @@
 name: orchestration-envelope
 user-invocable: false
 version: 2.2.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal machine-result contract for headless agentic-workflow drivers. The

package/skills/phase-contract/SKILL.md

@@ -2,7 +2,7 @@
 name: phase-contract
 user-invocable: false
 version: 1.0.5
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal contract: the single owner of the eight phase-lint rules, the fixed

package/skills/plan-feature/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: plan-feature
 user-invocable: true
-version: 5.2.0
+version: 5.3.1
 argument-hint: <NN-slug | #N> | --from-issue N | --scaffold <slug> | --next
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Route designed features or issues into engineering planning and roadmap
@@ -91,8 +91,9 @@ one hop from this file, and fail closed when missing.
    the internal steps; never re-fetched mid-plan.
 4. **Confirm roadmap.** Verify the feature is registered in
    `docs/features/ROADMAP.md` with the right number, ordering, and dependencies;
-   if any of the three is missing or wrong, fix the entry now — never leave
-   registration for later.
+   if any of the three is missing or wrong, fix the entry now — never leave registration for later.
+   `plan-feature` verifies and repairs the roadmap entry; `plan-feature-scaffold`
+   is the sole writer of the `defined → planned` write.
 5. **Dependency & blocker check (always, before recommending execution).**
    - Walk the feature's `Depends on:` closure (transitively): every dependency
      must be `done` **and merged**. Any unmet → the closing block recommends

package/skills/plan-feature-from-issue/SKILL.md

@@ -2,7 +2,7 @@
 name: plan-feature-from-issue
 user-invocable: false
 version: 2.0.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal step of plan-feature: turn a feature-request issue into a scoped,

package/skills/plan-feature-scaffold/SKILL.md

@@ -2,7 +2,7 @@
 name: plan-feature-scaffold
 user-invocable: false
 version: 2.4.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal step of plan-feature: from an already-designed SPEC (product half

package/skills/plan-fix/SKILL.md

@@ -3,7 +3,7 @@ name: plan-fix
 user-invocable: true
 version: 3.3.0
 argument-hint: <issue-number> [<issue-number> …]
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Draft and locally commit a tightly scoped, phased fix SPEC from one or more

package/skills/planning-preflight/SKILL.md

@@ -2,7 +2,7 @@
 name: planning-preflight
 user-invocable: false
 version: 1.1.1
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal planning gate: consumes the normalized repository state and makes

package/skills/pre-execution-review/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: pre-execution-review
 user-invocable: false
-version: 2.3.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+version: 2.5.1
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal owner of the pre-execution review cycle and the planning ledgers:

package/skills/pre-execution-review/references/LEDGERS.md

@@ -118,7 +118,7 @@ The one-owner rule, stated once so every skill and template can cite it here:
 **a durable ledger has exactly one writer per column set, plus at most one
 declared mechanical annotator, which may append only the token its own row
 names.** Nobody else writes a row — not a reviewer, not a later phase, not a
-script. So `fold-findings` flips only the `folded:` flag `triage-issue` gives it,
+script. So `fold-findings` flips only the `folded:` flag per the map's `fold-findings:folded-flag` owner entry,
 and `scripts/ledger-provenance.mjs` appends only the marker it really emits:
 its `· fold <sha>` (or `· ticked <sha>` on a row that scores 1) plus the
 `· REOPENED — provenance unproven` note when a tick has no matching
@@ -142,7 +142,7 @@ must pass; the CI node-compat job enforces the fallback.
 ```text
 ledger-ownership@1
 truth-class | ledger | owner | annotator | annotator-token | validator
-review-findings | docs/features/<NN>-<slug>/review-findings.md · docs/fix/<issue>-<topic>/review-findings.md | review-change:finding-rows + review-change:finding-mark + review-change:review-mark + audit-pr:audit-rows + triage-issue:triage-rows + fold-findings:folded-flag | scripts/ledger-provenance.mjs | · fold <sha> + · ticked <sha> + · REOPENED | bun test scripts/ledger-provenance.test.mjs
+review-findings | docs/features/<NN>-<slug>/review-findings.md · docs/fix/<issue>-<topic>/review-findings.md | review-change:finding-rows + review-change:finding-mark + review-change:review-mark + review-change:review-gate-ran-marks + audit-pr:audit-rows + triage-issue:triage-rows + execute-phase:gate-ran-marks + fold-findings:folded-flag | scripts/ledger-provenance.mjs | · fold <sha> + · ticked <sha> + · REOPENED | bun test scripts/ledger-provenance.test.mjs
 planning-findings | docs/features/<NN>-<slug>/planning-findings.md · docs/fix/<issue>-<topic>/planning-findings.md | review-spec:spec-stage-rows + review-plan:plan-stage-rows + design-feature:product-class-resolutions + plan-feature:plan-class-resolutions + plan-fix:fix-plan-class-resolutions + fold-findings:source-class-resolutions | none | none | bun test scripts/pre-execution-quality.test.mjs
 progress | docs/features/<NN>-<slug>/progress.md · docs/fix/<issue>-<topic>/progress.md | plan-feature-scaffold:create + execute-phase:phase-entries + execute-phase:gate-rejection-traces + review-spec:product-receipt + review-plan:plan-receipt | none | none | bun test scripts/pre-execution-sensor.test.mjs
 known-issues | docs/features/<NN>-<slug>/known-issues.md · docs/fix/<issue>-<topic>/known-issues.md | plan-feature-scaffold:create + execute-phase:blocker-entries-and-status | none | none | bun test scripts/ledger-ownership.test.mjs
@@ -207,3 +207,36 @@ reproducer as its regression check — it never re-derives it; a `recheck` cell
 that cannot be materialized yields `BLOCKED <missing input>`. This consumption
 leaves the row shape, the `VF-` exclusions, and the `review-change`
 single-writer rule untouched.
+
+### The gate-run mark
+
+A gate run — green or red — leaves a durable mark in the unit's
+`review-findings.md` ledger (for features:
+`docs/features/<NN>-<slug>/review-findings.md`, for fixes:
+`docs/fix/<issue>-<topic>/review-findings.md`), owned by the `review-findings`
+truth-class row's owner cell extended with the two recorder column-sets:
+
+```text
+gate-ran@1
+id | file:line | cmds | exit | [additive-slots ...]
+GATE-RAN | HEAD <40-hex sha> | <cmds> | exit <code> | [reserved trailing slot: `manifest <sha>`]
+```
+
+- **Fixed format** (the one grammar; every consumer cites this block):
+  `GATE-RAN | HEAD <sha> | <cmds> | exit <code>` — every run records the SHA,
+  the commands run, and the exit code (green and red alike; `exit 0` is green).
+  `<cmds>` is the runnable command(s) the gate ran, joined by ` | ` when several.
+- **Additive slots**: fields after `HEAD` are additive; consumers ignore unknown
+  trailing fields (feature 35's `manifest <sha>` slot is reserved, not yet
+  consumed).
+- **Identical-head reuse**: any skill may consume a **green** run only at the
+  identical HEAD; a changed head ⇒ re-run the gate. A red mark is never
+  consumed as a pass.
+- **Recorder column-sets**: the `review-findings` truth-class row's owner cell
+  declares `execute-phase:gate-ran-marks` (executor phase gates) and
+  `review-change:review-gate-ran-marks` (reviewer gate runs), distinct column-set
+  names per the one-writer-per-column-set rule.
+- **Owner extension**: the identical owner cell is mirrored into both template
+  projections (`docs/features/_TEMPLATE/LEDGERS.md` and `docs/fix/_TEMPLATE/LEDGERS.md`).
+- **No new truth-class row**: the grammar admits no new row — the existing
+  `review-findings.md` ledger pattern is reused with extended owner cells.

package/skills/product-audit/SKILL.md

@@ -2,11 +2,11 @@
 name: product-audit
 user-invocable: true
 disable-model-invocation: true
-version: 3.1.0
+version: 3.2.0
 metadata:
   opencode/autoinvoke: false
 argument-hint: <path-or-area> (optional — defaults to the whole product)
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Audit the whole product across code, quality, process, docs, roadmap, and
@@ -97,12 +97,12 @@ Verdict: <one-line honest health verdict>
   Installed tooling ....... ✓ | ⚠ | ✗ | n-a
 
 ## Findings (severity-ranked, one F-sequence for the whole audit)
-  F1 [SEV] <dimension> — <finding> — evidence: <file:line | metric | doc> — class: <fix-now|postpone|tradeoff>
+  F1 [SEV] <dimension> — <finding> — evidence: <file:line | metric | doc> — class: <fix-now|replan-in-unit|decision-required|proposal|ignore>
   F2 [SEV] ...
   [example — scope-export recurrence] F<k> [med] Workflow discipline — <N>
     consecutive units exported scope via `## Amendments`/descope issues —
     features are being cut too big for real capacity — evidence: <unit list +
-    amendments/issues> — class: postpone — route: #64 (atomicity/split rules)
+    amendments/issues> — class: proposal — route: #64 (atomicity/split rules)
 
 ## Delta vs audit <prior-id>
   New: F<k>

package/skills/product-audit/references/AUDIT_DIMENSIONS.md

@@ -12,7 +12,7 @@
 | **Brand / voice** | User-facing copy vs. the brand guide | surfaces with copy |
 | **Tech debt** | Accumulated shortcuts, TODO/FIXME, stale abstractions | all |
 | **Process & docs** | Incomplete phases, aging open issues, **solvable known-issues**, doc completeness, missing/optimizable workflow docs, capability-inventory freshness (`docs/CAPABILITIES.md` ↔ code drift) | all |
-| **Workflow discipline** | The workflow's own rules held: branch/PR discipline, `done · #<pr>` links, phase naming (`P1…`), per-phase docs, commit format, dependency closures, artifact language — **run `audit-docs` checks 1–13 mechanically** (compose it); never assume a rule held because it "should". **Scope-export recurrence:** across the most recent units (merged or in-flight), each with a non-empty `## Amendments` descope log or a descope-classified born issue (`audit-pr`'s scope-bleed gate) counts as one scope-exporting unit — **≥ 2 consecutive** such units is a planning-quality finding ("features cut too big for real capacity"), routed to the atomicity/split rules (**#64**), not re-litigated as a per-unit defect | all |
+| **Workflow discipline** | The workflow's own rules held: branch/PR discipline, `done · #<pr>` links, phase naming (`P1…`), per-phase docs, commit format, dependency closures, artifact language — **run `audit-docs` checks mechanically** (cite the count from `audit-docs`; never restated in the dimension table); never assume a rule held because it "should". **Scope-export recurrence:** across the most recent units (merged or in-flight), each with a non-empty `## Amendments` descope log or a descope-classified born issue (`audit-pr`'s scope-bleed gate) counts as one scope-exporting unit — **≥ 2 consecutive** such units is a planning-quality finding ("features cut too big for real capacity"), routed to the atomicity/split rules (**#64**), not re-litigated as a per-unit defect | all |
 | **Roadmap coherence** | Stale/obsolete/superseded features, missing dependencies, gaps & opportunities | all |
 | **Installed tooling** | Installed skills + connected MCP servers vs. the project's applicable axes and roadmap features — unregistered-but-useful items, and tooling that would change a feature's scope | all |
 

package/skills/product-audit/references/AUDIT_PROCESS.md

@@ -4,7 +4,7 @@
 2. **Sweep code & axes** — run the applicable axes across the codebase: compose
    `review-implementation` plus the internal review pack's applicable passes
    (each returns its fixed-format table + PASS|FAIL), and any optional installed
-   extras. Classify findings (severity + fix-now / postpone / tradeoff).
+   extras. Classify findings (severity + closed class set from review-implementation/CLASSIFY.md).
 
 **Evidence-provenance gate (fixed):** applies during every evidence-collecting sweep
 step (2–5). Each item ends with exactly one fallback; never pick another one mid-audit.

package/skills/replan-findings/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: replan-findings
 user-invocable: false
-version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+version: 1.1.1
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal contract: the conditional replan entry. Loaded only when
@@ -67,8 +67,8 @@ fingerprint: <sha256 over the inputs the answer used>
 - `read-set` is the bounded intake below: at most 12 paths, then an explicit
   `… and N more` line — never a silent truncation.
 - `open-rows`/`rows:` come from the ledger's open rows only (`folded` not
-  `yes`/`—`/`-`/`n/a`/empty), and the id shapes `VF-<n>` and `REVIEW-RAN` are
-  marks, never findings.
+  `yes`/`—`/`-`/`n/a`/empty), and the id shapes `VF-<n>`, `REVIEW-RAN` and
+  `GATE-RAN` are marks, never findings.
 
 Exit codes are part of the contract: a route prints and exits **0**; an unknown
 unit, or any argument count other than one, exits **1**; an ambiguous token (a

package/skills/review-a11y/SKILL.md

@@ -2,7 +2,7 @@
 name: review-a11y
 user-invocable: false
 version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal accessibility review pass of the agentic-workflow review pack —

package/skills/review-brand/SKILL.md

@@ -2,7 +2,7 @@
 name: review-brand
 user-invocable: false
 version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal brand & copy review pass of the agentic-workflow review pack — composed

package/skills/review-change/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: review-change
 user-invocable: true
-version: 3.6.0
+version: 3.7.0
 argument-hint: <path-or-glob> [--adversarial N] [--synthesize]
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Review a change with only applicable internal axes, classify every finding,
@@ -152,12 +152,14 @@ sequential/headless fallbacks; never collapse independent adversarial passes.
 Orchestrates internal finders (`review-code`, `review-security`, `review-verify`,
 `review-design`, `review-a11y`, `review-brand`, `review-perf`, `review-seo`), then
 one `review-implementation` classifier and `review-debt` transform, isolated by
-default; installed platform packs are optional. `triage-issue` is user-invoked
-only for independent proposals (D3). It is Stage 4: checkpoint reviews are
+default; installed platform packs are optional. `triage-issue` is user-invoked,
+never auto-run (D3), for independent proposals, audit findings, and
+`--prioritize-now` runs. It is Stage 4: checkpoint reviews are
 optional, the end review is mandatory and fresh. `fix-now` is routed to the
 unit's fold cycle — a separate `/fold-findings` invocation, never run by this review;
 `replan-in-unit` adds user-confirmed phases, and independent work becomes
-proposals. `audit-pr` consumes only the verified PR-comment receipt, never the
+proposals. `audit-pr` consumes
+only the verified PR-comment receipt, never the
 chat report; `product-audit` is the periodic sweep. On `REVIEW-FAIL` the manual
 correction path is `/fold-findings`, then re-run `/review-change` on the changed
 HEAD (bounded at two cycles — a third cycle never starts without an explicit

package/skills/review-change/references/OUTPUT_AND_GUARDRAILS.md

@@ -35,7 +35,8 @@ lost, and none becomes reviewer-created backlog (D3):
 - **fix-now / `decision-required`** → stop and surface the decision to the user;
   the unit blocks until decided. No issue is created.
 - **proposal** (independent future capability) → batched in the report with a
-  trigger; only the **user** routes it to `triage-issue`.
+  trigger; only the **user** routes it to `triage-issue` (independent
+  proposals, audit findings, or `--prioritize-now` runs).
 - **ignore** → note the rationale in the report; no further action.
 
 The report's `Decision:` line is **three-state** (D10): `REVIEW-PASS` when the

package/skills/review-change/references/PERSIST_AND_DECIDE.md

@@ -18,14 +18,17 @@ exact command tokens.
    `gh pr view --json state` when a PR is open; otherwise the unit is unmerged
    by definition). Otherwise, for each **fix-now** finding of severity `high`
    or `med` (only ledger severities; finder scale
-   `critical`→`high`, `major`→`med`, `minor`→`low`): append a row
+   converts through the canonical table in
+   `CLASSIFY.md`):
+   append a row
    (create the file with the header row when missing), carrying the
    verbatim `Sev` value into `severity`; `folded` always starts `no` — that
    row comes from a **confirmed** candidate only and carries its
    `finding-mark@1` signature on a **separate `VF-` row** (reviewer, head SHA,
    recheck + reproducer), as modeled in `LEDGERS.md` (§finding-mark@1) and the
    fixture.
-   `execute-phase`'s fold cycle is the only step that ever flips it to `yes`.
+   `ledger-ownership@1` / `fold-findings:folded-flag` is the sole writer of
+   the `folded: no → yes` flip.
    A `low` finding is **never persisted to the fold ledger** — report-only
    note (step 13), never blocking (finders' materiality floor). Re-runs
    **dedupe by `file:line` + axis**:
@@ -35,16 +38,19 @@ exact command tokens.
    **Non-fix-now findings are never written here** — they keep
    their destinations from step 11 (outcome routing): independent future
    capabilities batch as proposals; only the user routes them to `triage-issue`
-   (D3).
-   **Commit the ledger append** — rows + `REVIEW-RAN` mark, one commit
-   (`docs(<unit>): persist review findings F<n>–F<m>`), pushed when a PR is open;
+   (independent proposals, audit findings, or `--prioritize-now` runs) (D3).
+   **Commit the ledger append** — rows + `REVIEW-RAN` + `GATE-RAN` marks,
+   one commit (a reviewer records a `GATE-RAN` mark for the gate run the review
+   performed and consumes an identical-head green mark instead of re-running,
+   see `LEDGERS.md` §gate-ran@1; `docs(<unit>): persist review findings`);
+   pushed when a PR is open;
    an uncommitted append hands the next review a dirty-tree stop. On
-   `REVIEW-PASS` with an open PR no ledger write happens (the SHA-bound
-   receipt is the durable record): head and posted receipt stay identical.
-   This skill's only mutations are this ledger commit (step 11) and, on
-   `REVIEW-PASS` with a PR, the receipt comment (step 12) — it never runs a
-   fold, executes a phase, or edits source (see the review-end turn boundary in
-   the SKILL.md Turn contract).
+   `REVIEW-PASS` with an open PR the SHA-bound receipt is the durable record:
+   head and posted receipt stay identical.
+   This skill's only mutations are the rows + `REVIEW-RAN` + `GATE-RAN` marks
+   (all in the step 11 commit), and, on `REVIEW-PASS` with a PR, the receipt
+   comment (step 12) — it never runs a fold, executes a phase, or edits source
+   (see the review-end turn boundary in the SKILL.md Turn contract).
 12. **Close out the final-review receipt before reporting.** Derive the
    `Decision` from step 7 and persist step 11 first. Then — **only on
    `Decision: REVIEW-PASS` and when the PR exists** — run the receipt emitter,

package/skills/review-code/SKILL.md

@@ -2,7 +2,7 @@
 name: review-code
 user-invocable: false
 version: 1.2.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal correctness + simplification review pass of the agentic-workflow

package/skills/review-debt/SKILL.md

@@ -2,7 +2,7 @@
 name: review-debt
 user-invocable: false
 version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal tech-debt transform pass of the agentic-workflow review pack —

package/skills/review-design/SKILL.md

@@ -2,7 +2,7 @@
 name: review-design
 user-invocable: false
 version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal UI/UX design review pass of the agentic-workflow review pack —

package/skills/review-implementation/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: review-implementation
 user-invocable: false
-version: 1.8.0
+version: 1.9.0
 argument-hint: <path-or-glob>
 allowed-tools: Read, Grep, Glob, Bash, WebFetch
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal scope/classification engine composed by review-change (and reused by

package/skills/review-implementation/references/CLASSIFY.md

@@ -5,6 +5,61 @@ the **synthesized** findings table (D5). Classify each finding into exactly one
 class, in this order. Never reopen source files to classify; the table's
 evidence is authoritative.
 
+### Severity conversion (canonical table)
+
+The single-owner table below maps every severity scale the review pack emits
+onto the classification scale (`high | med | low`). Only this section may
+convert — a consumer facing an unknown scale **fails closed** (no ad-hoc
+conversion). The table replaces the ad-hoc mapping that lived at
+`PERSIST_AND_DECIDE.md`.
+
+The sensor's own `SEVERITY_VOCABULARY` map (`scripts/workflow-status.mjs:718-721`)
+is a direct projection of this table onto the envelope schema's `high|med|low`
+enum, not a competing converter; it always produces a value listed here.
+
+| Producer scale | → `high` | → `med` | → `low` |
+|---|---|---|---|
+| Ledger (`CLASSIFY.md` itself): `high` | self | — | — |
+| Ledger: `med` | — | self | — |
+| Ledger: `low` | — | — | self |
+| Finder (nine review passes): `critical` → `high` | ✓ | — | — |
+| Finder: `major` → `med` | — | ✓ | — |
+| Finder: `minor` → `low` | — | — | ✓ |
+| Planning: `critical` → `high` | ✓ | — | — |
+| Planning: `high` → `high` | ✓ | — | — |
+| Planning: `medium` → `med` | — | ✓ | — |
+| Planning: `low` → `low` | — | — | ✓ |
+| Planning: `info` → `low` | — | — | ✓ |
+| `audit-docs`: `high` → `high` | ✓ | — | — |
+| `audit-docs`: `low` → `low` | — | — | ✓ |
+
+**Unknown scale → fail closed.** A scale not listed above is an error; the
+consuming skill must not guess.
+
+### Derived blocking gate
+
+A finding **blocks** only when the reviewer cites which single-owner source
+fails — blocking is a table lookup over cited sources, never a severity
+opinion. The four citation categories are:
+
+1. **ACCEPTANCE criterion** unverified or failed.
+2. **Obligation row** in the unit's ledger is not `verified` or `n-a`.
+3. **Gate is red** at the reviewed head (the project gate exited non-zero at
+   the exact head under review).
+4. **Open confirmed `fix-now` row** on the fold ledger (a finding already
+   persisted as `fix-now` with `folded: no`).
+
+No citation among these four categories → the finding is a **report-note** or
+**proposal**, never blocking. D10's verdict rule (the three-way `REVIEW-PASS |
+REVIEW-FAIL | NEEDS-DECISION` verdict) remains **unchanged** — the derived gate
+operates inside the `REVIEW-FAIL` branch as the evidence that determines whether
+a finding truly blocks.
+
+**`report-note` definition owner.** The `report-note` classification is owned by
+`LEDGERS.md` §3 (`:91-96`): material is `medium`+, a `low` row is a persisted
+report-note. Classifying surfaces cite this owner instead of restating the
+materiality bar.
+
 ### Step 1 — `ignore` first (the claim, not a class choice)
 
 `ignore` claims **"this is not a real defect"** — a false positive or a

package/skills/review-perf/SKILL.md

@@ -2,7 +2,7 @@
 name: review-perf
 user-invocable: false
 version: 1.2.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal performance review pass of the agentic-workflow review pack — composed

package/skills/review-plan/SKILL.md

@@ -3,7 +3,7 @@ name: review-plan
 user-invocable: true
 version: 1.7.0
 argument-hint: <NN-slug | fix-N | path/to/SPEC.md> [--adversarial N]
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Independent read-only review of a frozen Engineering plan before execution, in a

package/skills/review-security/SKILL.md

@@ -2,7 +2,7 @@
 name: review-security
 user-invocable: false
 version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal security review pass of the agentic-workflow review pack — composed

package/skills/review-seo/SKILL.md

@@ -2,7 +2,7 @@
 name: review-seo
 user-invocable: false
 version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal SEO review pass of the agentic-workflow review pack — composed

package/skills/review-spec/SKILL.md

@@ -3,7 +3,7 @@ name: review-spec
 user-invocable: true
 version: 1.8.0
 argument-hint: <NN-slug | path/to/SPEC.md>
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Independent read-only review of a frozen Product half before engineering

package/skills/review-verify/SKILL.md

@@ -2,7 +2,7 @@
 name: review-verify
 user-invocable: false
 version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal run-it verification review pass of the agentic-workflow review pack —

package/skills/triage-issue/SKILL.md

@@ -3,7 +3,7 @@ name: triage-issue
 user-invocable: true
 version: 2.8.0
 argument-hint: <issue-number> [more issue numbers…] | <audit-id> F<k> [F<j>…] | --prioritize-now <unit> F<k> [F<j>…]
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Verify an issue, persisted audit finding, or unresolved review finding against

package/skills/verification-contract/SKILL.md

@@ -2,7 +2,7 @@
 name: verification-contract
 user-invocable: false
 version: 1.3.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal contract: one compact frozen ACCEPTANCE.md per delivery unit, its

package/skills/workflow-status/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: workflow-status
 user-invocable: true
-version: 3.7.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+version: 3.8.1
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 argument-hint: "[--json-only] [--last-envelope <json|path>]"
 description: >

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

@@ -9,10 +9,11 @@ placement per the installed `orchestration-envelope` skill. The
 states** (the schema package needs no release):
 
 - `CLEAN` → `state: OK` (the sensor default when the substrate is usable).
-- A missing or non-frozen repository-state ledger is a run-scoped substrate
-  gate and overrides the crash-recovery state with `state: BLOCKED`; the
-  blocker and concrete discovery/resolution command are emitted before
-  readiness data.
+- `draft`, `contradicted`, or `resolved` repository-state ledger is a
+  run-scoped substrate gate and overrides the crash-recovery state with
+  `state: BLOCKED`; the blocker and concrete discovery/resolution command
+  are emitted before readiness data.
+  An absent ledger is a non-blocking notice, not a blocker.
 - `RESUMABLE` → `state: CONTINUE`, `next.recommended` = the resume command
   from the decision table.
 - `AMBIGUOUS` → `state: NEEDS_INPUT`, `needs_input.question` = what is

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

@@ -12,12 +12,13 @@ the JSON and interprets it.
 
 Read `docs/workflow/REPOSITORY_STATE.md` when present and always emit
 `detail.repository_state: {status, snapshot_id, source_revision}`. Before
-readiness classification, if the ledger is missing, `draft`, `contradicted`, or
+readiness classification, if the ledger is `draft`, `contradicted`, or
 `resolved`, add a run-scoped `substrate` blocker, set the envelope state to
 `BLOCKED`, leave `startable_now` empty, and set `next.recommended` to
-`/discover-repository-state` for missing/non-frozen state or
-`/resolve-repository-state <contradiction-id>` for `contradicted` state. The
-sensor remains read-only; it never edits or resolves the ledger. Conflicting
+`/discover-repository-state` for non-frozen state or
+`/resolve-repository-state <contradiction-id>` for `contradicted` state.
+An absent ledger emits a non-blocking substrate notice instead of a blocker.
+The sensor remains read-only; it never edits or resolves the ledger. Conflicting
 live evidence against a frozen ledger remains a contradiction candidate.
 
 3. **Urgency labels (`detail.urgent`) — labels-only, presence-only, never

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

@@ -83,8 +83,9 @@ mechanized.*
 
     A row is **open** under the router's own predicate (`scripts/unit-route.mjs`
     `isOpen`), never a re-derived one: `folded: yes`, `—`, `-`, `n/a` and an empty
-    cell all close it. The id shapes `VF-<n>` (a finding's verification mark) and
-    `REVIEW-RAN` (a review mark) are **never** findings — a ledger pads a mark row
+    cell all close it. The id shapes `VF-<n>` (a finding's verification mark),
+    `REVIEW-RAN` (a review mark) and `GATE-RAN` (a gate-run mark) are **never**
+    findings — a ledger pads a mark row
     with empty cells, so it reaches the row parser looking like an open finding and
     would otherwise project a suggestion for a merged unit. A **decision-required**
     open row contributes **nothing**: it outranks the fold in the route table (which