pi-dev 0.2.3 → 0.2.5

package/README.md

@@ -35,21 +35,22 @@ You ask. It classifies. It executes. It reports.
 - **A migration gate that won't let you cheat.** `/do` refuses to touch an un-migrated repo. `/migrate` audits `AGENTS.md`, `CLAUDE.md`, scoped agent dirs, handoff systems, and ADR layouts; archives the noise; stamps a marker; and on every re-entry runs drift probes so banned conventions can't sneak back in.
 - **No handoff files. Ever.** State of work lives in three places only — code (git), the issue tracker, and merged preferences. No `docs/handoff/`, no `.scratch/flow/`, no SESSION_*.md littering your repo.
 - **Local-live verification the agent owns.** A one-time playbook captures how to boot your stack. From then on the agent boots it, drives it, and quotes the evidence in the summary. You are not the test runner.
-- **Vertical-slice issues with AI disclaimers baked in.** `/to-issues` produces independently-grabbable tickets — each with acceptance criteria, allowed-touch-set, and out-of-scope — and the disclaimer required by `/triage` lands on every one.
+- **Vertical-slice issues that read like a spec.** `/to-issues` produces independently-grabbable tickets — each with acceptance criteria, allowed-touch-set, and out-of-scope — written as plain spec so the next worker agent picks them up as input, not as a meta-tagged AI artefact.
+- **One minimal plugin where prose is provably not enough.** Ships `pi-flow`: a single pi extension whose only job is to catch `/do` ending a turn with `follow-up: ... run /do ...` mid-chain (the hand-back pattern that turns one prompt into ten "진행해" replies) and steer back into the next phase. Toggle in `~/.pi/agent/settings.json` → `piFlow.enabled`. We add a new guard only when an audit shows a rule the model demonstrably can't see itself drift past.
 
 ## Install
 
 Requires Node ≥ 20 and the [pi runtime](https://github.com/badlogic/pi).
 
 ```bash
-# Interactive: pick global vs project-local, then install + seed preferences
+# Interactive: pick global vs project-local, then install skills + extensions + seed preferences
 npx pi-dev@latest install
 
 # Or be explicit:
-npx pi-dev@latest install --global    # ~/.pi/agent/skills/   (every repo)
-npx pi-dev@latest install --local     # ./.pi/skills/         (this repo only)
+npx pi-dev@latest install --global    # ~/.pi/agent/{skills,extensions}/   (every repo)
+npx pi-dev@latest install --local     # ./.pi/{skills,extensions}/         (this repo only)
 
-# Refresh skills (auto-detects scope from disk; preferences are kept)
+# Refresh skills + extensions (auto-detects scope from disk; preferences are kept)
 npx pi-dev@latest update
 
 # See what's installed under each scope
@@ -64,10 +65,11 @@ npx pi-dev doctor
 | | global | local |
 | --- | --- | --- |
 | Skills | `~/.pi/agent/skills/` | `<repo>/.pi/skills/` |
+| Extensions | `~/.pi/agent/extensions/` | `<repo>/.pi/extensions/` |
 | Preferences | `~/.pi/agent/preferences.md` | `<repo>/.pi/preferences.md` |
 | Pi sessions see it from | every cwd | only this repo |
-| Goes in the repo's git? | no | yes (commit `.pi/skills/`, gitignore `.pi/sessions/`) |
-| Use when | the skills are part of *your* engineering taste | the skills are part of *the project's* contract |
+| Goes in the repo's git? | no | yes (commit `.pi/skills/` + `.pi/extensions/`, gitignore `.pi/sessions/`) |
+| Use when | the framework is part of *your* engineering taste | the framework is part of *the project's* contract |
 
 Non-interactive runs (CI, piped input) default to `--global` silently. Pass `-y` to skip the prompt and accept the default.
 

package/dist/install.js

@@ -3,7 +3,19 @@ import { execSync } from "node:child_process";
 import { join } from "node:path";
 import { createInterface } from "node:readline";
 import { SKILLS, CONSUMER_SKILLS } from "./manifest.js";
-import { PKG_SKILLS_DIR, PKG_GLOBAL_PREFS_PRESET, destFor, } from "./paths.js";
+import { PKG_SKILLS_DIR, PKG_EXTENSIONS_DIR, PKG_GLOBAL_PREFS_PRESET, destFor, } from "./paths.js";
+/**
+ * Extensions shipped with pi-dev. Each is a subdirectory under `extensions/`
+ * that pi auto-discovers from `~/.pi/agent/extensions/<name>/` (global) or
+ * `.pi/extensions/<name>/` (local). The directory name is the install name
+ * verbatim — no prefix, no transform.
+ *
+ * Keep this list short. A new entry is justified only by an audit signal
+ * showing prose alone has ≥60% miss rate on a mechanically checkable rule.
+ */
+const EXTENSIONS = [
+    { name: "pi-flow", summary: "Steer mid-chain hand-backs back into the next phase." },
+];
 function ask(question) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     return new Promise((res) => {
@@ -39,8 +51,9 @@ async function resolveScope(opts) {
 }
 export async function install(opts = {}) {
     const scope = await resolveScope(opts);
-    const { agentDir, skillsDir, prefsFile } = destFor(scope);
+    const { agentDir, skillsDir, extensionsDir, prefsFile } = destFor(scope);
     mkdirSync(skillsDir, { recursive: true });
+    mkdirSync(extensionsDir, { recursive: true });
     const skillsToInstall = opts.includeMaintainer ? SKILLS : CONSUMER_SKILLS;
     let copied = 0;
     for (const skill of skillsToInstall) {
@@ -59,6 +72,25 @@ export async function install(opts = {}) {
         copied++;
     }
     console.log(`Installed ${copied} skill(s) into ${skillsDir} [${scope}]`);
+    let extsCopied = 0;
+    for (const ext of EXTENSIONS) {
+        const src = join(PKG_EXTENSIONS_DIR, ext.name);
+        const dst = join(extensionsDir, ext.name);
+        if (!existsSync(src)) {
+            console.warn(`  skip extension ${ext.name} (source not found in package)`);
+            continue;
+        }
+        if (existsSync(dst) && !opts.force) {
+            cpSync(src, dst, { recursive: true, force: true });
+        }
+        else {
+            cpSync(src, dst, { recursive: true });
+        }
+        extsCopied++;
+    }
+    if (extsCopied > 0) {
+        console.log(`Installed ${extsCopied} extension(s) into ${extensionsDir} [${scope}]`);
+    }
     if (opts.skipPrefs) {
         console.log("Skipped preferences (pass --include-prefs on update to merge in new keys).");
         return;

package/dist/paths.js

@@ -4,23 +4,31 @@ import { fileURLToPath } from "node:url";
 export const HOME = homedir();
 export const PI_AGENT_DIR = join(HOME, ".pi", "agent");
 export const PI_SKILLS_DIR = join(PI_AGENT_DIR, "skills");
+export const PI_EXTENSIONS_DIR = join(PI_AGENT_DIR, "extensions");
 export const PI_GLOBAL_PREFS = join(PI_AGENT_DIR, "preferences.md");
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 /** Resolve the package root regardless of whether we run from src/ or dist/. */
 export const PKG_ROOT = resolve(__dirname, "..");
 export const PKG_SKILLS_DIR = join(PKG_ROOT, "skills");
+export const PKG_EXTENSIONS_DIR = join(PKG_ROOT, "extensions");
 export const PKG_PRESETS_DIR = join(PKG_ROOT, "presets");
 export const PKG_GLOBAL_PREFS_PRESET = join(PKG_PRESETS_DIR, "preferences.md");
 /** Compute install destinations for a given scope. `local` resolves against `cwd`. */
 export function destFor(scope, cwd = process.cwd()) {
     if (scope === "global") {
-        return { agentDir: PI_AGENT_DIR, skillsDir: PI_SKILLS_DIR, prefsFile: PI_GLOBAL_PREFS };
+        return {
+            agentDir: PI_AGENT_DIR,
+            skillsDir: PI_SKILLS_DIR,
+            extensionsDir: PI_EXTENSIONS_DIR,
+            prefsFile: PI_GLOBAL_PREFS,
+        };
     }
     const agentDir = join(cwd, ".pi");
     return {
         agentDir,
         skillsDir: join(agentDir, "skills"),
+        extensionsDir: join(agentDir, "extensions"),
         prefsFile: join(agentDir, "preferences.md"),
     };
 }

package/extensions/pi-flow/README.md

@@ -0,0 +1,40 @@
+# pi-flow
+
+The default plugin that ships with `pi-dev`. One job: stop `/do` from
+quietly handing the chain back to you between phases.
+
+## What it does
+
+Watches the end of every assistant turn. If the last visible text contains
+a `follow-up: ... run /do ...` line **without** a preceding
+`chain complete — no further action.` line, it queues a follow-up steer
+that prompts the next phase. Your next turn is the next `[flow N/M]`
+status line, not "진행해".
+
+## Why one guard, not five
+
+`pi-flow` is intentionally minimal. Each new guard taxes every tool call,
+slows iteration, and tempts everyone to disable the whole plugin. So:
+
+- We add a guard only when a real audit shows ≥60% violation on a rule
+  the model can't see itself drift past.
+- We remove a guard when the underlying root cause is gone (e.g. an
+  `.gitignore` lockout makes a path-write guard redundant).
+- Everything else stays in `SKILL.md` prose where the cost is zero.
+
+The hugn 2026-05 audit produced exactly one such finding (mid-chain
+hand-back, 8/13 sessions). That is what this guard exists for.
+
+## Toggle
+
+`~/.pi/agent/settings.json`:
+
+```json
+{
+  "piFlow": {
+    "enabled": false
+  }
+}
+```
+
+Default: on.

package/extensions/pi-flow/index.ts

@@ -0,0 +1,65 @@
+/**
+ * pi-flow
+ *
+ * Minimal runtime plugin that keeps /do on-chain.
+ *
+ * One guard, one event: when an assistant turn ends with a
+ * `follow-up: ... run /do ...` line that is *not* preceded by the canonical
+ * `chain complete — no further action.` terminator, the chain is being
+ * handed back mid-flight. The plugin queues a steer reminder so the next
+ * turn re-enters the chain at the next phase instead of waiting for the user
+ * to type "진행해" / "go" / "다음".
+ *
+ * Rationale: the hugn 2026-05 audit showed 8/13 /do sessions ending with
+ * chain-depth 0 and 82% of user messages being short re-entry nudges. Every
+ * other candidate guard had near-zero ROI — the taboo-path writes were already
+ * stopped by a .gitignore lockout, and other rules were taken out of policy.
+ * One predicate, one steer.
+ *
+ * Toggle:
+ *   ~/.pi/agent/settings.json → "piFlow": { "enabled": false }
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const HANDBACK = /^follow-up:\s.*\brun\s+`?\/?do\b/m;
+const TERMINATOR = /chain complete\s+\u2014\s+no further action/;
+
+function isEnabled(): boolean {
+  const settingsPath = join(homedir(), ".pi", "agent", "settings.json");
+  if (!existsSync(settingsPath)) return true;
+  try {
+    const raw = JSON.parse(readFileSync(settingsPath, "utf-8")) as Record<string, unknown>;
+    const cfg = (raw["piFlow"] ?? {}) as { enabled?: boolean };
+    return cfg.enabled !== false;
+  } catch {
+    return true;
+  }
+}
+
+export default function piFlow(pi: ExtensionAPI) {
+  if (!isEnabled()) return;
+
+  pi.on("message_end", async (event) => {
+    if (event.message.role !== "assistant") return;
+    const text = event.message.content
+      .filter((b): b is { type: "text"; text: string } => b.type === "text")
+      .map((b) => b.text)
+      .join("\n");
+    if (!text || !HANDBACK.test(text) || TERMINATOR.test(text)) return;
+
+    pi.sendMessage(
+      {
+        customType: "pi-flow",
+        content:
+          "[pi-flow] mid-chain hand-back detected. `follow-up: … run /do …` is the Step-7 terminator, " +
+          "not a phase boundary. Print the next `[flow N/M]` status line and continue the chain.",
+        display: true,
+      },
+      { triggerTurn: true, deliverAs: "followUp" },
+    );
+  });
+}

package/extensions/pi-flow/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "pi-flow",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Default pi-dev plugin: keeps /do on-chain by steering mid-chain hand-backs.",
+  "pi": {
+    "extensions": ["./index.ts"]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-dev",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "An autonomous engineering skill framework for the pi runtime — built on Matt Pocock's skills.",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "dist",
     "skills",
+    "extensions",
     "presets",
     "README.md",
     "LICENSE"
@@ -39,10 +40,10 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/jason2077/pi-dev.git"
+    "url": "git+https://github.com/jason2077/pi-flow.git"
   },
   "bugs": {
-    "url": "https://github.com/jason2077/pi-dev/issues"
+    "url": "https://github.com/jason2077/pi-flow/issues"
   },
-  "homepage": "https://github.com/jason2077/pi-dev#readme"
+  "homepage": "https://github.com/jason2077/pi-flow#readme"
 }

