@gtrabanco/pi-agentic-workflow 0.26.0 → 0.31.0

package/skills/init-workspace/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: init-workspace
 user-invocable: true
-version: 4.0.3
+version: 4.2.0
 argument-hint: <target-dir>
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -26,7 +26,8 @@ raw placeholders.
   three-tier dispatch and stops with the dispatcher's `open-questions@1` block
   — against a scratch unit folder when no unit exists yet (§Consent).
 ✓ The adapted scaffold and repository-state ledger are written (or the merge/abort decision was asked) and remaining placeholders are listed
-✓ Nothing was installed or overwritten without an explicit yes
+✓ Nothing was installed, registered (MCP) or overwritten — including the global
+  Serena config — without an explicit yes
 ✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise
 ✓ The closing `→ Next:` block is printed as the ABSOLUTE last output
 ```
@@ -77,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
@@ -94,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
@@ -122,12 +127,23 @@ loads exactly upgrade and skips bootstrap plus portability.
   on its own. **The urgency label seeding is additive-only the same way:**
   create a missing `urgent`/`fix-next` label, never touch one that already
   exists (name, color, or description a project already customized).
-- **Serena convention.** `.serena/project.yml` is committed; `project.local.yml`
-  and `cache` stay local. Never write `.serena/` config without consent. LSP
-  never verifies documents — false positives happen when a file type's server
-  is not listed (markdown/yaml/json are never auto-detected), and a listed
-  server that fails to start must be removed (one failure disables every
-  server in the project). Document verification is a script's job.
+- **Serena convention — tool and config, one consent question.** `.serena/project.yml`
+  is committed; `project.local.yml` and `cache` stay local. Never write
+  `.serena/` config, install the tool, register an MCP server or touch the
+  global `serena_config.yml` (`trusted_project_path_patterns`) without an
+  explicit yes — [SERENA](references/SERENA.md) owns the single question and
+  the fixed provisioning report. LSP never verifies documents — false positives
+  happen when a file type's server is not listed (markdown/yaml/json are never
+  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
@@ -217,8 +233,11 @@ OpenCode adapter does not load this fallback.
   listed as a residual when its hook API/dependency was unavailable.
   The adaptive lane conventions (unit document, triage, catalog steps, guards,
   evidence, commit formats) are written into AGENTS.md.
-- The Serena project config is provisioned (or reported as a residual with the
-  reason, and the health check ran).
+- Serena is provisioned and reported: the one consent question was asked, the
+  project config written (or skipped with its reason), the tool installed and its
+  MCP server registered for the detected platform — or each refused/absent item
+  recorded as a residual with its reason — and the fixed provisioning report
+  states the health check per listed server. The run completes either way.
 - **The closing `→ Next:` block is printed** (plus the offer to install the skills):
 
   ```

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

@@ -69,3 +69,9 @@
      website itself.
    - **Naming conventions**, **MCP servers**, and **Serena language servers** (see
      [SERENA](SERENA.md) for the mapping), if any.
+   - **Serena footprint** — the platform whose MCP config is the one to register
+     (Claude Code, Cursor, VS Code/Copilot, Codex, JetBrains), the installers
+     actually present (`uv --version`, `pipx --version`), and whether the global
+     `serena_config.yml` already covers this project root under
+     `trusted_project_path_patterns`. The write step offers **one** consent
+     question from these three facts; it never asks a second time.

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

@@ -24,14 +24,23 @@
 7. **Propagate the unit doc template.** Ensure
    `docs/features/_TEMPLATE/SPEC.md` exists with all 14 sections sections.
    This is the template used when creating new unit documents.
-8. **Provision the Serena project config.** Load
-   [SERENA](SERENA.md), ask consent, then: (a) append the `.gitignore`
-   block additively (skip when already present); (b) write `.serena/project.yml`
-   with the `language_servers` list for every detected language (never overwrite
-   an existing file — report it); (c) run the health check from SERENA.md and
-   record the result. If Serena is not installed, offer install or record as a
-   residual.
-9. **Install accepted agent safety hooks.** Keep the canonical policy and
+8. **Provision Serena — one consented question, then write.** Load
+   [SERENA](SERENA.md) and ask its single consent question; one yes covers the
+   tool install, the detected platform's MCP registration and the global trust
+   append, and a refusal installs, registers and writes **nothing**. On yes:
+   (a) append the `.gitignore` block additively (skip when already present);
+   (b) write `.serena/project.yml` with the `language_servers` list for every
+   detected language (never overwrite an existing file — report it); (c) run the
+   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. **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
@@ -44,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
@@ -57,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):
@@ -70,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

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

@@ -93,6 +93,12 @@ check names the offending entry. Removing a failing entry (per the startup
 rule below) is the correct remediation — never leave a dead entry in the file.
 **Never claim LSP evidence for a run whose server never started.**
 
