pi-dev 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-dev",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "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

@@ -27,6 +27,22 @@ The point: **never edit a SKILL.md from gut feeling.** Edit because session N sh
 - **Target repo path** (or its sessions directory). Defaults: the user names a repo; you resolve it.
 - Optional: a specific skill name to focus the audit on (`do`, `migrate`, `triage`, …).
 - Optional: a date range.
+- **Install scope** for any fixes that come out of the audit — `global` or `project`. Auto-detected (see Step 5.5); user can override per finding.
+
+## Install scopes
+
+pi-runtime today loads skill bodies from a single location: `~/.pi/agent/skills/<name>/SKILL.md`. The framework's 3-layer override is on **preferences**, not on SKILL bodies. So a finding lands in one of two places:
+
+| scope | lands in | reaches | propagation | when to pick |
+| --- | --- | --- | --- | --- |
+| **global** | `pi-dev`'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 |
+| **project** | consumer repo's `docs/agents/preferences.md` (Project taboos / Diagnosis posture / Local-live playbook / Free notes — whichever section fits) | only this repo, on every `/do` bootstrap | regular consumer-repo commit | gap is the repo's domain / paths / conventions, not the SKILL.md |
+
+Notes:
+
+- A `global` apply is **always** mirrored into `~/.pi/agent/skills/<name>/` on the operator's machine so the next session picks it up immediately, without waiting for npm.
+- A `project` apply touches no pi-dev files. It is committed to the consumer repo only.
+- A single audit may produce a mix of global and project findings. Decide scope per finding, not per audit.
 
 ## Session-data location & format
 
@@ -141,33 +157,131 @@ For every 🔴 / 🟡 row, quote the smallest piece of evidence that makes the g
 
 If a finding cannot be backed by an excerpt, it is not actionable yet — demote to a TODO and keep digging.
 
-### 6 — Propose SKILL.md edits
+### 5.5 — Decide install scope per finding (auto + user-overridable)
+
+For each 🔴 / 🟡 finding, pick a default scope using this two-step heuristic, then show the table to the user once and let them flip individual rows before applying.
+
+**Step A — detect operator context.** Run once at the start of this step:
+
+```bash
+origin=$(git -C "$PWD" remote get-url origin 2>/dev/null || echo "")
+pkg_name=$(jq -r '.name // empty' package.json 2>/dev/null)
+is_maintainer=false
+case "$origin" in *pi-dev*|*pi-dev.git) is_maintainer=true ;; esac
+[ "$pkg_name" = "pi-dev" ] && is_maintainer=true
+echo "operator_context=$([ \"$is_maintainer\" = true ] && echo maintainer || echo consumer)"
+```
+
+- `operator_context=maintainer` → cwd is the pi-dev repo itself; the release path is available.
+- `operator_context=consumer` → cwd is a downstream repo; no release path. `global` findings here become "draft a patch + open an upstream PR / issue" rather than "push and release".
+
+**Step B — score each finding.** Default to `global` if the finding matches **any** of:
+
+- Cites SKILL.md wording / phase / predicate / rule numbers.
+- 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.
+
+Default to `project` if the finding matches **any** of:
+
+- 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.
+
+Present the scope-decision table:
+
+```
+| # | finding (short)                          | default scope | target file                          | flip? |
+| - | ---------------------------------------- | ------------- | ------------------------------------ | ----- |
+| 1 | /do hands flow back between phases       | global        | pi-dev:skills/do/SKILL.md            |       |
+| 2 | docs/handoff/ resurrected after marker   | global        | pi-dev:skills/migrate/SKILL.md       |       |
+| 3 | retro-action-item label still alive      | project       | hugn:docs/agents/preferences.md      |       |
+| 4 | smoke command name changed in S058       | project       | hugn:docs/agents/preferences.md      |       |
+```
+
+Ask the user once: "OK to proceed with these scopes? Reply with row numbers to flip, or `go`." Apply their flips and move on. If `operator_context=consumer`, any rows still marked `global` get the suffix `(via upstream PR — cannot release locally)` and the apply step adjusts accordingly.
+
+### 6 — Propose edits (per-finding, scoped)
+
+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:
 
-For each 🔴 finding, draft the smallest possible edit that, **if it had been in the SKILL.md at session time, would have prevented the gap.** Constraints:
+**Global findings (target: pi-dev SKILL.md):**
 
 - 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 **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.
 
-Show the edits as a unified diff before applying.
+**Project findings (target: consumer's `docs/agents/preferences.md`):**
 
-### 7 — Apply, release, verify
+- Pick the *narrowest* existing section that fits before adding a new one. Mapping:
 
-Standard pi-dev release loop:
+  | 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) |
 
-1. `git add skills/<name>/SKILL.md && git commit -m "<conventional commit anchoring the evidence>"` — the commit body should cite the signal that motivated each change.
-2. `cp` the edited SKILL.md into `~/.pi/agent/skills/<name>/` so the **next** session in any repo picks up the change immediately (release-please takes a minute and a half).
+- One bullet per finding. Reference the evidence ticket ("S058 smoke name", "#103 missing disclaimer") 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 (global), then consumer's `docs/agents/preferences.md` (project).
+
+### 7 — Apply, release, verify (branches on scope)
+
+Run both branches if the audit produced mixed-scope findings. Each branch has its own terminal state.
+
+**7a. Global branch** — only if any finding was approved as `global` **and** `operator_context=maintainer`:
+
+1. From the pi-dev checkout: `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. After the next consumer session lands, re-run **this skill** and confirm the targeted signals moved.
+4. Confirm `npm view pi-dev@latest version` matches the bumped tag.
+
+**7a' — Global findings when `operator_context=consumer`:** you cannot release. Instead:
+
+1. Stash the proposed diffs to `/tmp/pi-dev-upstream-<date>.patch` with one file per skill.
+2. Open an issue on `pi-dev` (or a PR if the operator has clone+push rights) with the evidence excerpts and the patch attached.
+3. As a hotfix for this machine only, optionally `cp` the edited bodies into `~/.pi/agent/skills/<name>/` and note in the issue that the next `pi-dev update` will overwrite them — which is the desired end state once the upstream change lands.
+
+**7b. Project branch** — only if any finding was approved as `project`:
+
+1. In the 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 the repo's normal workflow. No release-please involvement — preferences are not packaged.
+
+**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.).
+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
 
-This skill is done when **all three** are true:
+This skill is done when **all four** are true:
 
 1. A signal table with severities and evidence excerpts has been presented.
-2. Either (a) zero 🔴 findings — flow is healthy, recorded as "no change this cycle", OR (b) a unified diff for each 🔴 finding has been applied to `skills/<name>/SKILL.md` AND mirrored into `~/.pi/agent/skills/<name>/`.
-3. If diffs landed, the release loop (commit → push → merge release PR → npm publish) finished and the new version is `npm view pi-dev@latest version`.
+2. Each finding has an approved scope (`global` / `project` / `defer`) on record, defaulted by Step 5.5 and confirmed by the user.
+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 (or been stashed + filed upstream when an operator-context mismatch prevents release).
+4. For any landed change: if `global` and `maintainer`, the npm version has bumped (`npm view pi-dev@latest version`); if `project`, 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:
+
+```
+audit complete — no changes this cycle.
+```
+
+```
+audit complete — global v<X.Y.Z> released, project commit <sha>, next re-audit after the next session.
+```
+
+```
+audit complete — upstream issue <#N> filed, project commit <sha>, hotfix mirrored to ~/.pi.
+```
 
 ## What this skill does not do