package/skills/do/SKILL.md

@@ -26,33 +26,9 @@ The point: **one request → one finished outcome**, with as few user interrupti
    - a phase's terminal predicate fails twice and the failure cannot be characterised, OR
    - the Ambiguity protocol fires (preferences truly silent on a one-shot decision), OR
    - user interrupts.
-5. **No handoff files.** State of work lives in three places only: **code (git), issue tracker, merged preferences**. Do not create `.scratch/flow/`, `docs/handoff/`, or any session-log file. Phase outputs are remembered in-context; persistent decisions are committed to code or filed as issues.
+5. **No handoff files.** State of work lives in three places only: **code (git), issue tracker, merged preferences**. Do not create `.scratch/flow/`, `docs/handoff/`, `.handoff/`, or any session-log file (`SESSION_*.md`, `HANDOFF_*.md`). Phase outputs are remembered in-context; persistent decisions are committed to code or filed as issues.
 6. **Side-effect gates respect prefs literally.** `auto-create-issues`, `auto-apply-labels`, `auto-commit-per-slice`, `auto-pr` follow merged prefs without reinterpretation.
 7. **Status line per phase.** `[flow N/M] <phase-name> — <one-sentence what>`.
-8. **Issue-write rule (no exceptions).** Every issue body written from a `/do` flow — whether you invoke `/to-issues`, `/triage`, or call `gh issue create` / `gh issue edit` directly from a bash tool — MUST start with this disclaimer as the first non-blank line:
-
-   ```
-   > *This was generated by AI during triage.*
-   ```
-
-   This rule is global and binding regardless of which skill you think you are in. Before publishing any issue body:
-
-   - Build the body with `--body-file <path>` or a heredoc, never with inline `--body "..."` (heredocs make the disclaimer visible in the diff and the file is auditable).
-   - The first non-blank line of the body file must be the disclaimer literal above.
-   - Immediately after `gh issue create` / `gh issue edit` returns, run one self-check on the resulting body and halt the flow if it fails:
-
-     ```bash
-     gh issue view <num> --json body --jq '.body' | awk 'NF{print; exit}' | grep -q 'generated by AI' \
-       || { echo "AI disclaimer missing on issue #<num>"; exit 1; }
-     ```
-
-   **Anti-patterns** (delete and redo if you catch any in your own draft):
-
-   - `gh issue create --title "…" --body "..."` (inline body, no disclaimer check)
-   - First line of issue body being `## Goal`, `## Scope`, `## Problem Statement`, `**Parent epic:**`, or any heading other than the disclaimer.
-   - Skipping the post-create `gh issue view ... | grep generated by AI` self-check because "I included the disclaimer in the heredoc".
-
-   Skills `/to-issues` and `/triage` repeat this rule for the case where you do enter them. This Hard rule is the binding statement for the case where you do not.
 
 ## Process
 
