@gtrabanco/pi-agentic-workflow 0.30.0 → 0.34.0

package/dist/settings/console.js

@@ -650,38 +650,84 @@ function describeRouting(file) {
     ];
     return routes.join(" · ");
 }
+/**
+ * The canonical write order for a config file. `dirty()` compares the cleaned
+ * draft against the cleaned file as JSON text, so the order is part of the
+ * contract: the same keys written in a different order would read as an edit.
+ * Keys outside this list are appended in the draft's own order, so a key the
+ * console never prompts for still survives the save (F4).
+ */
+const KEY_ORDER = [
+    "default",
+    "commands",
+    "onUnavailableRoute",
+    "onSettle",
+    "pathProtection",
+    "advance",
+    "recommendedModels",
+    "memory",
+    "profiles",
+    "profileOrder",
+    "profileFallback",
+];
 /**
  * Keep everything the file held or the operator set; drop only what says nothing
  * (an empty route). Eliding by VALUE — treating an explicit `inherit` or `stop` as
  * absent because a shipped default happens to agree — silently discards the only
  * two moves that matter at project scope: switching a command off under a global
  * route, and re-arming fail-closed over a global `inherit` (F4).
+ *
+ * The copy is driven by the draft's OWN keys, not by a list of the keys this
+ * console edits. Enumerating them silently deleted every valid key the console
+ * never prompts for — `memory` (the Engram consent switch, feature 66 AC3),
+ * `pathProtection` and `advance` — so an opt-in written by hand vanished on the
+ * next save with no message and no error (F4/VF-4). A key the parser accepted is
+ * never a key this function may drop.
  */
 function clean(draft) {
-    const file = {};
-    if (draft.default && Object.keys(draft.default).length > 0)
-        file.default = { ...draft.default };
-    const commands = {};
-    for (const [name, route] of Object.entries(draft.commands ?? {})) {
-        if (Object.keys(route).length > 0)
-            commands[name] = { ...route };
-    }
-    if (Object.keys(commands).length > 0)
-        file.commands = commands;
-    if (draft.onUnavailableRoute)
-        file.onUnavailableRoute = draft.onUnavailableRoute;
-    if (draft.onSettle)
-        file.onSettle = draft.onSettle;
-    if (draft.recommendedModels !== undefined)
-        file.recommendedModels = draft.recommendedModels;
-    if (draft.profiles && Object.keys(draft.profiles).length > 0) {
-        file.profiles = structuredClone(draft.profiles);
+    const kept = {};
+    for (const [key, value] of Object.entries(draft)) {
+        if (value === undefined)
+            continue;
+        if (key === "commands") {
+            const commands = {};
+            for (const [name, route] of Object.entries((value ?? {}))) {
+                if (route && Object.keys(route).length > 0)
+                    commands[name] = { ...route };
+            }
+            if (Object.keys(commands).length > 0)
+                kept.commands = commands;
+            continue;
+        }
+        if (key === "profiles") {
+            const profiles = {};
+            for (const [name, profile] of Object.entries((value ?? {}))) {
+                if (profile && Object.keys(profile).length > 0)
+                    profiles[name] = structuredClone(profile);
+            }
+            if (Object.keys(profiles).length > 0)
+                kept.profiles = profiles;
+            continue;
+        }
+        if (Array.isArray(value)) {
+            // `profileOrder` is the only list at this level: an empty order says
+            // nothing, so it is elided exactly as the empty route was.
+            if (value.length > 0)
+                kept[key] = [...value];
+            continue;
+        }
+        if (typeof value === "object" && value !== null && Object.keys(value).length === 0)
+            continue;
+        kept[key] = typeof value === "object" && value !== null ? structuredClone(value) : value;
     }
-    if (draft.profileOrder && draft.profileOrder.length > 0) {
-        file.profileOrder = [...draft.profileOrder];
+    const file = {};
+    for (const key of KEY_ORDER) {
+        if (key in kept)
+            file[key] = kept[key];
     }
-    if (draft.profileFallback && Object.keys(draft.profileFallback).length > 0) {
-        file.profileFallback = { ...draft.profileFallback };
+    for (const key of Object.keys(kept)) {
+        if (!(key in file))
+            file[key] = kept[key];
     }
     return file;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.30.0",
+  "version": "0.34.0",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",

package/skills/audit-pr/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: audit-pr
 user-invocable: true
-version: 5.6.2
+version: 5.6.3
 argument-hint: <pr-number> (optional — defaults to the current branch's PR)
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT

package/skills/audit-pr/references/03_AUDIT_PROCESS.md

@@ -29,8 +29,9 @@
    - **BLOCKED** — one or more gates fail; output the ranked blocker list.
 6. **Persist blockers to the fold ledger (BLOCKED verdict only).** Every blocker
    on a **BLOCKED** verdict is, by definition, fix-now — merge is gated on it.
-   Append each to the unit's fix-now fold ledger `review-findings.md` (same
-   location and fixed schema
+   Append each to the unit's fix-now fold ledger — its `## Findings` section for
+   a migrated unit (issue #308), `review-findings.md` for a legacy one; probe the
+   doc first and write to exactly one carrier (same fixed schema
    `| id | file:line | axis | severity | class | route | folded |` as
    `review-change`'s persist step) — the **same ledger**, not a separate one
    (D4: the fold cycle consumes one list). **Merged unit → no write** — check

package/skills/execute-phase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: execute-phase
 user-invocable: true
-version: 6.1.0
+version: 6.2.2
 argument-hint: <NN-slug> [P<k>|step] [--max-attempts N] [--force]
 allowed-tools: [Bash, Read, Edit, Write, MultiEdit]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
@@ -35,7 +35,8 @@ done:
 
 ```
 ✓ Required user inputs were answered concretely (not defaulted). Nothing here
-  is inferred: a gap runs `node scripts/needs-input.mjs <unit-dir>` and the
+  is inferred: a gap runs `bun scripts/needs-input.mjs <unit-dir>` (node fallback
+if bun is not installed) and the
   `open-questions@1` block is pasted, then the run stops.
 ✓ Triage verified — unit doc Evidence section header matches
   `bun scripts/unit-route.mjs --triage <slug>` output block (PREFLIGHT.md)
@@ -44,6 +45,8 @@ done:
 ✓ Evidence rows updated (command → exit/digest → output → verified-by)
 ✓ Progress log updated with a dated `YYYY-MM-DD HH:MM` entry that names the
   phase id (what, commit, next)
+✓ Memory boundary ran — the phase's outcome saved under `unit/<NN-slug>/doc`,
+  or the mirror marked pending when the layer is degraded
 ✓ Diff guard passed (on implement steps) — see `diff-guard` in PREFLIGHT.md
 ✓ → Next: block printed as the absolute last output
 ```
@@ -64,8 +67,8 @@ This skill **never interviews**. It reads its inputs — the unit doc's `Tasks`,
 one is a **gap**, resolved in one fixed order and never by inference:
 **(0) provenance** (search the repo's own docs and record where) →
 **(1) research** (2–3 concrete options with trade-offs; asking for more research
-is a legitimate answer) → **(2) halt**: run `node scripts/needs-input.mjs
-<unit-dir>`, paste the `open-questions@1` block verbatim, stop. Interactive the
+is a legitimate answer) → **(2) halt**: run `bun scripts/needs-input.mjs
+<unit-dir>` (node fallback if bun is not installed), paste the `open-questions@1` block verbatim, stop. Interactive the
 block is the pause point, unattended it is a hard fail. Grammar and exit codes:
 `orchestration-envelope`'s `references/TURN_CONTRACT.md` §Open questions.
 
@@ -79,9 +82,13 @@ path-protection checkpoint.
 ## Step 0 — Discover the project
 
 Per the agent guide's **Workflow conventions** + **documentation map**, read the
-unit doc at `docs/features/<NN-slug>/SPEC.md`. Verify it carries `## Tasks` (P1…Pn),
-`## Evidence`, and `## Progress` sections. If absent, the unit is not ready —
-stop and suggest `unit-lane` triage first.
+unit doc at `docs/features/<NN-slug>/SPEC.md`. Verify it carries `## Tasks` (P1…Pn)
+**and the receipt sections of the shape it is written in** (#308 accepts both):
+the legacy shape carries `## Evidence` + `## Progress log`, a re-cut unit doc carries
+`## Specs`, `## Findings` + `## Log` (its evidence and gate runs are `E`/`G` log
+lines, its progress is `P` lines). If neither pair is present, the unit is not ready —
+stop and suggest `unit-lane` triage first. `scripts/unit-route.mjs` resolves the
+shape; never judge a re-cut unit by the legacy headings and stop it.
 
 ## Process
 
@@ -136,7 +143,14 @@ names before implementation), then green. UI/adapter glue may test after.
    output (≤2 lines) | verified-by |`. Append to the Evidence section.
 3. **Progress log**: append a dated entry —
    `YYYY-MM-DD HH:MM — <what was done> → <commit sha> — next: <what is next>`.
-4. **Commit**: `git add <changed files>` then `git commit -m "<type>(<scope>):
+4. **Memory boundary** — this step is a phase transition. Follow
+   [the memory protocol](../unit-lane/references/MEMORY.md): before the first
+   memory read run `agentic-workflow memory probe` once and record its verdict
+   in Evidence; after the step, save the phase id, what it changed, its Evidence
+   outcome and any discovery under `topic_key: "unit/<NN-slug>/doc"`, an explicit
+   `project` and explicit session attribution (§5). A `degraded` verdict is
+   recorded and the mirror marked pending — it never blocks the step.
+5. **Commit**: `git add <changed files>` then `git commit -m "<type>(<scope>):
    <step-summary>"` — run it, paste the SHA.
 
 ### 6. Red gate (repair loop)

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

@@ -52,8 +52,10 @@ Something forbidden looks necessary → stop, record it in `decisions.md` or
 
 ## Step completion gate
 
-The step completion gate verifies that Evidence rows are complete for the
-step's acceptance criteria, the unit doc is committed clean, and the diff guard
+The step completion gate verifies that the step's acceptance criteria have
+complete evidence in the unit's own carrier — the `## Evidence` table rows for a
+legacy-shape unit, `## Log` `E` lines (command, exit, ≤2 lines of output) for a
+re-cut one (#308) — that the unit doc is committed clean, and that the diff guard
 (if applicable) passed. The mark's shape, ownership, and reuse rule are
 declared in `LEDGERS.md` (§gate-ran@1).
 
@@ -76,7 +78,8 @@ GATE-RAN | HEAD <40-hex sha> | <cmds> | exit <code>
 ✓ Verification gate green — type-check + tests + build actually RUN (paste exit
   status), never assumed
 ✓ Every task of this step checked off in the unit doc's `Tasks` section, each
-  mapped to an Evidence row (code path or test name)
+  mapped to an Evidence row (legacy shape) or an `E` log line (re-cut shape) —
+  code path or test name
 ✓ Tests updated/added for every behavior this step changed
 ✓ Tests-first red run recorded (core/domain + orchestration steps, n/a for
   test-after UI/adapter steps) — the failing first run's command, exit status,
@@ -88,10 +91,12 @@ GATE-RAN | HEAD <40-hex sha> | <cmds> | exit <code>
   consumers)
 ✓ Architecture doc respected (dependency directions, layer boundaries)
 ✓ Architectural invariants preserved or backed by an explicit recorded decision
-✓ Evidence rows complete for the step's ACs — unit doc committed clean
-  (one dated `YYYY-MM-DD HH:MM` Progress entry, all Evidence rows current)
-✓ Docs COMMITTED with the step — the unit doc carries all required sections
-  (Tasks, Evidence, Progress, References); no orphan files remain
+✓ The step's ACs have complete evidence in the unit's carrier — unit doc committed
+  clean (one dated `YYYY-MM-DD HH:MM` Progress entry or `P` log line, all evidence
+  current)
+✓ Docs COMMITTED with the step — the unit doc carries all required sections of its
+  own shape (Tasks + Evidence + Progress + References for legacy; Specs + Tasks +
+  Findings + Log + References for re-cut); no orphan files remain
 ```
 
 A step that cannot tick every box is **not done**: fix within the step's
@@ -123,8 +128,9 @@ planned work, and inference never prove implementation. A present ledger whose
 status is `draft`, `contradicted`, or `resolved` stops implementation and routes
 to discovery or resolution first. If no ledger exists, inspect the repository
 directly and record `n/a: no normalized repository state`; NRS is optional.
-Unit doc evidence rows (Evidence, Progress) are the single source of truth
-for step completion — no separate ACCEPTANCE.md, progress.md, or TASKS.md.
+Unit doc evidence is the single source of truth for step completion — the
+`## Evidence`/`## Progress log` sections of a legacy-shape doc, the `## Log` lines of
+a re-cut one (#308) — never a separate ACCEPTANCE.md, progress.md, or TASKS.md.
 
 ## Architectural invariants
 

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

@@ -24,10 +24,12 @@ findings end up "solved" locally but absent from the merged PR:
 ✓ Gate RUN and green (exit codes pasted)
 ✓ Never edit an existing test's expectation to match behaviour — a setup
   repair keeps assertions at least as strong and never touches expectations
-✓ Evidence rows updated where the finding touched them (the finding's row
-  in the unit doc's Evidence ledger flipped `folded: no → yes` — the one and
-  only state transition, `ledger-ownership@1` / `fold-findings:folded-flag`
-  is the sole writer)
+✓ Evidence rows updated where the finding touched them, in the unit's own findings
+  carrier: a legacy row flipped `folded: no → yes`; a migrated unit's row leaves
+  `## Findings` and its fold is a `## Log` `F` line naming the fold commit — that
+  carrier has no `folded` column to flip (#308). Either close is the one and only
+  state transition, and `ledger-ownership@1` / `fold-findings:folded-flag` is the
+  sole writer of it
 ✓ Progress log advanced with a dated entry noting the fold
 ✓ `git add` + `git commit` RUN (sha pasted) — e.g.
   `fix(<scope>): fold review findings — <summary>`
@@ -56,8 +58,9 @@ No auto-merge. Explicit `P<k>` stops after one step; omitted-step mode gates
 and commits every remaining step before the same final review.
 ## Gate-run marks (gate-ran@1)
 
-Every verification gate this cycle runs records a `GATE-RAN` mark in the unit
-doc's Evidence section at the head it actually ran:
+Every verification gate this cycle runs records a `GATE-RAN` mark at the head it
+actually ran — a row in the legacy `review-findings.md`, a `## Log` `G` line for a
+re-cut unit (#308):
 `GATE-RAN | HEAD <40-hex sha> | <cmds> | exit <code>`. A green run is recorded;
 a red run is also recorded (exit code ≠ 0 is evidence, not silence). Any skill
 may consume a green mark only at the identical HEAD — a changed head re-runs
@@ -70,5 +73,5 @@ the gate. The recorders are `execute-phase:gate-ran-marks` and
 When the final triaged step closes: mark the unit done, push the branch, and
 open the PR with `gh pr create` (per the project's Workflow conventions) —
 regardless of the review still to come. The PR body carries the unit doc's
-Evidence section as its verification record and closes the unit's tracked
-issues via `Closes #N`.
+verification record (its `## Evidence` rows, or a re-cut unit's `## Log` `E`/`G`
+lines) and closes the unit's tracked issues via `Closes #N`.

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

@@ -125,7 +125,10 @@ block text, no-forgery and legacy detail:
 Consume `skills/verification-contract/SKILL.md`. For a current-format unit,
 the Evidence section in the unit doc **is** the acceptance manifest — each
 acceptance criterion has a corresponding Evidence row with command, exit/digest,
-and output. No sibling file; the unit doc's Evidence section header carries the
+and output. A re-cut unit (#308) has no Evidence section by design: its acceptance
+manifest is `## Specs`, and each criterion's receipt is a `## Log` `E` line; the
+gate below reads that carrier instead, and never stops a migrated unit for lacking
+a section its own template retired. No sibling file; the unit doc's Evidence section header carries the
 last-reviewed sha. The unit doc's triage block (pasted verbatim from
 `scripts/unit-route.mjs --triage`) is the step authority: `execute-phase` runs
 only what the triage block demands.
@@ -136,8 +139,9 @@ only what the triage block demands.
 - Missing/mismatched Evidence (unit doc has been edited since last execution)
   → print the verification contract's fixed `EVIDENCE GATE` block and stop.
   `--force` never bypasses a changed acceptance state.
-- Unit with no Evidence section → the unit doc template was incomplete;
-  create the section before proceeding.
+- Unit with no Evidence section and no `## Log` → the unit doc template was
+  incomplete; create the section its shape requires before proceeding. A doc with
+  `## Log` is the re-cut shape: its `E`/`G` lines are the rows, never a gap.
 
 Run this check before each step in whole-unit mode. The executor may add tests
 but may not narrow acceptance criteria, weaken assertions, or edit the Acceptance

package/skills/fold-findings/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: fold-findings
 user-invocable: true
-version: 1.9.0
+version: 1.9.2
 argument-hint: [finding-id …]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -49,19 +49,30 @@ postpone/wontfix/promote/documented-tradeoff rows; those belong to `/triage-issu
 
 Per Workflow conventions, read:
 
-1. The unit's `review-findings.md` under `docs/features/<NN>-<slug>/` or
-   `docs/fix/<n>-<topic>/`; schema is owned by `review-change`/`audit-pr`:
-
-   ```
-   | id | file:line | axis | severity | class | route | folded |
-   ```
-
-   After `VERDICT: BLOCKED`, append missing rows (`class: fix-now`, `folded: no`,
-   next free `Fn`, dedupe `file:line`+axis), commit as
-   `docs(<unit>): reconstruct fold ledger from audit-pr blockers`, then fold;
-   never report “no findings”.
-2. Queue `folded: no` rows; explicit IDs restrict it and leave other rows
-   untouched. Group by root cause, verifier and rollback boundary.
+1. The unit's findings carrier: a migrated unit (issue #308) keeps its OPEN rows
+   in its own `SPEC.md` under `## Findings`, with folded history and marks as
+   `## Log` lines; a legacy unit keeps `review-findings.md` under
+   `docs/features/<NN>-<slug>/` or `docs/fix/<n>-<topic>/`. Probe the doc first and
+   fall back to the file — a unit with the section never reads both. Each carrier
+   has **its own** schema, owned by `review-change`/`audit-pr` and stated for both
+   shapes in `pre-execution-review/references/LEDGERS.md`:
+
+   - legacy (7 cols): `\| id \| file:line \| axis \| severity \| class \| route \| folded \|`
+     — closing a row flips `folded: no → yes`, and this skill is that flip's sole writer
+   - migrated (6 cols, `findings-table@1`): `\| id \| S# / file:line \| axis \| severity \|
+     class \| route \|` — every row it holds is OPEN; closing one **deletes the row** and
+     appends a `## Log` `F` line naming the fold commit. There is no `folded` column to
+     flip, and `class` here is the repairing owner (`product`/`plan`/`source`/
+     `environment`/`runtime`), not a disposition.
+
+   Never write one carrier's row into the other's grammar. After `VERDICT: BLOCKED`,
+   append missing rows in the carrier's own schema (next free `Fn`, dedupe
+   `file:line`+axis; legacy `class: fix-now`, `folded: no`), commit as
+   `docs(<unit>): reconstruct fold ledger from audit-pr blockers`, then fold; never
+   report “no findings”.
+2. Queue the carrier's open rows — a legacy `folded: no` row, a migrated row of
+   `## Findings` (all of them are open); explicit IDs restrict the queue and leave
+   other rows untouched. Group by root cause, verifier and rollback boundary.
 3. The project's verification gate and forge CLI (use the declared forge).
 4. Whether the branch has an open PR; this decides immediate push after commit.
 
@@ -126,7 +137,7 @@ conclusion the already-run router printed, never the invocation itself: on
 `route: replan` the planner command it printed — `/unit-lane <slug>` for a
 feature unit or `/unit-lane --fix <n>` for a fix unit; on `route: decision` stop
 and surface the decision to the user, never a planner. `<unit>` is the bare folder number or the full slug (both resolve). The invocation
-`node scripts/unit-route.mjs <unit>` is the discovery step the fold already
+`bun scripts/unit-route.mjs <unit>` (node fallback if bun is not installed) is the discovery step the fold already
 ran; it is never the recommendation.
 
 **Freeze-batch (product owner present).** Any taken `fix-now` row whose `Route`
@@ -212,8 +223,8 @@ decision to skip.
 
 | Batch state | Branch | `→ Next:` (consumer) |
 |---|---|---|
-| freeze-batch (≥ 1 product-owned row) | `PRODUCT-ROUTE` | `/unit-lane <slug>` (feature) or `/unit-lane --fix <n>` (fix) when the router concludes `product` — the lane repairs the half through its `design` step, its `review` step re-judges it; the conclusion printed by `node scripts/unit-route.mjs <unit>` (discovery step the fold already ran) |
-| freeze-batch (≥ 1 replan-class row) | `REPLAN-ROUTE` | `/unit-lane <slug>` (feature) or `/unit-lane --fix <n>` (fix) when the router concludes `replan` — user confirms, the lane's `plan` step appends the phases and its `review` step gates, then `/execute-phase` on this unit; on `route: decision` stop and surface the decision to the user — the conclusion printed by `node scripts/unit-route.mjs <unit>` (discovery step the fold already ran) |
+| freeze-batch (≥ 1 product-owned row) | `PRODUCT-ROUTE` | `/unit-lane <slug>` (feature) or `/unit-lane --fix <n>` (fix) when the router concludes `product` — the lane repairs the half through its `design` step, its `review` step re-judges it; the conclusion printed by `bun scripts/unit-route.mjs <unit>` (node fallback if bun is not installed; discovery step the fold already ran) |
+| freeze-batch (≥ 1 replan-class row) | `REPLAN-ROUTE` | `/unit-lane <slug>` (feature) or `/unit-lane --fix <n>` (fix) when the router concludes `replan` — user confirms, the lane's `plan` step appends the phases and its `review` step gates, then `/execute-phase` on this unit; on `route: decision` stop and surface the decision to the user — the conclusion printed by `bun scripts/unit-route.mjs <unit>` (node fallback if bun is not installed; discovery step the fold already ran) |
 | `all-repair-in-place` + docs-only + no folded row severity `high` + prior consumer skip decision | `RE-REVIEW-SKIPPED` | skip — consumer has explicitly decided to skip the re-review |
 | `all-repair-in-place` + docs-only + no folded row severity `high` | `RE-REVIEW-OPTIONAL` | `/review-change` (default, delta mode) — or the consumer's recorded skip decision |
 | empty batch (class `none`) | `RE-REVIEW-OPTIONAL` | `/review-change` by default — safe: the head is unchanged |

package/skills/fold-findings/references/FOLD_PROCESS.md

@@ -43,8 +43,10 @@
 
    | Condition over the taken batch | Batch class | Fold behavior |
    |---|---|---|
-   | ≥ 1 row with frozen class `replan-in-unit` or `decision-required` | `frozen (replan present)` | **freeze-batch** — nothing folds, no `folded: yes` flips, no commits; the receipt records the REPLAN-ROUTE and every retained (unfolded) row id; the loop stops; the consumer is the conclusion printed by `node scripts/unit-route.mjs <unit>` (discovery step the fold already ran), where `<unit>` is the bare folder number or the full slug (both resolve): on `route: replan` the planner command the router printed — `/unit-lane <slug>` (feature) or `/unit-lane --fix <n>` (fix) — the lane appends the phases and its `review` step gates, then `/execute-phase` on this unit; on `route: decision` stop and surface the decision to the user, never a planner |
-   | ≥ 1 row with frozen class `fix-now` whose `Route` cell begins `product owner`, `product-owned` or `owned by product` (head-anchored, identical to `scripts/unit-route.mjs`'s `PRODUCT_ROUTE` regex: `/^(?:product[- ]owner\|product[- ]owned\|owned by product)\b/i`, per `#293`) | `frozen (product owner present)` | **freeze-batch** — nothing folds, no `folded: yes` flips, no commits; the receipt records the PRODUCT-ROUTE and every retained (unfolded) row id; the loop stops; the consumer is the conclusion printed by `node scripts/unit-route.mjs <unit>`: `route: product` and the lane hand-off — `/unit-lane <slug>` (feature) or `/unit-lane --fix <n>` (fix) — the lane repairs the half, its `review` step re-judges it, then `/execute-phase` on this unit |
+   | ≥ 1 row with frozen class `replan-in-unit` or `decision-required` | `frozen (replan present)` | **freeze-batch** — nothing folds, no `folded: yes` flips, no commits; the receipt records the REPLAN-ROUTE and every retained (unfolded) row id; the loop stops; the consumer is the conclusion printed by `bun scripts/unit-route.mjs <unit>` (node fallback
+if bun is not installed) (discovery step the fold already ran), where `<unit>` is the bare folder number or the full slug (both resolve): on `route: replan` the planner command the router printed — `/unit-lane <slug>` (feature) or `/unit-lane --fix <n>` (fix) — the lane appends the phases and its `review` step gates, then `/execute-phase` on this unit; on `route: decision` stop and surface the decision to the user, never a planner |
+   | ≥ 1 row with frozen class `fix-now` whose `Route` cell begins `product owner`, `product-owned` or `owned by product` (head-anchored, identical to `scripts/unit-route.mjs`'s `PRODUCT_ROUTE` regex: `/^(?:product[- ]owner\|product[- ]owned\|owned by product)\b/i`, per `#293`) | `frozen (product owner present)` | **freeze-batch** — nothing folds, no `folded: yes` flips, no commits; the receipt records the PRODUCT-ROUTE and every retained (unfolded) row id; the loop stops; the consumer is the conclusion printed by `bun scripts/unit-route.mjs <unit>` (node fallback
+if bun is not installed): `route: product` and the lane hand-off — `/unit-lane <slug>` (feature) or `/unit-lane --fix <n>` (fix) — the lane repairs the half, its `review` step re-judges it, then `/execute-phase` on this unit |
    | all taken rows foldable, none replan-class | `all-repair-in-place` | fold as today (group → fix → gate → commit → flip) |
    | empty queue (zero findings taken) | `none` | receipt only |
 
@@ -60,7 +62,7 @@
    `DISPUTED <evidence → user decision>`; never edit classification or create an
    issue.
 9. **Replan.** If the smallest correct group exceeds a reviewable correction,
-   run `node scripts/unit-route.mjs <unit>` — its `route: replan` line prints the
+   run `bun scripts/unit-route.mjs <unit>` (node fallback if bun is not installed) — its `route: replan` line prints the
    planner command (`/unit-lane <slug>` for a feature, `/unit-lane --fix <n>` for
    a fix) that appends the proposed
    phases to the unit's SPEC. The `<unit>` argument accepts the bare folder number

package/skills/init-workspace/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: init-workspace
 user-invocable: true
-version: 4.1.0
+version: 4.2.0
 argument-hint: <target-dir>
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -78,7 +78,7 @@ Inspect the target dir (`[target-dir]`, default cwd) before touching anything:
 
 ## Progressive loading — bootstrap or upgrade, never both
 
-The reference allowlist is exactly the five linked paths below. Never invent or
+The reference allowlist is exactly the six linked paths below. Never invent or
 read another `references/` path. Step 0 selects exactly one route:
 
 **Hard rule for an existing Claude Code, Cursor, Copilot, or OpenCode
@@ -95,6 +95,10 @@ or portability unless the runtime platform has no named adapter at all.
   only. Its additive-only rule is absolute; do not replay bootstrap.
   The upgrade route loads [SERENA language servers](references/SERENA.md)
   for the additive provisioning step.
+- Provisioning Engram on a host with no pi package: read
+  [Engram provisioning](references/ENGRAM.md) — detect, ask, register or
+  instruct, report. Loaded by the bootstrap write route only (the pi package
+  provisions itself, feature 66).
 - No named adapter exists for the detected runtime platform: add
   [portability](references/PORTABILITY.md) only for that fallback. Claude Code,
   Cursor, Copilot, and OpenCode are named supported adapters; a missing adapter
@@ -133,6 +137,13 @@ loads exactly upgrade and skips bootstrap plus portability.
   auto-detected), a listed server that fails to start must be removed (one
   failure disables every server in the project), and LSP evidence stays
   TypeScript/JavaScript-only. Document verification is a script's job.
+- **Engram provisioning is ask-first, never assumed (feature 66).** Detect the
+  `engram` binary, ask before writing any host MCP config, write the absolute
+  path with the exact `mcp --tools=agent` argv, and report exactly what was
+  written. An existing `engram` declaration is never overwritten, and an absent
+  binary is a recorded residual — the documented install route is
+  `pi install npm:gentle-engram@latest`, never the CLI's own setup subcommand,
+  which keeps serving whatever version ran it until it is re-run.
 - **Retrieval index scaffold and git hooks are consent-gated (AC22).** The
   index surface — the committed `.agentic-workflow/index.json` config plus the
   three freshness hooks (`post-merge`, `post-checkout`, `post-rewrite`, all

package/skills/init-workspace/references/BOOTSTRAP_WRITE.md

@@ -34,7 +34,13 @@
    health check and render the fixed provisioning report. When no installer is
    available, offer only what the machine can perform and record the residual
    with its reason — the run completes either way.
-9. **Install accepted agent safety hooks.** Keep the canonical policy and
+9. **Offer Engram provisioning.** Load [ENGRAM](ENGRAM.md), detect the binary
+   and ask consent: register the `engram` MCP server (absolute path, exact
+   `mcp --tools=agent` argv) when the host has one, leave an existing
+   declaration untouched, and report exactly what was written. An absent binary
+   becomes a residual with the documented install route — never a failed run.
+   Skip this step when the pi package provisions the host itself.
+10. **Install accepted agent safety hooks.** Keep the canonical policy and
    fullauto wrapper at `.agentic-workflow/hooks/`. Seed the shipped
    path-protection policy at `.agentic-workflow/path-policy.json` and its doc
    page at `.agentic-workflow/path-protection.md`, beside the hooks — the
@@ -47,10 +53,10 @@
    an unknown payload, or an existing customized hook file becomes a residual,
    never a silent overwrite. Direct merges remain blocked; do not create a
    `.automerge` exception.
-10. **Offer the workflow skills.** Propose installing them:
+11. **Offer the workflow skills.** Propose installing them:
    `npx skills add gtrabanco/agentic-workflow` (note the SSH/local-path variant if
    the source is private). Don't install without a yes.
-11. **State that reviews are self-contained; offer optional extras.** The
+12. **State that reviews are self-contained; offer optional extras.** The
    workflow ships its **own internal review pack** (`review-code`,
    `review-security`, `review-verify`, `review-debt`, `review-design`,
    `review-a11y`, `review-brand`, `review-perf`, `review-seo`) — it installs
@@ -60,7 +66,7 @@
    under a short "Optional review extras" note so `review-change` and
    `product-audit` run them **in addition** — never as a dependency. Don't
    install anything without a yes.
-12. **Seed the urgency labels (feature 15, injection-safe urgency).** Create the
+13. **Seed the urgency labels (feature 15, injection-safe urgency).** Create the
    two capability-gated GitHub labels `triage-issue` owns and applies
    (`skills/triage-issue/SKILL.md` is the sole owner of the name/color
    vocabulary — this step only seeds it, never redefines it):
@@ -73,7 +79,7 @@
    forge is unavailable or the user declines forge setup, skip this step and
    list the two labels as a residual for the user to create manually later
    (never fail the whole scaffold on it).
-13. **Report.** List what was created, which placeholders still need human input,
+14. **Report.** List what was created, which placeholders still need human input,
    the companion skills recorded/installed, the urgency labels seeded (or
    skipped, with reason), and the next step:
    `discover-repository-state` → `/unit-lane` (or `workflow-status`) → catalog

package/skills/init-workspace/references/ENGRAM.md

@@ -0,0 +1,107 @@
+## Why this step exists
+
+The workflow's units save what they learned into Engram, the cross-session
+memory layer its memory protocol documents. On a host whose agent has no `pi`
+package to provision it (the pi package registers the server itself, feature
+66 P4), the target project has no memory layer at all unless this step offers
+one — so Engram provisioning is a **parity obligation**, not an optional extra:
+feature 66's approval is that the pi path registers it and every other host is
+offered the same thing ask-first.
+
+## What this file owns
+
+The **non-pi** half of Engram provisioning. It owns exactly four moves —
+detect, ask, provision-or-instruct, report — and nothing else. The workflow-side
+protocol (when units save, the recall order, the degraded path) is **not** here;
+it lives in `unit-lane`'s memory reference, which the skills that run units
+already load.
+
+## 1. Detect
+
+Look for the `engram` binary on `PATH` (`command -v engram`) and read its
+version (`engram --version`). Two outcomes matter:
+
+- **Present** — record the resolved path and the version fingerprint.
+- **Absent** — record it as a residual, and go to step 2 with the install
+  guidance below rather than silently skipping the step.
+
+Never write an MCP registration file for a binary that does not resolve: a
+registered-but-unstartable server fails every session after it, which is a worse
+default than an honest gap.
+
+## 2. Ask, then do exactly what was agreed
+
+This is a **consent-gated install** like every other in this skill. Ask one
+question — "register Engram as the project's memory layer?" — and act on the
+answer:
+
+| Answer | What you do |
+|---|---|
+| yes | write the MCP registration named in step 3 and report it verbatim |
+| no | write nothing, record it as a residual, finish the run normally |
+| not installed | offer the install route below, and provision **only** if the user then says yes |
+
+**The install route is `pi install npm:gentle-engram@latest`.** The CLI's own
+setup subcommand is **not** the documented route and must never be printed as an
+instruction: it pins whatever version ran it and keeps serving that version
+until it is re-run, so an updated binary can sit unused behind a stale
+registration (decision D3, 2026-10-21).
+
+## 3. What "register" means on a non-pi host
+
+There is no `pi.registerMcpServer` here, so the registration is a **declared
+file** the host agent reads. Write the server into that host's own MCP config
+(the agent's documented MCP surface), never into a file the host does not read:
+
+```json
+{
+  "mcpServers": {
+    "engram": { "command": "<absolute path to engram>", "args": ["mcp", "--tools=agent"] }
+  }
+}
+```
+
+**Rules:**
+
+- **Absolute path, never a bare name** — the host's `PATH` at load time is not
+  the shell's.
+- **Args are exactly** `mcp` `--tools=agent`. A different argv changes which
+  tools the server exposes.
+- **Never overwrite a server the user already declared** under the name
+  `engram` — a declared server wins over anything this step would add. Report
+  that you found it and left it alone.
+- **Additive and idempotent** — a second run with the same content writes
+  nothing and says so.
+
+## 4. Report exactly what was written
+
+Every outcome ends in a report the user can read back:
+
+- **Registered** — the file path, the server name, and the exact `command` +
+  `args` written.
+- **Declined** — that nothing was written, and that the run continued.
+- **Binary missing** — that nothing was written, the install route verbatim, and
+  that it is recorded as a residual.
+- **Already declared** — the file that already carries it, and that it was left
+  untouched.
+
+"Report exactly what was written" is the same contract the Serena step follows;
+a provisioning step the user cannot read back is one they cannot trust.
+
+## Checklist (pass only if)
+
+- [ ] `engram` presence **and** version were detected (or absence recorded)
+- [ ] Consent was asked before any file was written — never assumed
+- [ ] The written server uses the absolute binary path and the exact argv
+- [ ] An existing `engram` declaration was left untouched and reported
+- [ ] A second run is a no-op
+- [ ] The closing report states what was written — or that nothing was
+
+## Forbidden
+
+- Never print the CLI's own setup subcommand as the install route
+- Never write an MCP config for an unresolved binary
+- Never overwrite an operator's existing `engram` declaration
+- Never let a memory gap fail the run — record it as a residual and continue
+- Never restate the unit-boundary save/recall protocol here; that is the lane's
+  memory reference