@gtrabanco/pi-agentic-workflow 0.30.0 → 0.34.0

package/skills/unit-lane/references/MEMORY.md

@@ -0,0 +1,179 @@
+# Memory protocol — save and recall at unit boundaries
+
+Engram is this workflow's required cross-session memory substrate (owner
+decision 2026-09-24, feature 66). **Required substrate is not a hard
+dependency:** the committed docs stay authoritative, and a memory layer that is
+down is reported once and recorded — it never blocks a unit.
+
+This file is the protocol's single home. `execute-phase` and `log-session` carry
+a thin instruction plus a pointer here; they never restate it.
+
+## 1. Probe before the first memory read
+
+Run the bounded health probe once per session, before the first read:
+
+```sh
+agentic-workflow memory probe        # human block
+agentic-workflow memory probe --json # memory-probe@1 verdict
+```
+
+It is bounded (4 s / 10 s per check, 30 s ceiling), writes nothing, issues no
+MCP tool call, and **always exits 0**. Paste its verdict into the unit doc's
+Evidence section — one row, `verified-by` naming the session:
+
+- `ok` → memory is trustworthy for this session.
+- `degraded` → say **once** which checks failed, record the verdict, and keep
+  working. Never re-probe in a loop, never ask the user to fix it first.
+
+A `degraded` verdict is an answer, not a blocker: the degraded path in §7 is the
+documented response.
+
+## 2. Boundary saves — what, when, and under which key
+
+Save at **three boundaries**, always under a stable per-unit topic key:
+
+| Boundary | topic_key | Payload |
+|---|---|---|
+| unit start (after triage) | `unit/<NN-slug>/doc` | goal, the numbered acceptance criteria verbatim, the triaged step list |
+| each phase transition | `unit/<NN-slug>/doc` | the phase id, what it changed, its Evidence outcome, new discoveries |
+| unit close | `unit/<NN-slug>/doc` | final Evidence outcomes, decisions taken, the gotchas worth recalling |
+
+One payload, four parts — the same four a later session needs to resume without
+re-reading the docs:
+
+```text
+memory-payload@1
+goal:    <one line — the unit's objective>
+ac:      1. <numbered AC verbatim, one per line>
+evidence: <phase> <command> → <exit/digest> → <outcome>
+learned: <gotcha, edge case, or decision a fresh session would get wrong>
+```
+
+Call `mem_save` with `topic_key: "unit/<NN-slug>/doc"` and an explicit
+`project`; on a write surface that exposes `session_id`, pass it too (§5). Later
+boundaries reuse the same `topic_key` so the record **upserts** instead of
+fragmenting into one row per phase.
+
+**What is saved is a summary for recall, never the artifact.** The unit doc, its
+Evidence rows and `docs/LOGS.md` stay authoritative; a memory record that
+disagrees with them is wrong by definition.
+
+## 3. Recall — the fixed order
+
+Resume in this order, and stop as soon as the unit is reconstructable:
+
+1. **`mem_context`** — scoped explicitly (`project: "<name>"`, and `scope` when
+   you mean one).
+2. **`mem_search`** — a scoped search with an **explicit `project`**. Never rely
+   on an omitted selector for a global read; a default is not a decision.
+3. **One retry** — if the project-scoped search misses, retry **once** with
+   **`all_projects: true`** passed explicitly. A second miss is a miss.
+4. **`mem_get_observation`** — fetch the full untruncated body of the hit that
+   matters.
+5. **Read the unit doc** and reconcile: the file wins on every conflict, and the
+   difference is worth recording as a discovery (§2 `learned:`).
+
+Only when `mem_context` and both searches miss does a fresh session fall back to
+reading the docs cold — and that fallback is recorded, because it means the
+recall path failed, not that nothing was ever saved.
+
+When the cwd is ambiguous (several repos under it), call **`mem_current_project`**
+and navigate by its `available_projects`: pick the matching project explicitly
+rather than letting an ambiguous cwd decide. An ambiguous answer is never
+resolved by guessing.
+
+## 4. Keyword-bound recall — the disclosed ceiling
+
+Engram's recall is **keyword-bound** (FTS5 over stored text, no vectors). Two
+consequences are obligations, not trivia:
+
+- **A miss is not evidence that knowledge was never saved.** It means the query
+  did not hit the stored terms. Rephrase with the unit's own vocabulary (slug,
+  AC wording, file paths) before concluding anything is absent.
+- **What you save must be searchable later.** Save the words a future session
+  will search for — the unit slug, the phase id, the failing command, the file
+  path — not a paraphrase.
+
+Hybrid FTS5+vector recall is Engram's own direction (#192), never built here.
+
+## 5. Session attribution — explicit on every write, on the surface that carries it
+
+Every write must be **attributed to one known session**, never to whichever
+session a machine happens to resolve. On a box with several active runtime
+sessions an unresolved attribution fails closed and the write is lost — the one
+outcome this protocol exists to prevent (the health probe's
+`session-ambiguity` check reads exactly this signal, §1).
+
+Which parameter carries that attribution depends on the surface in front of you:
+
+| Write surface | How the session is carried | What you do |
+|---|---|---|
+| Engram's own MCP server (`engram mcp --tools=agent`) | its `mem_save`, `mem_save_prompt`, `mem_session_summary` and `mem_capture_passive` take a `session_id` argument | open the session (`mem_session_start`) and pass that id on **every** write |
+| a host whose memory tools expose no `session_id` (Pi's Engram provider binds the runtime session itself) | the provider stamps the session from the live runtime session and **refuses** when that identity is ambiguous or disagrees with the project | never write before the session is open, always pass an explicit `project` (and `cwd` when the directory could match more than one project), and treat an attribution refusal as a failed write — record it (§7), do not retry blind |
+
+On both surfaces the obligation is the same and the check is the same: **a write
+that cannot say which session it belongs to is a write that did not happen**.
+
+- `mem_session_start` opens the id (or the runtime session the provider binds to)
+  at unit start; the boundaries in §2 reuse it, and nothing is written before it.
+- **`mem_session_end` runs only on confirmed-stale ids** — ids you opened yourself
+  and know are finished. Never end an id a live session may still hold.
+- When `mem_session_summary` cannot resolve the project, the explicit
+  **project fallback** is the documented escape hatch: pass `project` by name
+  and the summary lands instead of being refused. Record the fallback when you
+  use it.
+- Passing a `session_id` to a tool that does not declare it is not "explicit
+  attribution", it is an invalid call. Read the tool's own parameter list when
+  the host offers more than one memory surface, and record which surface you used.
+
+## 6. The canonical split (D2)
+
+Both writers exist on purpose; neither mirrors the other.
+
+| Writer | Owns | Travels |
+|---|---|---|
+| `docs/LOGS.md` (`log-session`) | the human/team journal: what happened, for people | with git |
+| `mem_session_summary` / `unit/<NN-slug>/doc` | local decision and gotcha recall keyed by unit id | local only |
+
+Team memory travels with git; agent recall stays local. A double-write on
+purpose, recorded here so it is never mistaken for an accident.
+
+## 7. Degradation — recorded, never silent
+
+When the probe says `degraded` or a write fails:
+
+- **Local progress is preserved.** The unit doc, Evidence rows and commit are
+  the record; they never depend on memory.
+- **The mirror is marked pending explicitly** — one line in the Progress entry
+  or Evidence row saying the memory write is pending, so a later session knows
+  the gap exists and is not a "nothing was saved" conclusion.
+- **Unrelated safe work continues.** Never stop a unit for a mirror failure.
+- **Sync resumes when the layer answers** — retry the pending write at the next
+  boundary, not in a loop.
+- **Read both sides back.** After a write, read the file and the mirror; when
+  the versions are irreconcilable, keep both and surface the difference rather
+  than silently picking one.
+
+## Checklist (pass only if)
+
+- [ ] The probe ran once and its verdict is in Evidence (§1)
+- [ ] A save happened at unit start, at each phase transition, and at close (§2)
+- [ ] Every save was explicitly attributed: a `session_id` on a surface that
+  accepts one, otherwise an open session plus an explicit `project` — and it
+  named the unit's `topic_key` (§2, §5)
+- [ ] Recall followed the fixed order, with an explicit `project` and at most
+  one explicit `all_projects: true` retry (§3)
+- [ ] Any miss was treated as keyword-bound, not as absence (§4)
+- [ ] Any degradation was recorded as pending — never silent (§7)
+
+## Forbidden
+
+- Never let a memory verdict block a unit, or re-probe in a loop
+- Never rely on an omitted selector for a global read
+- Never write with unresolved session attribution — pass the `session_id` where
+  the surface takes one, and where it does not, never write before the session is
+  open (§5)
+- Never call `mem_session_end` on an id you did not open or cannot confirm stale
+- Never mirror `docs/LOGS.md` verbatim — the split is deliberate (§6)
+- Never treat a recall miss as proof nothing was saved
+- Never let a memory record override the committed artifact

package/skills/unit-lane/references/PLAN.md

@@ -166,7 +166,17 @@ name those files instead.
 - [ ] Each task names its validator (a backticked command plus its expected outcome)
 - [ ] Final task is verification (proves the whole unit works)
 - [ ] No task reaches into a future-phase concern (docs, release, migrations)
-- [ ] Phases labeled P1, P2, … (never S1, Step 1)
+- [ ] Phases labeled P1, P2, … — `#308`: `S#` is the requirement id (a spec),
+      `P#` is the phase label (a task); the two vocabularies never swap roles
+- [ ] Each requirement is cut from the request verbatim: numbered `S#` in
+      `## Specs`, one per distinct ask, with the requester's own words as its
+      quote and no requirement the request did not make
+- [ ] A later correction is appended under its own id (`S1a`) and leaves the
+      requirement it corrects untouched
+- [ ] Every task bullet names the `S#` it delivers on its `(Implements: …)` line
+- [ ] The `## Log` is opened with `L1` = the request verbatim, and later entries
+      append (never rewrite) in the `log-kind@1` vocabulary
+- [ ] `## Findings` is present and carries only OPEN rows (empty at plan time)
 - [ ] Both planning ledgers are cut (planning evidence + obligations), in the
       sizing rule's home, with stable ids
 

package/skills/unit-lane/references/RESEARCH.md

@@ -7,9 +7,9 @@ them, not the user. A blank or missing objective/scope is therefore a **document
 defect**: stop and repair the SPEC (`/unit-lane <unit>` — its §1 writes the
 objective/why/user-outcome) or re-triage. Never infer unit scope, and never
 turn a doc defect into a question the user cannot answer. A gap that survives
-the repair runs `node scripts/needs-input.mjs <unit-dir>`, pastes the
-`open-questions@1` block and stops, routed to `design` or `unit-lane` by the
-owning stage.
+the repair runs `bun scripts/needs-input.mjs <unit-dir>` (node fallback if bun is
+not installed), pastes the `open-questions@1` block and stops, routed to `design`
+or `unit-lane` by the owning stage.
 
 ## Purpose
 

package/skills/verification-contract/SKILL.md

@@ -1,15 +1,16 @@
 ---
 name: verification-contract
 user-invocable: false
-version: 1.4.3
+version: 1.5.0
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal contract: the acceptance artifact per delivery unit — legacy (pre-
   feature 61) units may carry a frozen `ACCEPTANCE.md` (binding if present);
   post-feature 61 units use the unit doc's `## Acceptance criteria` section as
-  the canonical acceptance source; the unit doc's `## Evidence` table serves as
-  the execution receipt. Consumed by planners, execute-phase, and review-change.
+  the canonical acceptance source; the unit doc's evidence carrier — `## Evidence`
+  table, or `## Log` `E` lines for a re-cut unit (#308) — serves as the execution
+  receipt. Consumed by planners, execute-phase, and review-change.
 ---
 
 # Verification Contract (internal)
@@ -63,9 +64,10 @@ v1` is needed: property/fuzz rides the existing `commands` class.
 
 ## Freeze and receipt
 
-The unit doc's `## Evidence` table is the execution receipt: each Evidence row
-records a validator command, its exit code or blob digest, output excerpt, and
-who verified it. A frozen criterion's receipt is the Evidence row for that
+The unit doc's own evidence carrier is the execution receipt: the `## Evidence`
+table for a legacy-shape unit, the `## Log` `E` lines for a re-cut one (#308). Each
+row or line records a validator command, its exit code or blob digest, output
+excerpt, and who verified it. A frozen criterion's receipt is the Evidence row for that
 criterion — exact match continues; missing/mismatched evidence stops before
 edits:
 
@@ -122,4 +124,4 @@ semantics are verified against authoritative documentation **before a test encod
 
 ## Done when
 
-Execution receipt (unit doc `## Evidence` table for post-feature 61 units; legacy `ACCEPTANCE.md` manifest binding-if-present) + named validators + literal quality floor; executor and reviewer evaluate identical evidence.
+Execution receipt (unit doc `## Log` `E` lines for a re-cut unit, `## Evidence` table for a post-feature 61 one; legacy `ACCEPTANCE.md` manifest binding-if-present) + named validators + literal quality floor; executor and reviewer evaluate identical evidence.

package/skills/workflow-status/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: workflow-status
 user-invocable: true
-version: 3.9.2
+version: 3.9.4
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 argument-hint: "[--json-only] [--last-envelope <json|path>] [--compact]"
@@ -69,7 +69,9 @@ bytes on a mature repo); the exact keep/drop set is in
 Per the agent guide's **Workflow conventions** + **documentation map**. The
 script reads what THIS skill needs (`docs/features/ROADMAP.md`, the fix index
 `docs/fix/README.md`, every in-flight feature folder's `TASKS.md` +
-`progress.md` + `review-findings.md`, and `docs/workflow/REPOSITORY_STATE.md`);
+`progress.md` and its findings carrier — `SPEC.md` `## Findings` + `## Log` for a
+migrated unit (issue #308), `review-findings.md` for a legacy one — and
+`docs/workflow/REPOSITORY_STATE.md`);
 read them yourself only to interpret a field the script emitted.
 
 ## Progressive loading — fixed sensor route

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

@@ -104,7 +104,9 @@ Exactly two fields change:
   `in-progress` stays in both modes, so `detail.startable_now` and
   `detail.blocked_units` keep naming every unit either way.
 - `findings.fix_now[].route`: the reviewer's multi-paragraph evidence memo becomes
-  `...(N char evidence, see the unit review-findings.md)`, keeping the original
+  `...(N char evidence, see the unit review-findings.md)` for a legacy carrier and
+  `...(N char evidence, see the unit SPEC.md ## Findings)` for a migrated one (#308),
+  keeping the original
   length visible. `id`, `file`, `axis`, `severity`, `class` and `suggested_tier`
   are untouched, and the memo is on disk in the unit's `review-findings.md`, which
   is where the fold reads it.