@@ -155,6 +131,8 @@ Then for each phase:
 - Ending the turn with `follow-up: <next planned phase> — run /do …` when N < M. The `follow-up:` line is reserved for *post-chain* deferred work (push, manual ops live, prefs refresh). Using it to describe the *next planned phase of this chain* is a disguised hand-back — start the phase instead.
 - Treating a short user nudge ("진행해", "다음", "계속", "ㄱㄱ", "go", "이어서") as a new request. If the planned chain has unfinished phases, those nudges are noise — re-enter the chain at the next phase, do not re-classify and re-inject `/do`.
 
+The `pi-flow` plugin (installed by default) watches the end of each assistant turn: a `follow-up: ... run /do ...` line *not* preceded by `chain complete — no further action.` is treated as a mid-chain hand-back and steered back into the next phase automatically. The prose above is still the canonical contract; the plugin is the safety net.
+
 The only place a wrap-up belongs is **Step 7 — Final summary**, after the last phase has met its terminal predicate.
 
 ### Step 5 — Live verification
@@ -219,7 +197,7 @@ If you emitted anything that looks like a wrap-up ("All set!", "Done.", "Let me
 | `grill-with-docs` / `grill-lite`   | every open question answered, deferred with rationale, or escalated; relevant CONTEXT/ADR updates committed |
 | `to-prd`                           | PRD published to issue tracker with `needs-triage` (per `auto-create-issues`)           |
 | `to-issues`                        | all slices created on tracker; each is independently grabbable; labels applied per `auto-apply-labels` |
-| `triage`                           | issue carries exactly one state label; AI disclaimer present (verified via the Hard rule #8 self-check, not just inserted into the heredoc) |
+| `triage`                           | issue carries exactly one state label                                                                                                       |
 | `diagnose`                         | reproducible pass/fail loop exists AND root cause identified AND regression test exists |
 | `tdd`                              | new test red→green; project's check command clean; commit per `auto-commit-per-slice`    |
 | `improve-codebase-architecture`    | proposed deepening either applied or recorded as a follow-up issue                      |

package/skills/improve-skill-flow/SKILL.md

@@ -50,22 +50,37 @@ Always from inside the pi-dev checkout (see Pre-flight).
 - **Consumer repo path** (or its sessions directory) to audit. The maintainer names a repo on this machine; you resolve its sessions dir.
 - Optional: a specific skill name to focus the audit on (`do`, `migrate`, `triage`, …).
 - Optional: a date range.
-- **Fix scope** per finding — `framework` or `consumer-prefs`. Defaults set in Step 5.5; maintainer can flip individual rows before applying.
+- **Fix scope** per finding — `framework`, `extension`, or `consumer-prefs`. Defaults set in Step 5.5; maintainer can flip individual rows before applying.
 
 ## Fix scopes
 
-pi-runtime today loads skill bodies from a single location (`~/.pi/agent/skills/<name>/SKILL.md` for global installs, `<repo>/.pi/skills/<name>/SKILL.md` for local installs). The framework's 3-layer override is on **preferences**, not on SKILL bodies. So a finding lands in one of two places:
+pi-runtime loads three artefact kinds the framework can ship:
+
+- **Skill bodies** — `~/.pi/agent/skills/<name>/SKILL.md` (global) or `<repo>/.pi/skills/<name>/SKILL.md` (local). Pure prose.
+- **Extensions** — `~/.pi/agent/extensions/<name>/` (global) or `<repo>/.pi/extensions/<name>/` (local). TypeScript modules auto-loaded via jiti; can subscribe to `tool_call`, `message_end`, `before_agent_start`, etc., and can block tool calls or inject steer messages. pi-dev ships **one** by default — `pi-flow` — and the bar to add a second is high (see below).
+- **Preferences** — `docs/agents/preferences.md` (per repo) and `~/.pi/agent/preferences.md` (per machine). 3-layer override on prose-level decisions.
+
+A finding lands in exactly one of:
 
 | scope | lands in | reaches | propagation | when to pick |
 | --- | --- | --- | --- | --- |
-| **framework** | this repo's `skills/<name>/SKILL.md` | every consumer after the next `npx pi-dev update` | release-please → npm publish | the SKILL.md wording itself is wrong; gap shows up generically |
-| **consumer-prefs** | the audited consumer repo's `docs/agents/preferences.md` (Project taboos / Diagnosis posture / Local-live playbook / Free notes — whichever section fits) | only that repo, on every `/do` bootstrap | regular consumer-repo commit | gap is the consumer repo's domain / paths / conventions, not the SKILL.md |
+| **framework** | this repo's `skills/<name>/SKILL.md` | every consumer after the next `npx pi-dev update` | release-please → npm publish | the SKILL.md wording is wrong; gap shows up generically; prose alone is plausibly enough |
+| **extension** | this repo's `extensions/pi-flow/index.ts` (extend) or a new `extensions/<name>/` (rare) | every consumer after `npx pi-dev update` | release-please → npm publish | a real audit shows prose can't recover the rule, AND the rule is a simple deterministic predicate, AND skipping the guard would silently waste ≥1 user prompt per session |
+| **consumer-prefs** | the audited consumer repo's `docs/agents/preferences.md` | only that repo, on every `/do` bootstrap | regular consumer-repo commit | gap is the consumer repo's domain / paths / conventions, not the SKILL.md |
 
 Notes:
 
 - A `framework` apply is **always** mirrored into `~/.pi/agent/skills/<name>/` on this machine so the next session picks it up immediately, without waiting for npm.
+- An `extension` apply is **always** mirrored into `~/.pi/agent/extensions/<name>/` on this machine for the same reason. The package directory name is the install name verbatim (no `pi-dev-` prefix).
 - A `consumer-prefs` apply touches no pi-dev files. It is committed to the consumer repo only.
-- A single audit may produce a mix of framework and consumer-prefs findings. Decide scope per finding, not per audit.
+- A single audit may produce a mix of all three. Decide scope per finding, not per audit.
+
+**Extension scope is the most expensive option.** Every guard runs on every relevant tool call or turn, slows iteration, and tempts the maintainer to disable the whole plugin. Default to `framework` / `consumer-prefs` and reach for `extension` only when the audit makes the ROI undeniable. The bar:
+
+- The rule was in-context as SKILL.md prose at audit time **and** was violated on ≥60% of opportunities across two consecutive audits.
+- The predicate is deterministic and short — a tool name plus an arg regex, or a tail-of-turn regex — with no LLM call.
+- The failure cost is concrete — the model wastes one or more user prompts per session re-entering a chain, or commits a destructive artefact.
+- A simpler remedy (gitignore lockout, prefs taboo, prose anti-pattern) does **not** plausibly close the gap. If it does, take the simpler remedy.
 
 ## Session-data location & format
 
@@ -84,7 +99,27 @@ Each line is one of these record types:
 | `session` | session header — has `cwd`, `timestamp`, `version`, `id` |
 | `model_change` | provider / modelId switch |
 | `thinking_level_change` | reasoning effort knob |
-| `message` | a user or assistant turn |
+| `message` | a user / assistant / toolResult turn |
+
+**Record shape for `message` (do not skim this — it has bitten parsers before):**
+
+```jsonc
+{
+  "type": "message",
+  "id": "...",
+  "parentId": "...",
+  "timestamp": "2026-05-11T16:46:49.795Z",
+  "message": {                       // ← NESTED. role/content are HERE, not at top level.
+    "role": "user" | "assistant" | "toolResult",
+    "content": [ ...blocks ],
+    "timestamp": "...",
+    // assistant-only extras: api, provider, model, usage, stopReason, responseId
+    // toolResult-only extras: toolCallId, toolName, isError
+  }
+}
+```
+
+A correct read path is `rec["message"]["role"]` and `rec["message"]["content"]`. Reading `rec["role"]` / `rec["content"]` returns `None` for every record and silently produces a zero-row signal table — if your first pass shows all counters at 0, this is almost certainly why.
 
 `message.content` is a **list of blocks**, each block has a `type`:
 
@@ -95,8 +130,19 @@ Each line is one of these record types:
 | `toolCall` | `{id, name, arguments}` | **pi uses this** — NOT Anthropic SDK's `tool_use` |
 | `toolResult` | `{id, output}` | **pi uses this** — NOT `tool_result` |
 
+Roles in practice: `user`, `assistant`, and **`toolResult`** (yes, role and block type share the name; a `toolResult`-role message contains one or more `text` blocks holding the tool output). Treat `toolResult`-role messages as siblings of the originating `toolCall` — do not double-count them as user/assistant turns.
+
 Tool names are **lower-case** (`bash`, `read`, `edit`, `write`, `glob`, `grep`, etc.). Build any parser around `toolCall` / `toolResult` first, then fall back to Anthropic-shaped blocks for robustness.
 
+**Parser pre-flight (mandatory before Step 2 aggregates).** After you write the one-shot Python parser, run it on the newest 1–2 `.jsonl` files and assert the following are non-zero for any session that obviously had work done:
+
+```python
+assert tool_count, "toolCall extraction returned 0 — check rec['message']['content'], not rec['content']"
+assert user_msg_total or skill_inject_count, "no user messages parsed — same nested-message bug"
+```
+
+If either assertion would fail, fix the parser before producing the signal table. A zero-row table is never a finding — it is a parser bug.
+
 **Critical detail:** the pi runtime injects each skill's `SKILL.md` content into the conversation as a `<skill name="..." location="...">…</skill>` block embedded inside a **user-role** message (system-side injection, but the role is user). This is how you tell the classifier loaded a skill. Count these to see what `/do` actually picked.
 
 Timestamps on `message` records are ISO strings; some other record types use int millis. Handle both.
@@ -133,7 +179,7 @@ Run a single pass over every targeted `.jsonl` and tally:
 - Count user messages shorter than ~80 chars — these are usually nudges ("진행해", "다음은?", "끝났어?"). High proportion = `/do` is handing the flow back too often.
 - Count user messages containing correction markers (`아니`, `wait`, `stop`, `취소`, `다시`, `그만`, `undo`, `revert`). These mark interventions.
 - Count `<!-- migrated: ... -->` marker date vs. any post-marker `docs/handoff/` / `.scratch/flow/` / `SESSION_*.md` writes. Drift = handoff lockout failed.
-- Count tracker writes (`gh issue create`, `gh pr create`) and check whether `generated by AI` (the `/triage` disclaimer) appears in the surrounding text. Missing disclaimer = `/to-issues` / `/triage` predicate violated.
+- Count tracker writes (`gh issue create`, `gh pr create`) and inspect the bodies; the bodies are plain spec consumed by future worker agents, so look for issues with shape problems (missing parent, no acceptance criteria, etc.) rather than meta tags.
 
 Use a deterministic Python or shell script you write once and check into `/tmp` for the duration of the run. Do not eyeball big JSONLs by hand.
 
@@ -160,7 +206,7 @@ Produce a small table per audited skill. Each row:
 | signal                         | observed | expected (predicate / rule)        | severity |
 | ------------------------------ | -------- | ---------------------------------- | -------- |
 | /do → next-skill chain depth   | 1/5      | ≥1 per chain step (M phases)       | 🔴       |
-| AI disclaimer on slice issues  | 0/8      | every issue starts with disclaimer | 🔴       |
+| /do hand-back via follow-up    | 8/13     | 0 mid-chain hand-backs             | 🔴       |
 | post-marker handoff writes     | 9        | 0                                  | 🟡       |
 | ...                            |          |                                    |          |
 ```
@@ -176,7 +222,7 @@ For every 🔴 / 🟡 row, quote the smallest piece of evidence that makes the g
 
 - a user message timestamp + first 80 chars,
 - a tool-call command that violates a taboo,
-- a missing disclaimer in a created issue body.
+- the first 80 chars of an issue body that violates the slice template.
 
 If a finding cannot be backed by an excerpt, it is not actionable yet — demote to a TODO and keep digging.
 
@@ -184,9 +230,15 @@ If a finding cannot be backed by an excerpt, it is not actionable yet — demote
 
 For each 🔴 / 🟡 finding, pick a default scope using the heuristic below, then show the table once and let the maintainer flip individual rows before applying.
 
+Default to `extension` if the finding matches **any** of:
+
+- The rule was already in SKILL.md prose at the time of the violating session **and** was violated repeatedly (i.e. prose recall is provably low for this rule).
+- The predicate is mechanically expressible against `event.input` (tool name + arg substring / path glob) or `event.message.content` (text tail shape).
+- The fix is a *refusal* or a *steer*, not a *reminder*.
+
 Default to `framework` if the finding matches **any** of:
 
-- Cites SKILL.md wording / phase / predicate / rule numbers.
+- Cites SKILL.md wording / phase / predicate / rule numbers, and the rule was not yet in place.
 - The proposed fix is a generic anti-pattern string, a terminator literal, a runway line, or a lockout that any repo would benefit from.
 - The same gap would plausibly show up in two or more consumer repos.
 
@@ -199,12 +251,12 @@ Default to `consumer-prefs` if the finding matches **any** of:
 Present the scope-decision table:
 
 ```
-| # | finding (short)                          | default scope    | target file                          | flip? |
-| - | ---------------------------------------- | ---------------- | ------------------------------------ | ----- |
-| 1 | /do hands flow back between phases       | framework        | pi-dev:skills/do/SKILL.md            |       |
-| 2 | docs/handoff/ resurrected after marker   | framework        | pi-dev:skills/migrate/SKILL.md       |       |
-| 3 | retro-action-item label still alive      | consumer-prefs   | hugn:docs/agents/preferences.md      |       |
-| 4 | smoke command name changed in S058       | consumer-prefs   | hugn:docs/agents/preferences.md      |       |
+| # | finding (short)                          | default scope    | target file                                          | flip? |
+| - | ---------------------------------------- | ---------------- | ---------------------------------------------------- | ----- |
+| 1 | /do hands flow back between phases       | extension        | pi-dev:extensions/pi-flow/index.ts (message_end)     |       |
+| 2 | post-marker handoff writes               | framework        | pi-dev:skills/migrate/SKILL.md (gitignore lockout)   |       |
+| 3 | retro-action-item label still alive      | consumer-prefs   | hugn:docs/agents/preferences.md                      |       |
+| 4 | smoke command name changed in S058       | consumer-prefs   | hugn:docs/agents/preferences.md                      |       |
 ```
 
 Ask once: "OK to proceed with these scopes? Reply with row numbers to flip, or `go`." Apply the flips and move on.
@@ -220,6 +272,15 @@ For each 🔴 / 🟡 finding, draft the smallest possible edit that, **if it had
 - Prefer **terminal markers** ("the summary's last line must be one of these two literals: …") over qualitative descriptions of "good wrap-up".
 - Update **at most three skills per run.** More than that means findings aren't anchored well enough.
 
+**Extension findings (target: pi-dev `extensions/pi-flow/index.ts`, or rarely a new `extensions/<name>/`):**
+
+- Add the handler to `pi-flow` rather than creating a new extension, unless the new concern is large enough to be independently toggleable.
+- A guard must be **deterministic** — same input → same outcome. No LLM calls, no time-of-day branches.
+- A guard must be **narrowly scoped** — tool name + arg shape, or end-of-turn regex. No free-text classification.
+- A guard must be **toggleable** via `~/.pi/agent/settings.json`. Default on. A user that disables it must still be able to read the prose contract.
+- Trim the corresponding SKILL.md prose to a one-line *why* + a pointer to the plugin. Do not delete the why — the model still needs to know the intent when the plugin is off.
+- Update **at most one handler per run.** Two changes at once destroys the next audit's ability to attribute movement.
+
 **Consumer-prefs findings (target: that repo's `docs/agents/preferences.md`):**
 
 - Pick the *narrowest* existing section that fits before adding a new one. Mapping:
@@ -234,10 +295,10 @@ For each 🔴 / 🟡 finding, draft the smallest possible edit that, **if it had
   | glossary / context term clarification | `## Glossary alignment` |
   | rationale that doesn't fit elsewhere | `## Free notes` (one paragraph max, dated) |
 
-- One bullet per finding. Reference the evidence ticket ("S058 smoke name", "#103 missing disclaimer") so the line stays auditable.
+- One bullet per finding. Reference the evidence ticket ("S058 smoke name", "#103 missing parent ref") so the line stays auditable.
 - Do **not** invent new top-level sections unless three findings legitimately share one.
 
-Show all drafts as one unified diff per target file before applying. Group by target file: pi-dev's `skills/<name>/SKILL.md` first (framework), then the consumer's `docs/agents/preferences.md` (consumer-prefs).
+Show all drafts as one unified diff per target file before applying. Group by target file: pi-dev's `extensions/pi-flow/index.ts` first (extension), then `skills/<name>/SKILL.md` (framework), then the consumer's `docs/agents/preferences.md` (consumer-prefs).
 
 ### 7 — Apply, release, verify (branches on scope)
 
@@ -250,6 +311,16 @@ Run both branches if the audit produced mixed-scope findings. Each branch has it
 3. `git push origin main`; release-please opens the version-bump PR; merge it; npm publish runs automatically.
 4. Confirm `npm view pi-dev@latest version` matches the bumped tag.
 
+**7a′. Extension branch** — only if any finding was approved as `extension`:
+
+1. Edit `extensions/pi-flow/index.ts` (or, only if justified by Step 5.5 bar, add a new `extensions/<name>/` directory with `index.ts`, `package.json`, `README.md`).
+2. If a new extension was added, register it in `src/install.ts` `EXTENSIONS` array so `pi-dev install` and `pi-dev update` propagate it.
+3. `npm run build` to ensure `install.ts` still compiles.
+4. Smoke-test with `node dist/cli.js install --local --skip-prefs -y` in `/tmp/<fresh-dir>`. Verify the extension landed under `.pi/extensions/<name>/`.
+5. `git add extensions/<name>/ src/install.ts src/paths.ts && git commit -m "feat(pi-flow): <one-liner anchoring the evidence>"`. Commit body must cite the signal.
+6. Mirror to live: `cp -r extensions/<name> ~/.pi/agent/extensions/<name>` so the **next** session picks up the change without waiting for npm.
+7. `git push origin main`; release-please → npm publish as usual.
+
 **7b. Consumer-prefs branch** — only if any finding was approved as `consumer-prefs`:
 
 1. In the audited consumer repo: edit `docs/agents/preferences.md` per the drafts from Step 6. Keep the migration marker at the very end of the file undisturbed.
@@ -260,7 +331,7 @@ Run both branches if the audit produced mixed-scope findings. Each branch has it
 **Verification (both branches).** After the next pi session in the affected repo:
 
 1. Re-run **this skill** scoped to the last 24 h.
-2. Confirm each previously-🔴 signal has moved (chain depth up, intervention rate down, taboo writes gone, disclaimer coverage at 100%, etc.).
+2. Confirm each previously-🔴 signal has moved (chain depth up, intervention rate down, taboo writes gone, etc.).
 3. If a signal did not move, the fix wording was too weak — file a follow-up audit, do not re-write from scratch.
 
 ## Terminal predicate
@@ -268,9 +339,9 @@ Run both branches if the audit produced mixed-scope findings. Each branch has it
 This skill is done when **all four** are true:
 
 1. A signal table with severities and evidence excerpts has been presented.
-2. Each finding has an approved scope (`framework` / `consumer-prefs` / `defer`) on record, defaulted by Step 5.5 and confirmed by the maintainer.
+2. Each finding has an approved scope (`framework` / `extension` / `consumer-prefs` / `defer`) on record, defaulted by Step 5.5 and confirmed by the maintainer.
 3. Either (a) zero 🔴 findings — flow is healthy, recorded as "no change this cycle", OR (b) each 🔴 finding has landed in its scope's target file.
-4. For any landed change: if `framework`, the npm version has bumped (`npm view pi-dev@latest version`); if `consumer-prefs`, the consumer repo has the commit on its push-stream. Either way, the next-session re-audit plan is stated.
+4. For any landed change: if `framework` or `extension`, the npm version has bumped (`npm view pi-dev@latest version`) and the live mirror is in place; if `consumer-prefs`, the consumer repo has the commit on its push-stream. Either way, the next-session re-audit plan is stated.
 
 The summary's **last line** must be one of:
 

package/skills/to-issues/SKILL.md

@@ -55,11 +55,7 @@ For each approved slice, publish a new issue to the issue tracker. Use the issue
 
 Publish issues in dependency order (blockers first) so you can reference real issue identifiers in the "Blocked by" field.
 
-**Every issue body MUST start with the AI disclaimer** (same wording as `/triage`). This is a hard requirement — no exceptions, including auto-generated slices. After writing the body, grep your own draft for the disclaimer string; if missing, do not publish.
-
 <issue-template>
-> *This was generated by AI during triage.*
-
 ## Parent
 
 A reference to the parent issue on the issue tracker (if the source was an existing issue, otherwise omit this section).
@@ -82,15 +78,13 @@ Or "None - can start immediately" if no blockers.
 
 </issue-template>
 
-**Publishing pattern (GitHub).** Use `--body-file -` with a heredoc, never inline `--body "..."`, so the disclaimer and markdown structure survive shell quoting verbatim:
+**Publishing pattern (GitHub).** Use `--body-file -` with a heredoc, never inline `--body "..."`, so markdown structure survives shell quoting verbatim:
 
 ```bash
 gh issue create \
   --title "[Slice N] <title>" \
   --label needs-triage \
   --body-file - <<'EOF'
-> *This was generated by AI during triage.*
-
 ## Parent
 #<parent>
 
@@ -99,11 +93,4 @@ gh issue create \
 EOF
 ```
 
-After creation, immediately verify the disclaimer landed:
-
-```bash
-gh issue view <n> --json body --jq '.body' | head -1 | grep -q 'generated by AI' \
-  || echo "FAIL: disclaimer missing on #<n>"
-```
-
 Do NOT close or modify any parent issue.

package/skills/triage/SKILL.md

@@ -7,12 +7,6 @@ description: Triage issues through a state machine driven by triage roles. Use w
 
 Move issues on the project issue tracker through a small state machine of triage roles.
 
-Every comment or issue posted to the issue tracker during triage **must** start with this disclaimer:
-
-```
-> *This was generated by AI during triage.*
-```
-
 ## Reference docs
 
 Before acting on the issue tracker, read the repo-local setup docs if they exist: