pi-dev 0.1.6 → 0.1.8

package/README.md

@@ -42,21 +42,34 @@ You ask. It classifies. It executes. It reports.
 Requires Node ≥ 20 and the [pi runtime](https://github.com/badlogic/pi).
 
 ```bash
-# Install the skills + seed your global preferences
+# Interactive: pick global vs project-local, then install + seed preferences
 npx pi-dev@latest install
 
-# Refresh skills only (keeps your preferences as-is)
+# 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)
+
+# Refresh skills (auto-detects scope from disk; preferences are kept)
 npx pi-dev@latest update
 
-# See what's installed
+# See what's installed under each scope
 npx pi-dev list
 
-# Verify your environment
+# Verify the active scope's layout
 npx pi-dev doctor
 ```
 
-`install` copies the skill folders to `~/.pi/agent/skills/` (where the pi runtime looks) and seeds `~/.pi/agent/preferences.md` only if you don't already have one.
-`update` refreshes skill folders but leaves your preferences alone unless you pass `--include-prefs`.
+**Scope choice cheat-sheet:**
+
+| | global | local |
+| --- | --- | --- |
+| Skills | `~/.pi/agent/skills/` | `<repo>/.pi/skills/` |
+| 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 |
+
+Non-interactive runs (CI, piped input) default to `--global` silently. Pass `-y` to skip the prompt and accept the default.
 
 ## How `/do` actually flows
 

package/dist/cli.js

@@ -9,20 +9,30 @@ function help() {
     console.log(`pi-dev — autonomous engineering skill framework for the pi runtime
 
 Usage:
-  pi-dev install [--skip-prefs]       Copy skills into ~/.pi/agent/skills and seed
-                                       ~/.pi/agent/preferences.md if missing.
-  pi-dev update [--include-prefs]     Refresh skills. By default keeps your global
-                                       preferences. Pass --include-prefs to overwrite.
-  pi-dev list                         Show installed skills + global prefs path.
-  pi-dev uninstall <skill>            Soft-remove a skill (renamed to .removed-…).
-  pi-dev doctor                       Check ~/.pi layout and external CLIs.
-  pi-dev version                      Print version.
-  pi-dev help                         This message.
+  pi-dev install [scope] [--skip-prefs] [-y]
+      Install skills + seed preferences. Scope is one of:
+        --global   ~/.pi/agent/skills/   (default, every pi session sees it)
+        --local    .pi/skills/ in cwd    (only this repo)
+      Without a flag, an interactive TTY is prompted; non-TTY defaults to global.
+      Pass -y to skip the prompt and accept the default.
+
+  pi-dev update [--include-prefs] [--global|--local]
+      Refresh skills in place. Scope is auto-detected from disk
+      (local wins if .pi/skills/ exists in cwd). Preferences are kept by default;
+      pass --include-prefs to re-seed.
+
+  pi-dev list                 Show installed skills under both scopes (if present).
+  pi-dev uninstall <skill> [--global|--local]
+                              Soft-remove a skill (renamed to .removed-…).
+  pi-dev doctor               Check the active scope's layout and external CLIs.
+  pi-dev version              Print version.
+  pi-dev help                 This message.
 
 After install, in any pi session, you primarily call:
-  /do      — the one-shot engineering entry point
-  /taste   — view or update preferences
-  /where   — recall prior pi sessions for this cwd
+  /do                     — the one-shot engineering entry point
+  /taste                  — view or update preferences
+  /where                  — recall prior pi sessions for this cwd
+  /improve-skill-flow     — audit pi sessions, propose evidence-based skill edits
 
 All other skills are invoked automatically by /do.
 `);
@@ -30,44 +40,61 @@ All other skills are invoked automatically by /do.
 function getFlag(name) {
     return args.includes(`--${name}`);
 }
-switch (cmd) {
-    case "install":
-        install({ skipPrefs: getFlag("skip-prefs") });
-        break;
-    case "update":
-        update({ skipPrefs: !getFlag("include-prefs") });
-        break;
-    case "list":
-        listInstalled();
-        break;
-    case "uninstall": {
-        const name = args[1];
-        if (!name) {
-            console.error("Usage: pi-dev uninstall <skill>");
-            process.exit(1);
+function getScope() {
+    if (getFlag("global"))
+        return "global";
+    if (getFlag("local"))
+        return "local";
+    return undefined;
+}
+async function main() {
+    switch (cmd) {
+        case "install":
+            await install({
+                skipPrefs: getFlag("skip-prefs"),
+                scope: getScope(),
+                yes: getFlag("yes") || args.includes("-y"),
+            });
+            break;
+        case "update":
+            await update({ skipPrefs: !getFlag("include-prefs"), scope: getScope() });
+            break;
+        case "list":
+            listInstalled();
+            break;
+        case "uninstall": {
+            const name = args[1];
+            if (!name || name.startsWith("--")) {
+                console.error("Usage: pi-dev uninstall <skill> [--global|--local]");
+                process.exit(1);
+            }
+            uninstallSkill(name, getScope());
+            break;
         }
-        uninstallSkill(name);
-        break;
-    }
-    case "doctor":
-        doctor();
-        break;
-    case "version":
-    case "--version":
-    case "-v": {
-        const here = dirname(fileURLToPath(import.meta.url));
-        const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
-        console.log(pkg.version);
-        break;
+        case "doctor":
+            doctor();
+            break;
+        case "version":
+        case "--version":
+        case "-v": {
+            const here = dirname(fileURLToPath(import.meta.url));
+            const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+            console.log(pkg.version);
+            break;
+        }
+        case "help":
+        case "--help":
+        case "-h":
+        case undefined:
+            help();
+            break;
+        default:
+            console.error(`Unknown command: ${cmd}\n`);
+            help();
+            process.exit(1);
     }
-    case "help":
-    case "--help":
-    case "-h":
-    case undefined:
-        help();
-        break;
-    default:
-        console.error(`Unknown command: ${cmd}\n`);
-        help();
-        process.exit(1);
 }
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/install.js

@@ -1,21 +1,55 @@
 import { existsSync, mkdirSync, cpSync, copyFileSync, renameSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { join } from "node:path";
+import { createInterface } from "node:readline";
 import { SKILLS } from "./manifest.js";
-import { PI_AGENT_DIR, PI_SKILLS_DIR, PI_GLOBAL_PREFS, PKG_SKILLS_DIR, PKG_GLOBAL_PREFS_PRESET, } from "./paths.js";
-export function install(opts = {}) {
-    mkdirSync(PI_SKILLS_DIR, { recursive: true });
+import { PKG_SKILLS_DIR, PKG_GLOBAL_PREFS_PRESET, destFor, } from "./paths.js";
+function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((res) => {
+        rl.question(question, (a) => {
+            rl.close();
+            res(a);
+        });
+    });
+}
+async function resolveScope(opts) {
+    if (opts.scope)
+        return opts.scope;
+    // Non-interactive (CI, piped) → default to global silently.
+    if (opts.yes || !process.stdin.isTTY)
+        return "global";
+    const cwd = process.cwd();
+    const { skillsDir: localSkills } = destFor("local", cwd);
+    const { skillsDir: globalSkills } = destFor("global");
+    console.log("");
+    console.log("pi-dev: where should the skills live?");
+    console.log("");
+    console.log(`  [g] global  →  ${globalSkills}`);
+    console.log(`               every pi session on this machine sees them.`);
+    console.log("");
+    console.log(`  [l] local   →  ${localSkills}`);
+    console.log(`               only pi sessions started from this repo see them.`);
+    console.log(`               pi reads project-local config from .pi/ in the cwd.`);
+    console.log("");
+    const ans = (await ask("Choose [G/l] (default global): ")).trim().toLowerCase();
+    if (ans === "l" || ans === "local")
+        return "local";
+    return "global";
+}
+export async function install(opts = {}) {
+    const scope = await resolveScope(opts);
+    const { agentDir, skillsDir, prefsFile } = destFor(scope);
+    mkdirSync(skillsDir, { recursive: true });
     let copied = 0;
     for (const skill of SKILLS) {
         const src = join(PKG_SKILLS_DIR, skill.name);
-        const dst = join(PI_SKILLS_DIR, skill.name);
+        const dst = join(skillsDir, skill.name);
         if (!existsSync(src)) {
             console.warn(`  skip ${skill.name} (source not found in package)`);
             continue;
         }
         if (existsSync(dst) && !opts.force) {
-            // Replace contents but keep the directory; safer than rmSync for skills
-            // the user may have customised lightly.
             cpSync(src, dst, { recursive: true, force: true });
         }
         else {
@@ -23,63 +57,96 @@ export function install(opts = {}) {
         }
         copied++;
     }
-    console.log(`Installed ${copied} skill(s) into ${PI_SKILLS_DIR}`);
+    console.log(`Installed ${copied} skill(s) into ${skillsDir} [${scope}]`);
     if (opts.skipPrefs) {
-        console.log("Skipped global preferences (use --include-prefs on update to merge in new keys).");
+        console.log("Skipped preferences (pass --include-prefs on update to merge in new keys).");
         return;
     }
-    if (!existsSync(PI_GLOBAL_PREFS)) {
+    if (!existsSync(prefsFile)) {
         if (existsSync(PKG_GLOBAL_PREFS_PRESET)) {
-            copyFileSync(PKG_GLOBAL_PREFS_PRESET, PI_GLOBAL_PREFS);
-            console.log(`Seeded global preferences at ${PI_GLOBAL_PREFS}`);
+            copyFileSync(PKG_GLOBAL_PREFS_PRESET, prefsFile);
+            console.log(`Seeded preferences at ${prefsFile} [${scope}]`);
         }
     }
     else {
-        console.log(`Existing global preferences kept at ${PI_GLOBAL_PREFS} (use --include-prefs to merge new keys).`);
+        console.log(`Existing preferences kept at ${prefsFile} (pass --include-prefs to merge new keys).`);
+    }
+    if (scope === "local") {
+        console.log("");
+        console.log("Tip: add `.pi/sessions/` to .gitignore (sessions are local-only).");
+        console.log("     Skills under `.pi/skills/` are safe to commit.");
     }
 }
-export function update(opts = {}) {
-    // Update is install with force, but defaults to NOT overwriting global prefs.
-    install({ ...opts, force: true, skipPrefs: !opts.skipPrefs ? true : opts.skipPrefs });
+export async function update(opts = {}) {
+    // Update is install with force. If scope wasn't passed, infer it from what's
+    // already on disk: a local `.pi/skills/` in cwd wins over global.
+    let scope = opts.scope;
+    if (!scope) {
+        const local = destFor("local");
+        if (existsSync(local.skillsDir))
+            scope = "local";
+        else
+            scope = "global";
+    }
+    await install({
+        ...opts,
+        scope,
+        force: true,
+        skipPrefs: !opts.skipPrefs ? true : opts.skipPrefs,
+        yes: true,
+    });
 }
-export function uninstallSkill(name) {
-    const dst = join(PI_SKILLS_DIR, name);
+export function uninstallSkill(name, scope) {
+    const resolved = scope ?? (existsSync(destFor("local").skillsDir) ? "local" : "global");
+    const { skillsDir } = destFor(resolved);
+    const dst = join(skillsDir, name);
     if (!existsSync(dst)) {
-        console.error(`Skill not installed: ${name}`);
+        console.error(`Skill not installed [${resolved}]: ${name}`);
         process.exit(1);
     }
-    // Soft delete: rename to .removed-<ts>
     const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const moved = join(PI_SKILLS_DIR, `.removed-${stamp}-${name}`);
+    const moved = join(skillsDir, `.removed-${stamp}-${name}`);
     renameSync(dst, moved);
-    console.log(`Uninstalled ${name} (moved to ${moved}).`);
+    console.log(`Uninstalled ${name} from ${resolved} (moved to ${moved}).`);
 }
 export function listInstalled() {
-    console.log(`Skills directory: ${PI_SKILLS_DIR}\n`);
-    for (const skill of SKILLS) {
-        const path = join(PI_SKILLS_DIR, skill.name, "SKILL.md");
-        const installed = existsSync(path);
-        const tag = skill.kind === "human" ? "[user]   " : "[support]";
-        const status = installed ? "ok" : "missing";
-        console.log(`  ${tag} /${skill.name.padEnd(34)} ${status}  — ${skill.summary}`);
+    const local = destFor("local");
+    const global = destFor("global");
+    const targets = [];
+    if (existsSync(local.skillsDir))
+        targets.push({ label: "local", ...local });
+    targets.push({ label: "global", ...global });
+    for (const t of targets) {
+        console.log(`Skills directory [${t.label}]: ${t.skillsDir}`);
+        for (const skill of SKILLS) {
+            const path = join(t.skillsDir, skill.name, "SKILL.md");
+            const installed = existsSync(path);
+            const tag = skill.kind === "human" ? "[user]   " : "[support]";
+            const status = installed ? "ok     " : "missing";
+            console.log(`  ${tag} /${skill.name.padEnd(34)} ${status}  — ${skill.summary}`);
+        }
+        console.log(`Preferences: ${existsSync(t.prefsFile) ? t.prefsFile : "(missing)"}`);
+        console.log("");
     }
-    console.log(`\nGlobal preferences: ${existsSync(PI_GLOBAL_PREFS) ? PI_GLOBAL_PREFS : "(missing)"}`);
 }
 export function doctor() {
     const issues = [];
-    if (!existsSync(PI_AGENT_DIR))
-        issues.push(`~/.pi/agent missing — run: pi-dev install`);
-    if (!existsSync(PI_SKILLS_DIR))
-        issues.push(`~/.pi/agent/skills missing — run: pi-dev install`);
+    const local = destFor("local");
+    const hasLocal = existsSync(local.skillsDir);
+    const activeScope = hasLocal ? "local" : "global";
+    const { agentDir, skillsDir, prefsFile } = destFor(activeScope);
+    if (!existsSync(agentDir))
+        issues.push(`${agentDir} missing — run: pi-dev install`);
+    if (!existsSync(skillsDir))
+        issues.push(`${skillsDir} missing — run: pi-dev install`);
     for (const skill of SKILLS.filter((s) => s.kind === "human")) {
-        if (!existsSync(join(PI_SKILLS_DIR, skill.name, "SKILL.md"))) {
-            issues.push(`Human skill /${skill.name} not installed — run: pi-dev update`);
+        if (!existsSync(join(skillsDir, skill.name, "SKILL.md"))) {
+            issues.push(`Human skill /${skill.name} not installed [${activeScope}] — run: pi-dev update`);
         }
     }
-    if (!existsSync(PI_GLOBAL_PREFS)) {
-        issues.push(`Global preferences missing — run: pi-dev install (or copy presets/preferences.md manually)`);
+    if (!existsSync(prefsFile)) {
+        issues.push(`Preferences missing at ${prefsFile} — run: pi-dev install (or copy presets/preferences.md manually)`);
     }
-    // Quick external check (best-effort)
     const checkCmd = (cmd, label) => {
         try {
             execSync(`${cmd} --version`, { stdio: "ignore" });
@@ -90,6 +157,7 @@ export function doctor() {
     };
     checkCmd("git", "git");
     checkCmd("gh", "gh CLI");
+    console.log(`Active scope: ${activeScope}`);
     if (issues.length === 0) {
         console.log("All checks passed.");
         return;

package/dist/paths.js

@@ -12,3 +12,15 @@ export const PKG_ROOT = resolve(__dirname, "..");
 export const PKG_SKILLS_DIR = join(PKG_ROOT, "skills");
 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 };
+    }
+    const agentDir = join(cwd, ".pi");
+    return {
+        agentDir,
+        skillsDir: join(agentDir, "skills"),
+        prefsFile: join(agentDir, "preferences.md"),
+    };
+}

package/package.json

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