+The report's `health:` line carries one entry per listed server. When the check
+cannot run at all — no tool, no installer, or a refused consent, including a
+refused **trust** append (§Trust) — it says so once, on that line, with the
+reason, instead of reporting a pass: an absent check is a residual, never a
+silent pass.
+
 ### Startup rule (critical)
 
 > **A server that fails to start must not stay listed.** One failing entry
@@ -121,13 +127,93 @@ deterministic script's job regardless — LSP serves navigation and diagnostics,
 not our document grammar. `node`+`npm` are required for json/yaml; `libicu` is
 required for marksman.
 
-## Tool install is a different step
+## Provisioning the tool — one consented question
+
+This file owns the **project config** *and* the tool that reads it. The install
+half (`#219`) lands here as one step, never a second interview.
+
+**Order inside the step (fixed):**
+
+1. **Detect what can be performed** — `uv --version` first, then `pipx
+   --version`. Never offer a route the machine cannot run.
+2. **Ask ONCE**, with the whole set in the question: the tool install, the MCP
+   registration for **the detected platform only**, and the global trust append
+   when the project root is not covered. One yes covers the set the question
+   names; a narrower yes narrows the set.
+3. **On yes** — install, register, append trust, then report exactly what
+   happened (§Report).
+4. **On no** — install nothing, register nothing, write nothing. Record the
+   absence as a residual with its reason and finish; the run still completes.
+
+**Install routes, in the order tried:**
+
+| Route | Command | When |
+|---|---|---|
+| preferred | `uv tool install -p 3.13 serena-agent`, then `serena init` | `uv` is on PATH |
+| fallback | `pipx install serena-agent`, then `serena init` | `uv` absent, `pipx` present — **MCP path only** |
+
+`serena init` creates the global `serena_config.yml` when absent and never
+rewrites an existing one. `serena -V` prints `Serena <version>`: that is the
+health reader, and the only proof the tool runs.
+
+### MCP registration — the detected platform, its own shape
+
+Register **one** server named `serena`, in the config file of the platform
+Step 0 detected. Never write a cross-platform blob, and never write a second
+platform's file "to be safe". A per-workspace file (`.vscode/mcp.json`,
+`.cursor/mcp.json`) needs the same consent as the rest; a global one
+(`~/.codex/config.toml`, the JetBrains `mcp.json`) is append-only — the one
+entry, never another line.
+
+| Detected | Where | Entry |
+|---|---|---|
+| Claude Code | `claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"` (user scope: `--scope user`, `--project-from-cwd`) | command `serena` |
+| Copilot / VS Code | `.vscode/mcp.json` → `servers.serena` | `{"type":"stdio","command":"serena","args":["start-mcp-server","--context=vscode","--project","${workspaceFolder}"]}` |
+| Cursor | `.cursor/mcp.json` → `mcpServers.serena` | `{"command":"serena","args":["start-mcp-server","--context=ide"]}` |
+| JetBrains Copilot | the global `mcp.json` Copilot opens | `{"type":"stdio","command":"serena","args":["start-mcp-server","--context=jb-copilot-plugin"]}` |
+| Codex | `~/.codex/config.toml` → `[mcp_servers.serena]` | `command = "serena"`, `args = ["start-mcp-server","--project-from-cwd","--context=codex"]` |
+
+### Trust — the fresh clone (global config, consent-gated)
+
+`trusted_project_path_patterns` lives in the user's **global** `serena_config.yml`,
+not the project's `.serena/project.yml`, and a fresh config defaults it to `[]`.
+A project root no pattern covers starts no language server, so the health check
+fails with nothing in the project to blame.
+
+- **Detect** — read the global config, test this project root against the
+  patterns.
+- **Offer the append inside the same consented question.** This file is shared by
+  every project on the machine, so it is never written implicitly.
+- **On yes** — append **one pattern naming this project root**. Never rewrite,
+  reorder or reformat any other line; an append is the only permitted edit.
+- **On no** — record the untrusted state as the health-check residual. It is a
+  residual, not an error, and it never blocks the run.
+
+### Report — exactly what happened
+
+Close the step with this fixed block. "Installed" is never assumed and never
+reported from the intent to install:
 
-This file owns the **project config**, not the tool. If Serena is not installed,
-offer the install (ask-first; `uv`/`uvx` preferred, `pipx` fallback) or record
-it as a residual. The install half is tracked by #219.
+```text
+SERENA PROVISIONING
+tool:      <installed | already present | refused | no installer | failed: <reason>>
+version:   <serena -V output, or n/a>
+mcp:       <registered <platform> -> <path> | already present | refused | failed: <reason>>
+trust:     <appended <pattern> | already covered | refused - untrusted | n/a>
+config:    <written .serena/project.yml | already present | skipped: <reason>>
+health:    <one line per listed server, see below>
+residual:  <none | the reason this run is degraded>
+```
 
 ## Degraded path
 
