npm - pi-dev - Versions diffs - 0.2.8 → 0.2.9 - Mend

pi-dev 0.2.8 → 0.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/package.json +1 -1
package/skills/improve-skill-flow/SKILL.md +131 -307

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "pi-dev",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "An autonomous engineering skill framework for the pi runtime — built on Matt Pocock's skills.",
   "type": "module",
   "bin": {

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

@@ -1,31 +1,25 @@
 ---
 name: improve-skill-flow
-description: MAINTAINER-ONLY. Analyse real pi-runtime session telemetry from any consumer repo on this machine to find where the engineering skills (especially /do's chain) drift from their stated contract, then propose evidence-anchored edits to pi-dev's own SKILL.md files. Run only from inside the pi-dev repo — it edits pi-dev sources and triggers a release. Use when the maintainer wants to improve, audit, debug, or evolve the pi-dev skill framework itself based on what actually happened in real sessions ("스킬 개선하자", "do 가 왜 멈춰", "히스토리 보고 분석해서 스킬 고치자", "메타 스킬 작업", etc).
+description: MAINTAINER-ONLY. Analyse real pi-runtime session telemetry from consumer repos to find where the engineering lifecycle, especially /do, drifts from its contract; then apply the smallest evidence-backed framework, runtime, or consumer-prefs improvement. Run only from the pi-dev repo.
 ---
-# /improve-skill-flow — Meta-skill for evidence-based skill improvement
-**Audience: pi-dev maintainers only.** Consumers do not get this skill installed. Consumers improve their own setup by editing `docs/agents/preferences.md` (per project) or `~/.pi/agent/preferences.md` (per machine), not by editing SKILL.md bodies. The framework is fixed for them; only the maintainer changes it.
-The pi-dev workflow is not just markdown. It is a layered control system: SKILL.md prose, repo preferences, pi-runtime lifecycle events, tools, commands, TUI surfaces, session persistence, compaction hooks, and extensions. This skill reads what real sessions did across consumer repos, compares that to what the workflow contract said *should* happen, then chooses the lightest effective intervention.
-The point: **never improve the framework from gut feeling, never collapse every fix into a "guard", and never append diary-style history.** Edit because session N showed phase P violated predicate Q on M occasions, then decide whether the right response is clearer prose, repo-local preferences, a runtime steer, a custom tool, a command, a TUI affordance, state persistence, compaction/context shaping, or — only when the evidence calls for it — a blocking gate. Every wording change must pay rent: reduce future confusion, replace weaker text, merge duplicate rules, or delete obsolete context.
+# /improve-skill-flow — Evidence loop for the pi-dev workflow
 ## North star
-`/do` is the autonomous engineering lifecycle orchestrator. Its job is not to perform one isolated action; its job is to carry a request through the agreed lifecycle in order — classify, scope, plan, run the right skills, satisfy each phase predicate, verify locally/live as required, apply side effects according to prefs, and finish with durable state in code / issues / preferences. The framework's product goal is to make that A→Z loop long-running, durable, low-interruption, and trustworthy across real repos.
+`/do` is the autonomous engineering lifecycle orchestrator. It should carry a request A→Z: classify → scope → plan → run phases in order → satisfy terminal predicates → verify → apply side effects per prefs → leave durable state in code / issues / preferences. This skill audits whether that lifecycle happened in real sessions and improves the framework so the next run is more autonomous, durable, low-interruption, and correct.
-Therefore `/improve-skill-flow` audits **lifecycle adherence**, not just individual mistakes. A session that eventually shipped after repeated user nudges, skipped verification, wrong side effects, or unordered phases is not healthy. The improvement question is: what framework / preference / runtime support would have let `/do` complete the full lifecycle autonomously and correctly the first time?
+Do not append diary history. Every edit must pay rent by removing ambiguity, replacing weaker text, merging duplicates, deleting stale rationale, or adding a runtime affordance that measurably improves the lifecycle.
-## Pre-flight (hard gate)
+## Pre-flight gate
-Refuse to run unless cwd is the pi-dev repo. Releases happen from here; nothing else makes sense.
+Run only from the pi-dev checkout:
 ```bash
 origin=$(git -C "$PWD" remote get-url origin 2>/dev/null || echo "")
 pkg_name=$(jq -r '.name // empty' package.json 2>/dev/null)
 ok=0
-case "$origin" in *pi-dev*|*pi-dev.git) ok=1 ;; esac
+case "$origin" in *pi-dev*|*pi-dev.git|*pi-flow*|*pi-flow.git) ok=1 ;; esac
 [ "$pkg_name" = "pi-dev" ] && ok=1
 if [ "$ok" != 1 ]; then
   echo "this skill is maintainer-only; cd into the pi-dev repo and re-run"
@@ -33,375 +27,205 @@ if [ "$ok" != 1 ]; then
 fi
 ```
-If the gate fails, stop. Do not proceed in a consumer repo.
-## When to run
-- A consumer repo on this machine has accumulated at least one real day of pi sessions (≈ 3+ `.jsonl` files).
-- A specific skill is suspected of misbehaving ("why does `/do` keep stopping?").
-- After landing a skill change, to verify the next session(s) actually follow the new wording.
-- Periodically (every N releases) as a regression sweep across all human-facing skills.
-Always from inside the pi-dev checkout (see Pre-flight).
-## What this skill is NOT
-- Not for analysing the *codebase* of any repo — that is `improve-codebase-architecture`.
-- Not for shipping engineering work — it does not invoke `/do`. Findings turn into proposed SKILL.md diffs, which are committed via the normal release-please flow on `pi-dev`.
-- Not a real-time monitor — it reads completed session files.
-- Not a consumer-facing tool. Consumers don't get this skill installed; they tune their setup via `preferences.md`, not by editing SKILL bodies.
+If the gate fails, stop.
 ## Inputs
-- **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`, `extension`, or `consumer-prefs`. Defaults set in Step 5.5; maintainer can flip individual rows before applying.
-## Fix scopes
-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.
-- **Runtime interventions** — extensions under `~/.pi/agent/extensions/<name>/` (global) or `<repo>/.pi/extensions/<name>/` (local). TypeScript modules auto-loaded via jiti. They can subscribe to lifecycle/session/agent/model/tool events, inject context in `before_agent_start`, reshape model context, observe `message_end`, intercept or modify tool calls/results, register custom tools/commands/shortcuts/flags, prompt via `ctx.ui`, render custom TUI widgets, persist state with `pi.appendEntry()`, and customize compaction/session behavior. pi-dev ships **one** extension by default — `pi-flow` — and the bar to add a second package remains high.
-- **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 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 / prefs cannot reliably preserve the workflow, AND pi-runtime has an event/tool/UI/state hook that can make the desired path easier, more observable, or safer |
-| **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 all three. Decide scope per finding, not per audit.
-**Extension scope is the most expensive option, but it is not synonymous with "guards".** Runtime interventions can be passive observability, progress/status UI, context injection, command shortcuts, structured tools, state checkpoints, compaction shaping, soft steers, confirmations, or hard blocks. Default to `framework` / `consumer-prefs` when prose or repo-local convention plausibly fixes the gap; reach for `extension` when the audit shows the workflow needs runtime support.
+Ask once only if missing:
-Intervention ladder, from lightest to strongest:
+- target consumer repo path, sessions dir, or "all repos with sessions"
+- focus skill (`do`, `triage`, `migrate`, …) or "everything"
+- date range or "all"
-1. **Observe** — collect counters / emit low-noise status so the next audit can see what happened.
-2. **Make the right path easier** — custom command, custom tool, context injection, remembered state, or TUI affordance.
-3. **Steer** — inject a follow-up message or system/context nudge when the model is drifting but no irreversible action happened.
-4. **Confirm** — ask the user only for genuinely risky or preference-silent operations.
-5. **Block** — refuse a tool call only for destructive, costly, or repeatedly proven workflow violations.
+## Fix targets
-The bar for extension work:
+| target | lands in | use when |
+| --- | --- | --- |
+| `framework` | `skills/<name>/SKILL.md` | generic prose contract is wrong, missing, duplicated, or ambiguous |
+| `extension` | `extensions/pi-flow/` or rare new extension | runtime support would make the correct lifecycle easier, visible, recoverable, or safer |
+| `consumer-prefs` | audited repo's `docs/agents/preferences.md` | repo-specific convention, path, smoke, glossary, env, tracker, or taboo |
+| `defer` | no edit | evidence is weak, already fixed, or needs a next-session re-audit |
-- The failure is repeated or high-cost, and the expected workflow was available in-context via SKILL.md / prefs / repo docs.
-- The runtime intervention can be described as a small event-driven mechanism over pi's lifecycle/session/agent/tool/UI/state surfaces; no hidden LLM call unless the finding is explicitly about a summarizer/evaluator extension.
-- The success metric is measurable in the next audit: fewer user nudges, higher `/do` phase completion, fewer corrections, better issue shape, shorter stalled intervals, or clearer live evidence.
-- A simpler remedy (docs wording, prefs, `.gitignore` lockout, issue-template fix) does **not** plausibly close the gap. If it does, take the simpler remedy.
+Mirror framework edits to `~/.pi/agent/skills/<name>/`. Mirror extension edits to `~/.pi/agent/extensions/<name>/`. Consumer-prefs edits stay in the consumer repo.
-External research posture (DECAY): before proposing a new class of runtime intervention, do a quick current-source pass. 2025–2026 agent-reliability literature emphasizes trajectory monitoring, workflow-level observability, recovery orchestration, and textual feedback from traces — not just pre-execution blocking. Use that as a check against over-fitting on "guards"; cite the sources in the audit notes when they shape the proposal.
+Runtime intervention is not synonymous with a guard. Consider the ladder: `observe → affordance/tool/command → context/state/render → steer → confirm → block`. Pick the weakest intervention that would have changed the audited session outcome, and define a next-audit metric for it.
-## Session-data location & format
+## Session facts to rely on
-pi-runtime persists every session as JSON Lines at:
+Sessions live at:
-```
+```text
 ~/.pi/agent/sessions/--<cwd-with-slashes-replaced-by-dashes>--/<ISO-ts>_<uuid>.jsonl
 ```
-For example `cwd=/Users/jason/dev/sandbox/hugn` → `~/.pi/agent/sessions/--Users-jason-dev-sandbox-hugn--/`.
-Each line is one of these record types:
-| `type` | meaning |
-| --- | --- |
-| `session` | session header — has `cwd`, `timestamp`, `version`, `id` |
-| `model_change` | provider / modelId switch |
-| `thinking_level_change` | reasoning effort knob |
-| `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`:
-| block `type` | shape | what it represents |
-| --- | --- | --- |
-| `text` | `{text}` | plain text from either side |
-| `thinking` | `{thinking, thinkingSignature}` | model scratchpad (assistant only) |
-| `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.
+Message records are nested. Always read `rec["message"]["role"]` and `rec["message"]["content"]`, never top-level `role/content`. `toolResult` is a message role and also a block type; do not count toolResult-role messages as user/assistant turns. Pi tool calls are content blocks with `type == "toolCall"` and lower-case `name` (`bash`, `read`, `edit`, `write`, …). Skill injections arrive as `<skill name="...">` blocks inside **user-role** messages.
-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:
+Parser pre-flight is mandatory on the newest 1–2 work sessions:
 ```python
-assert tool_count, "toolCall extraction returned 0 — check rec['message']['content'], not rec['content']"
+assert tool_count, "toolCall extraction returned 0 — check rec['message']['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.
+A zero-row signal table is a parser bug, not a finding.
 ## Process
 ### 1 — Scope and load
-Ask the maintainer (one round, only if not already specified):
-- target consumer repo (or "all repos with sessions on this machine")
-- a skill to focus on, or "everything"
-- a date range or "all"
-Resolve the sessions directory. List the `.jsonl` files with size + line count so the maintainer can see the input scale.
+Resolve the sessions directory. List candidate `.jsonl` files with size + line count. Use the requested range; otherwise default to all relevant files for the named repo(s).
 ### 2 — Build the raw signal table
-Run a single pass over every targeted `.jsonl` and tally:
-**Per session:**
-- user messages, assistant messages, tool calls, thinking blocks
-- duration (last ts − first ts)
-**Aggregates:**
-- tool-use frequency (`bash`, `read`, `edit`, `write`, …)
-- `<skill name="X">` injections per skill (this is the classifier's actual decision)
-- skills mentioned in user text vs. assistant text (request side vs. recall side)
-- top Edit / Write targets (hotspot files)
-- bash commands matching domain-specific danger / smell patterns
-**Workflow-compliance specific:**
-- Reconstruct `/do`'s lifecycle trajectory: classify → scope → plan → phase execution → terminal predicates → verification → side effects → durable final state. Score the ordered lifecycle, not just the final outcome.
-- After each `<skill name="do">` injection, did another skill get injected within the same session? **This measures `/do` chain depth.** Single-step chains are a red flag, but not the whole story.
-- Did `/do` emit `[flow plan]`? Count planned phases and observed `[flow N/M]` status lines. Flag: plan missing, N/M skipped, final summary before all phases, or terminal predicate not evidenced.
-- 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.
-- Detect stalled intervals: long gaps between assistant text / tool calls, repeated identical commands, or repeated failed live probes beyond the repo's wait budget.
-- Count local-live / ops-live evidence when runtime behavior changed: command run, observed output, log/screenshot/evidence embedded in summary.
-- Count side-effect gates: commits, pushes, PRs, issue creates/edits/closes vs. merged prefs (`auto-*`) and tracker docs.
-- 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 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, wrong state labels, wrong parent topology, etc.) rather than meta tags.
+Use one deterministic script in `/tmp`; do not eyeball JSONL by hand. Tally:
-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.
+- per session: duration, user/assistant/toolResult messages, tool calls, thinking blocks
+- tools used; edit/write targets; selected bash commands (`git`, `gh`, `npm publish`, dangerous or repo-specific patterns)
+- skill injections and sequence, especially `/do` → next skill
+- short user nudges and correction markers (`아니`, `왜`, `??`, `wait`, `stop`, `undo`, `revert`, `제대로`)
+- tracker writes and issue/PR body shape
+- post-migration writes to forbidden state paths
-### 3 — Cross-reference with repo state
-For the same date range, pull (against the **consumer repo** being audited):
-- `git log --since=<start> --pretty=format:"%h %ad %s"` — commit cadence vs. the predicate `auto-commit-per-slice`.
-- `gh issue list / pr list` (if GitHub) — slice/PR shape vs. `default-issue-style=vertical-slice`.
-- Existence of forbidden paths from `docs/agents/preferences.md` taboos (`docs/handoff/`, `.scratch/flow/`, etc.).
-- `gh label list` filtered against taboo-marked labels.
-Cross-reference each signal against:
-- The skill's **terminal predicate** in `do/SKILL.md` → "Phase contracts".
-- The consumer repo's **`docs/agents/preferences.md`** taboos and `auto-*` settings.
-- The hard rules in the skill being audited.
-### 4 — Score the gaps
-Produce a small table per audited skill. Each row:
+For `/do`, reconstruct the ordered lifecycle:
+```text
+classify → scope → plan → phase execution → terminal predicates → verification → side effects → durable final state
 ```
-| signal                         | observed | expected (predicate / rule)        | severity |
-| ------------------------------ | -------- | ---------------------------------- | -------- |
-| /do → next-skill chain depth   | 1/5      | ≥1 per chain step (M phases)       | 🔴       |
-| /do hand-back via follow-up    | 8/13     | 0 mid-chain hand-backs             | 🔴       |
-| post-marker handoff writes     | 9        | 0                                  | 🟡       |
-| ...                            |          |                                    |          |
-```
-Severity rule of thumb:
-- 🔴 — predicate is violated repeatedly AND the rule is binding (in "Hard rules" or "Phase contracts").
-- 🟡 — taboo or preference violated but the skill's wording is soft / advisory.
-- 🟢 — observed behaviour matches the spec; do not propose a change.
-### 5 — Anchor each finding to an evidence excerpt
+Flag missing `[flow plan]`, skipped `[flow N/M]`, final summary before all phases, terminal predicates without evidence, missing local/ops-live evidence, side effects that contradict prefs, repeated failed commands, stalls beyond wait budget, or user re-entry nudges.
-For every 🔴 / 🟡 row, quote the smallest piece of evidence that makes the gap undeniable:
+### 3 — Cross-reference live repo state
-- a user message timestamp + first 80 chars,
-- a tool-call command that violates a taboo,
-- the first 80 chars of an issue body that violates the slice template.
+Against the audited repo, bounded by the same date range:
-If a finding cannot be backed by an excerpt, it is not actionable yet — demote to a TODO and keep digging.
-### 5.5 — Decide fix scope per finding (auto + maintainer-overridable)
-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.
-Before assigning scope, write one sentence answering: **what would have made the correct workflow easier to follow at the moment of failure?** Do not jump straight to a blocking guard.
+```bash
+git log --since=<start> --pretty=format:"%h %ad %s" --date=short | head -50
+git status -sb
+find docs/handoff .scratch/flow .handoff -type f 2>/dev/null | head
+# if GitHub is the tracker:
+gh issue list --state open --limit 20 --json number,title,labels,url
+gh pr list --state open --limit 20 --json number,title,url
+```
-Default to `extension` if the finding matches **any** of:
+Read `docs/agents/preferences.md`, `issue-tracker.md`, `triage-labels.md`, and `domain.md`. Compare observed behavior to `/do` phase predicates, hard rules in the focused skill, and merged prefs.
-- The expected behavior was already in SKILL.md / prefs / repo docs at the time of the violating session **and** the session still drifted repeatedly or expensively.
-- The fix needs runtime affordance rather than prose: observe counters, inject context, add a command/tool, show TUI status, persist/checkpoint state, shape compaction/context, steer after a message, confirm a risky action, or block an unsafe tool call.
-- The success condition can be measured in the next session from telemetry, not merely hoped for from stronger wording.
+### 4 — Score gaps
-When defaulting to `extension`, classify the intervention type: `observe`, `affordance`, `context`, `state`, `render`, `steer`, `confirm`, or `block`.
+Produce a compact table per audited skill:
-Default to `framework` if the finding matches **any** of:
+```markdown
+| signal | observed | expected | severity |
+| --- | --- | --- | --- |
+| /do lifecycle completion | 2/7 phases evidenced | all planned phases + predicates | 🔴 |
+```
-- 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.
+Severity:
-Default to `consumer-prefs` if the finding matches **any** of:
+- 🔴 repeated or high-cost violation of a hard rule / phase predicate / lifecycle step
+- 🟡 preference or taboo drift, weak wording, noisy but plausible signal
+- 🟢 healthy; do not propose a change
-- Cites a repo-specific path (`src/core/...`, `bin/...-smoke.ts`), brand, schema, table, or domain term.
-- The fix is a taboo, a smoke convention, an env / boot detail, or a glossary entry.
-- The fix would not apply (or would be wrong) in another consumer repo.
+### 5 — Anchor evidence
-Present the scope-decision table:
+For every 🔴 / 🟡 row, quote the smallest proof: timestamp + first 80 chars of a user correction, assistant hand-back, tool command, path write, or issue body. No excerpt → demote to TODO and keep digging.
-```
-| # | finding (short)                          | default scope    | target file                                          | flip? |
-| - | ---------------------------------------- | ---------------- | ---------------------------------------------------- | ----- |
-| 1 | /do hands flow back between phases       | extension:steer  | pi-dev:extensions/pi-flow/index.ts (message_end)     |       |
-| 2 | long live-smoke silence causes user nudges | extension:render/observe | pi-dev:extensions/pi-flow/index.ts or project extension |       |
-| 3 | post-marker handoff writes               | framework        | pi-dev:skills/migrate/SKILL.md (gitignore lockout)   |       |
-| 4 | smoke command name changed in S058       | consumer-prefs   | hugn:docs/agents/preferences.md                      |       |
-```
+### 5.5 — Choose target and intervention type
-Ask once: "OK to proceed with these scopes? Reply with row numbers to flip, or `go`." Apply the flips and move on.
+Before choosing, answer one sentence:
-### 6 — Propose edits (per-finding, scoped)
+> What would have made the correct lifecycle easier to follow at the moment of failure?
-For each 🔴 / 🟡 finding, draft the smallest possible edit that, **if it had been in place at session time, would have prevented the gap.** The shape of the draft depends on the scope from Step 5.5.
+Then choose:
-**Diet rule before any draft:** inspect the target section as a whole and decide whether the change should replace, merge, move, or delete existing text. Do not append a new historical note just because today's audit found a new incident. If the section would become longer without becoming clearer, rewrite the section instead. If two bullets now say the same thing, collapse them. If a rule only explains why a past mistake happened but does not constrain future behavior, delete or compress it into the active rule.
+- `framework` when wording/ordering/terminal predicates are generically wrong or confusing.
+- `extension:<observe|affordance|context|state|render|steer|confirm|block>` when prose/prefs were available but runtime support is needed and next-session movement is measurable.
+- `consumer-prefs` when the fix is repo-specific.
+- `defer` when already fixed, weak, or better verified after another session.
-**Framework findings (target: pi-dev SKILL.md):**
+Show the scope table once and let the maintainer flip rows before applying.
-- Edit a **rule** or a **step**, not a flavour sentence. The model must be able to detect the constraint in its own draft output.
-- Prefer **replacement over accumulation**. A good edit often makes the skill shorter; adding lines is justified only when it removes a larger ambiguity.
-- Prefer **explicit anti-pattern strings** ("Do not say 'shall I continue?'") over abstract injunctions ("be decisive"). The hugn-2026-05 audit showed that named anti-patterns work.
-- 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.
+### 6 — Draft lean edits
-**Extension findings (target: pi-dev `extensions/pi-flow/index.ts`, or rarely a new `extensions/<name>/`):**
+Inspect the whole target section before drafting. Prefer replace/merge/delete over append. If the file grows, state what ambiguity the extra lines remove; otherwise rewrite shorter.
-- Start from pi's actual extension surface, not from the word "guard": lifecycle/session/agent/model/tool events, `before_agent_start` context injection, `context` shaping, `tool_call` / `tool_result` interception, registered tools, registered commands, `ctx.ui` notifications/widgets/custom UI, custom renderers, `pi.appendEntry()` state, and compaction/session hooks.
-- Prefer extending `pi-flow` when the concern is generic workflow compliance. Create a new extension only when the concern is large enough to be independently named, toggled, installed, and audited.
-- Pick the weakest intervention that would have changed the session outcome: observe → affordance → context/state/render → steer → confirm → block.
-- Determinism is mandatory for `confirm` and `block`; it is desirable but not sufficient for softer interventions. A progress widget, command shortcut, or state checkpoint can be valuable even when it does not block anything.
-- Runtime behavior must be toggleable via `~/.pi/agent/settings.json` when it can alter turns or tool execution. Default on only if the audit shows broad benefit.
-- Keep the corresponding SKILL.md prose as the human-readable contract: one-line *why*, the expected behavior, and a pointer to the runtime support. Do not delete the why — the model still needs to know the intent when the extension is off.
-- Update **at most one runtime mechanism per run** unless the second is pure observability. Two behavior changes at once destroys the next audit's ability to attribute movement.
+Framework edits:
-**Consumer-prefs findings (target: that repo's `docs/agents/preferences.md`):**
+- edit a rule, step, predicate, or anti-pattern the model can self-check
+- keep at most three skill files per run
+- remove obsolete or duplicate rationale while adding the fix
-- Pick the *narrowest* existing section that fits before adding a new one. Mapping:
+Extension edits:
-  | finding flavour | preferences section |
-  | --- | --- |
-  | forbidden path / file / module / command | `## Project taboos` |
-  | label / state / triage rule | `## Side-effect gates` or `## Project taboos` |
-  | smoke / test / endpoint convention | `## Smoke / test conventions` |
-  | boot / env / probe change | `## Local-live playbook` |
-  | error taxonomy / 5-axes / domain rule | `## Diagnosis posture` |
-  | glossary / context term clarification | `## Glossary alignment` |
-  | rationale that doesn't fit elsewhere | `## Free notes` (one paragraph max, dated) |
+- start from pi's actual surfaces: lifecycle/session/agent/model/tool events, `before_agent_start`, `context`, `tool_call`, `tool_result`, registered tools/commands, `ctx.ui`, custom rendering, `pi.appendEntry()`, compaction/session hooks
+- prefer `pi-flow` for generic lifecycle support; create a new extension only for a separately named/toggled concern
+- make turn/tool-altering behavior toggleable via `~/.pi/agent/settings.json`
+- change at most one runtime mechanism per run unless the second is pure observability
-- 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.
+Consumer-prefs edits:
-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).
+- use the narrowest existing section (`Project taboos`, `Smoke / test conventions`, `Local-live playbook`, `Diagnosis posture`, `Glossary alignment`, `Free notes`)
+- one auditable bullet per finding
+- keep the migration marker at EOF
-### 7 — Apply, release, verify (branches on scope)
+Show unified diffs before applying.
-Run both branches if the audit produced mixed-scope findings. Each branch has its own terminal state.
+### 7 — Apply, release, verify
-**7a. Framework branch** — only if any finding was approved as `framework`:
+Framework:
-1. From the pi-dev checkout (this repo): `git add skills/<name>/SKILL.md && git commit -m "<conventional commit anchoring the evidence>"`. Commit body must cite the signal that motivated each change.
-2. `cp` each edited SKILL.md into `~/.pi/agent/skills/<name>/` so the **next** session anywhere picks up the change immediately (release-please takes a minute and a half).
-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`:
+```bash
+git add skills/<name>/SKILL.md
+git commit -m "docs(<skill>): <evidence-anchored one-liner>"
+cp skills/<name>/SKILL.md ~/.pi/agent/skills/<name>/SKILL.md
+git push origin main
+# merge release-please PR; confirm npm view pi-dev version
+```
-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.
+Extension:
-**7b. Consumer-prefs branch** — only if any finding was approved as `consumer-prefs`:
+```bash
+npm run build
+node dist/cli.js install --local --skip-prefs -y   # in a temp dir; verify extension copied
+git add extensions/<name> src/install.ts src/paths.ts
+git commit -m "feat(pi-flow): <evidence-anchored one-liner>"
+cp -R extensions/<name> ~/.pi/agent/extensions/<name>
+git push origin main
+# merge release-please PR; confirm npm view pi-dev version
+```
-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.
-2. Bump the `last-updated` line at the top of the file to today's UTC date.
-3. `git add docs/agents/preferences.md && git commit -m "docs(agents): <one-liner per finding>"`. Conventional Commits apply.
-4. Push per that repo's normal workflow. No release-please involvement — preferences are not packaged.
+Consumer-prefs:
-**Verification (both branches).** After the next pi session in the affected repo:
+```bash
+# in consumer repo
+git add docs/agents/preferences.md
+git commit -m "docs(agents): <evidence-anchored one-liner>"
+# push per that repo's workflow
+```
-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, 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.
+After the next affected session, re-run this skill for the last 24 h and confirm the signal moved.
 ## Terminal predicate
-This skill is done when **all four** are true:
+Done when:
-1. A signal table with severities and evidence excerpts has been presented.
-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` 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.
+1. signal table + evidence excerpts are presented
+2. each 🔴 / 🟡 finding has target `framework` / `extension:*` / `consumer-prefs` / `defer`
+3. zero 🔴 findings are marked healthy/deferred with rationale, or each approved 🔴 has landed
+4. landed framework/extension changes are mirrored live and released to npm; consumer-prefs changes are committed in the consumer repo
+5. next-session re-audit plan is stated
-The summary's **last line** must be one of:
+Final line must be exactly one of:
-```
+```text
 audit complete — no changes this cycle.
+audit complete — framework v<X.Y.Z> released, consumer-prefs commit <sha-or-none>, next re-audit after the next session.
 ```
-```
-audit complete — framework v<X.Y.Z> released, consumer-prefs commit <sha>, next re-audit after the next session.
-```
-## What this skill does not do
-- It does not modify a consumer repo's code or issues. It edits **pi-dev's own `skills/`** (framework scope) and — only when the audit demands it — the consumer's `docs/agents/preferences.md` (consumer-prefs scope).
-- It does not invent gaps from first principles. Every finding must come from a session excerpt or a repo-state probe.
-- It does not run from a consumer repo. The Pre-flight gate refuses; cd into pi-dev first.
-- It does not run faster than the data allows — if there is only one session, run it but say so up front; the signal is noisy.
 ## Heuristics
-- **One screenful of signals beats a dashboard.** Most of the time three or four numbers tell the whole story.
-- **Judge `/do` by lifecycle completion, not skill injection alone.** Chain depth is useful, but the stronger metric is: classify/scope correct → plan emitted → phases run in order → terminal predicates evidenced → verification completed → side effects match prefs → durable state landed → user did not need to re-enter the chain.
-- **Short user messages are the cheapest interruption proxy.** Count them, then inspect the preceding assistant turn to classify why the user had to nudge.
-- **A taboo without a `.gitignore` lockout will resurrect.** If the same taboo file shows up across two audits, the fix belongs in `/migrate`, not `/do`.
-- **Do not overfit on guards.** The intervention may be an observability counter, status widget, custom command, context injection, state checkpoint, prompt/compaction shaping, soft steer, confirmation, or block. Pick by evidence and measured failure cost.
-- **Trajectory beats scalar success.** A task that eventually shipped after five corrections is not healthy; use the session trace to find where workflow support was missing.
-- **Refresh external reliability patterns when designing new runtime support.** Current agent-reliability work emphasizes trajectory monitoring, recovery orchestration, and trace-derived textual feedback; use that to challenge pi-flow designs before coding.
-- **Keep the skills lean.** Do not turn audits into append-only history. Prefer section rewrites, merged bullets, and deletion of stale rationale over adding another paragraph. If a skill crosses ~500 lines, treat that as a smell and look for compression before adding more.
-## Why this skill exists
-Skills are prose. Prose drifts. Without a feedback loop, the SKILL.md files become wishful thinking that the agent ignores in real sessions. This skill is the loop — and it is the maintainer's loop, not the consumer's.
+- Judge `/do` by lifecycle completion, not by isolated success.
+- Short user nudges are interruption smoke; inspect the preceding assistant turn.
+- A task that ships after many corrections is not healthy; trace where autonomy failed.
+- Do not overfit on guards; runtime support can observe, guide, remember, render, steer, confirm, or block.
+- Keep skills lean. Around 500 lines is a smell; compress before adding.
+- For new runtime-support patterns, verify current agent-reliability sources and cite them in audit notes.