-Serena unavailable → warn once, continue, and record the absence in the unit's
-evidence. **Never block a run on it.**
+Serena unavailable — no tool, no installer (`uv`, `pipx`), or a refused consent —
+→ warn once, continue, and record the absence with its reason in the unit's
+evidence. **Never block a run on it**, and never let a degraded run read as a
+healthy one: the report says which line is missing and why.
+
+LSP evidence itself stays confined to **TypeScript/JavaScript**: a diagnostic
+from any other listed server is navigation aid, never verification evidence, and
+no claim may cite it. Document verification (schema rules, required sections,
+column counts) stays a **deterministic script's** job regardless — LSP serves
+navigation, not our document grammar.

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

@@ -92,13 +92,15 @@ lacks**. Nine ordered steps:
    rule as the doc blocks; a pre-existing `urgent`/`fix-next` label the
    project recolored or redescribed is left exactly as-is).
 
-8. **Provision the Serena project config, additively only (Refs #219).** Load
-   [SERENA](SERENA.md). Append the `.gitignore` block only if the target
-   does not already contain it. Write `.serena/project.yml` only if it is
-   absent — never touch an existing one. Report what was skipped and why.
-   Run the health check and record the result. If Serena is not installed,
-   offer install or record as a residual. This step is additive-only; it
-   never rewrites or deletes, consistent with upgrade mode's rule.
+8. **Provision Serena, additively only (Refs #219).** Load
+   [SERENA](SERENA.md) and ask its single consent question — the tool install,
+   the detected platform's MCP registration and the global trust append all ride
+   on that one yes, and a refusal writes nothing. Then append the `.gitignore`
+   block only if the target lacks it, and write `.serena/project.yml` only if it
+   is absent — never touch an existing one. Report what was skipped and why, run
+   the health check, and render the fixed provisioning report. This step is
+   additive-only; it never rewrites or deletes, consistent with upgrade mode's
+   rule.
 9. **Report + hand off.** Summarize blocks added, filled, and skipped
    (residuals), the legacy `CLAUDE.md` outcome (folded items and removed, or kept
    with the reason), the urgency labels seeded (or already present), then print the

package/skills/log-session/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: log-session
 user-invocable: true
-version: 2.2.1
+version: 2.3.0
 argument-hint: "[note to prepend to the entry]"
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -124,6 +124,22 @@ the HEAD sha and start time at session open.
    open a PR just for a log entry, and never `git add -A` here — a concurrent
    conversation's work must not be swept into a log commit.
 
+## The canonical split — this skill's half (feature 66, D2)
+
+Two writers exist on purpose; neither mirrors the other:
+
+- **`docs/LOGS.md` (this skill)** is the **human/team journal** — what a session
+  set out to do, what it decided, where to resume. It travels with git, so a
+  teammate or a fresh clone reads it with no local state.
+- **Engram (`mem_session_summary`, and the lane's `unit/<NN-slug>/doc` topic)**
+  is **local decision and gotcha recall keyed by unit id**, written by
+  `unit-lane` and `execute-phase` at unit boundaries. It stays on the machine.
+
+Engram never mirrors this log, and this log never mirrors Engram: team memory
+travels with git, agent recall stays local. Write the journal half here; the
+protocol half (boundaries, recall order, degradation) lives in the lane's
+memory reference, `../unit-lane/references/MEMORY.md`.
+
 ## Guardrails
 
 - **Never use an expensive model for this.** It's summarization; `qwen3.6`

package/skills/unit-lane/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: unit-lane
 user-invocable: true
-version: 2.3.0
+version: 2.4.1
 argument-hint: <NN-slug | "<idea>"> [--retriage] | --fix <issue-number> | --from-issue <issue-number>
 description: >
   One-shot lane conductor for a delivery unit: triage, implement, evidence, and
@@ -39,6 +39,8 @@ done:
   on BREACH: re-triage or record exception, never shrink the diff
 ✓ Unit doc's Evidence rows updated (command → exit/digest → output → verified-by)
   and Progress log updated (dated entry) before every commit
+✓ Memory boundaries ran — probe verdict once, saves at unit start / each phase
+  transition / close under `unit/<NN-slug>/doc`, degradation recorded as pending
 ✓ → Next: block printed as the absolute last output
 ```
 
@@ -167,6 +169,20 @@ Before every commit:
 - **Progress log**: `YYYY-MM-DD HH:MM — <what was done> → <commit sha> — next:
   <what is next>`
 
+### 5b. Memory boundaries
+
+Engram is the required memory substrate; a down layer never blocks a unit —
+follow [the memory protocol](references/MEMORY.md).
+
+- **Probe once**, before the first memory read: `agentic-workflow memory probe`
+  → paste the verdict into Evidence; `degraded` is recorded and said once.
+- **Save at unit start, each phase transition, and close** under
+  `topic_key: "unit/<NN-slug>/doc"`, with explicit `project` and explicit
+  session attribution (§5 names what carries it on each write surface).
+- **Recall** `mem_context` → scoped search → one explicit `all_projects: true`
+  retry → `mem_get_observation` → the unit doc wins. A miss is keyword-bound,
+  never proof nothing was saved; an unavailable mirror is marked pending.
+
 ### 6. Close the unit — the close-out ladder
 
 When all triaged steps are done, in order: