pi-dev 0.1.8 → 0.2.1

package/dist/cli.js

@@ -9,17 +9,20 @@ function help() {
     console.log(`pi-dev — autonomous engineering skill framework for the pi runtime
 
 Usage:
-  pi-dev install [scope] [--skip-prefs] [-y]
+  pi-dev install [scope] [--skip-prefs] [--include-maintainer] [-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.
+      Pass --include-maintainer to also install maintainer-only skills
+      (only useful if you are developing pi-dev itself).
 
-  pi-dev update [--include-prefs] [--global|--local]
+  pi-dev update [--include-prefs] [--include-maintainer] [--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.
+      pass --include-prefs to re-seed. Maintainer skills already on disk are
+      preserved automatically; pass --include-maintainer to add them on update.
 
   pi-dev list                 Show installed skills under both scopes (if present).
   pi-dev uninstall <skill> [--global|--local]
@@ -32,7 +35,6 @@ 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
-  /improve-skill-flow     — audit pi sessions, propose evidence-based skill edits
 
 All other skills are invoked automatically by /do.
 `);
@@ -54,10 +56,15 @@ async function main() {
                 skipPrefs: getFlag("skip-prefs"),
                 scope: getScope(),
                 yes: getFlag("yes") || args.includes("-y"),
+                includeMaintainer: getFlag("include-maintainer"),
             });
             break;
         case "update":
-            await update({ skipPrefs: !getFlag("include-prefs"), scope: getScope() });
+            await update({
+                skipPrefs: !getFlag("include-prefs"),
+                scope: getScope(),
+                includeMaintainer: getFlag("include-maintainer"),
+            });
             break;
         case "list":
             listInstalled();

package/dist/install.js

@@ -2,7 +2,7 @@ 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 { SKILLS, CONSUMER_SKILLS } from "./manifest.js";
 import { PKG_SKILLS_DIR, PKG_GLOBAL_PREFS_PRESET, destFor, } from "./paths.js";
 function ask(question) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -41,8 +41,9 @@ export async function install(opts = {}) {
     const scope = await resolveScope(opts);
     const { agentDir, skillsDir, prefsFile } = destFor(scope);
     mkdirSync(skillsDir, { recursive: true });
+    const skillsToInstall = opts.includeMaintainer ? SKILLS : CONSUMER_SKILLS;
     let copied = 0;
-    for (const skill of SKILLS) {
+    for (const skill of skillsToInstall) {
         const src = join(PKG_SKILLS_DIR, skill.name);
         const dst = join(skillsDir, skill.name);
         if (!existsSync(src)) {
@@ -88,12 +89,16 @@ export async function update(opts = {}) {
         else
             scope = "global";
     }
+    // On update, preserve the maintainer set if maintainer skills are already on
+    // disk — no need to make the user re-pass the flag every time.
+    const maintainerAlreadyInstalled = existsSync(join(destFor(scope).skillsDir, "improve-skill-flow", "SKILL.md"));
     await install({
         ...opts,
         scope,
         force: true,
         skipPrefs: !opts.skipPrefs ? true : opts.skipPrefs,
         yes: true,
+        includeMaintainer: opts.includeMaintainer || maintainerAlreadyInstalled,
     });
 }
 export function uninstallSkill(name, scope) {
@@ -121,7 +126,11 @@ export function listInstalled() {
         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 tag = skill.kind === "human"
+                ? "[user]      "
+                : skill.kind === "maintainer"
+                    ? "[maintainer]"
+                    : "[support]   ";
             const status = installed ? "ok     " : "missing";
             console.log(`  ${tag} /${skill.name.padEnd(34)} ${status}  — ${skill.summary}`);
         }

package/dist/manifest.js

@@ -3,6 +3,8 @@
  *
  * `human` skills are what the user calls directly: /do, /taste, /where.
  * `support` skills are auto-invoked by /do or /migrate.
+ * `maintainer` skills are for pi-dev framework maintenance only; they are
+ * NOT installed for consumers by default (pass --include-maintainer to opt in).
  *
  * The skill names match the directory names under `skills/`.
  */
@@ -11,7 +13,8 @@ export const SKILLS = [
     { name: "do", kind: "human", summary: "Do the engineering work end-to-end." },
     { name: "taste", kind: "human", summary: "View / update / onboard preferences." },
     { name: "where", kind: "human", summary: "Recall prior pi sessions for this cwd." },
-    { name: "improve-skill-flow", kind: "human", summary: "Audit pi session telemetry and propose evidence-based SKILL.md edits." },
+    // Maintainer-only — pi-dev framework itself, not shipped to consumers.
+    { name: "improve-skill-flow", kind: "maintainer", summary: "Maintainer-only. Audit pi telemetry, propose SKILL.md edits, release." },
     // Auto-invoked support skills
     { name: "migrate", kind: "support", summary: "Strict migration gate before /do can run." },
     { name: "setup", kind: "support", summary: "Scaffold issue-tracker / triage / domain docs." },
@@ -27,3 +30,5 @@ export const SKILLS = [
 ];
 export const HUMAN_SKILLS = SKILLS.filter((s) => s.kind === "human");
 export const SUPPORT_SKILLS = SKILLS.filter((s) => s.kind === "support");
+export const MAINTAINER_SKILLS = SKILLS.filter((s) => s.kind === "maintainer");
+export const CONSUMER_SKILLS = SKILLS.filter((s) => s.kind !== "maintainer");

package/package.json

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

@@ -1,48 +1,71 @@
 ---
 name: improve-skill-flow
-description: Analyse real pi-runtime session telemetry from a consumer repo to find where the engineering skills (especially /do's chain) drift from their stated contract, then propose evidence-anchored edits to the SKILL.md files. Use when the user 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 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).
 ---
 
 # /improve-skill-flow — Meta-skill for evidence-based skill improvement
 
-The pi-dev skills are pure markdown. They get better by reading what real sessions did, comparing that to what the SKILL.md said *should* happen, and editing the gap closed. This skill is the canonical loop for that.
+**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 skills are pure markdown. They get better when the maintainer reads what real sessions did across consumer repos, compares that to what the SKILL.md said *should* happen, and edits the gap closed. This skill is the canonical loop for that.
 
 The point: **never edit a SKILL.md from gut feeling.** Edit because session N showed phase P violated predicate Q on M occasions, and here is the line that would have prevented it.
 
+## Pre-flight (hard gate)
+
+Refuse to run unless cwd is the pi-dev repo. Releases happen from here; nothing else makes sense.
+
+```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
+[ "$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"
+  exit 1
+fi
+```
+
+If the gate fails, stop. Do not proceed in a consumer repo.
+
 ## When to run
 
-- A consumer repo has accumulated at least one real day of pi sessions (≈ 3+ `.jsonl` files).
+- 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 the consumer repo — that is `improve-codebase-architecture`.
+- 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.
 
 ## Inputs
 
-- **Target repo path** (or its sessions directory). Defaults: the user names a repo; you resolve it.
+- **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.
-- **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.
+- **Fix scope** per finding — `framework` or `consumer-prefs`. Defaults set in Step 5.5; maintainer can flip individual rows before applying.
 
-## Install scopes
+## Fix 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:
+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:
 
 | 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 |
+| **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 |
 
 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.
+- 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.
+- 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.
 
 ## Session-data location & format
 
@@ -82,13 +105,13 @@ Timestamps on `message` records are ISO strings; some other record types use int
 
 ### 1 — Scope and load
 
-Ask the user (one round, only if not already specified):
+Ask the maintainer (one round, only if not already specified):
 
-- target repo (or "all repos with sessions")
+- 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 user can see the input scale.
+Resolve the sessions directory. List the `.jsonl` files with size + line count so the maintainer can see the input scale.
 
 ### 2 — Build the raw signal table
 
@@ -116,7 +139,7 @@ Use a deterministic Python or shell script you write once and check into `/tmp`
 
 ### 3 — Cross-reference with repo state
 
-For the same date range, pull:
+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`.
@@ -126,7 +149,7 @@ For the same date range, pull:
 Cross-reference each signal against:
 
 - The skill's **terminal predicate** in `do/SKILL.md` → "Phase contracts".
-- The repo's **`docs/agents/preferences.md`** taboos and `auto-*` settings.
+- The consumer repo's **`docs/agents/preferences.md`** taboos and `auto-*` settings.
 - The hard rules in the skill being audited.
 
 ### 4 — Score the gaps
@@ -157,31 +180,17 @@ 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.
 
-### 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.
+### 5.5 — Decide fix scope per finding (auto + maintainer-overridable)
 
-**Step A — detect operator context.** Run once at the start of this step:
+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.
 
-```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:
+Default to `framework` 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:
+Default to `consumer-prefs` 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.
@@ -190,28 +199,28 @@ Default to `project` 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       | 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      |       |
+| # | 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      |       |
 ```
 
-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.
+Ask once: "OK to proceed with these scopes? Reply with row numbers to flip, or `go`." Apply the flips and move on.
 
 ### 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:
 
-**Global findings (target: pi-dev SKILL.md):**
+**Framework 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.
 
-**Project findings (target: consumer's `docs/agents/preferences.md`):**
+**Consumer-prefs findings (target: that repo's `docs/agents/preferences.md`):**
 
 - Pick the *narrowest* existing section that fits before adding a new one. Mapping:
 
@@ -228,31 +237,25 @@ For each 🔴 / 🟡 finding, draft the smallest possible edit that, **if it had
 - 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).
+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).
 
 ### 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`:
+**7a. Framework branch** — only if any finding was approved as `framework`:
 
-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.
+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' — Global findings when `operator_context=consumer`:** you cannot release. Instead:
+**7b. Consumer-prefs branch** — only if any finding was approved as `consumer-prefs`:
 
-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.
+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 the repo's normal workflow. No release-please involvement — preferences are not packaged.
+4. Push per that repo's normal workflow. No release-please involvement — preferences are not packaged.
 
 **Verification (both branches).** After the next pi session in the affected repo:
 
@@ -265,9 +268,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 (`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.
+2. Each finding has an approved scope (`framework` / `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.
 
 The summary's **last line** must be one of:
 
@@ -276,17 +279,14 @@ 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.
+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, issues, or preferences. It only edits **pi-dev's own `skills/`**.
+- 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
@@ -299,4 +299,4 @@ audit complete — upstream issue <#N> filed, project commit <sha>, hotfix mirro
 
 ## 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.
+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.

package/skills/where/SKILL.md

@@ -1,11 +1,17 @@
 ---
 name: where
-description: Quickly absorb relevant prior pi sessions for the current cwd so multi-session work continues without rediscovery. Use when the user says "지난주에 뭐했지", "where were we", "이어서 가자", "다시 시작", or when /do detects continuation intent.
+description: Answer "where are we?" for this cwd — what stage the work is at, what just happened, and what comes next — by reading prior pi sessions, git, and the issue tracker. Use when the user says "지금 어디야", "우리 어디까지 했지", "지난주에 뭐했지", "where were we", "이어서 가자", "다시 시작", "다음 로드맵", or when /do detects continuation intent.
 ---
 
-# /where — Recall pi History
+# /where — Where Are We?
 
-This is a pi-specific skill. pi stores every session as a JSONL stream under `~/.pi/agent/sessions/<encoded-cwd>/<ts>_<sessionId>.jsonl`. This skill gives the agent a disciplined way to find and ingest only the slice of history that matters, without bloating context.
+The essence of this skill: answer three questions, in this order, about the current cwd.
+
+1. **어디까지 왔나 (stage)** — what phase / slice / release the work is in *right now*.
+2. **최근 뭐했나 (recent)** — what the last 1–3 sessions actually did, condensed.
+3. **다음 뭐 할까 (next)** — the most plausible next action, with the file / issue / command that picks it up.
+
+pi stores every session as a JSONL stream under `~/.pi/agent/sessions/<encoded-cwd>/<ts>_<sessionId>.jsonl`. That stream plus `git log` plus the issue tracker are the three signals this skill fuses to answer the three questions above. Without that fusion, "recall" is just history dumping; with it, the user can resume in one turn.
 
 ## When to use
 
@@ -19,18 +25,35 @@ Do not use:
 - To bypass the migration gate (it doesn't)
 - As a replacement for ADRs, CONTEXT.md, or issues (those are the durable channels)
 
+## Default action (zero-message invocation)
+
+When `/where` is invoked with **no accompanying user text** (the SKILL block is the only thing in the user turn), the invocation itself is the request: *"지금 어디야, 최근 뭐했고, 다음은 뭐야?"*
+
+Default behaviour, executed immediately and in the same turn:
+
+1. Run the full Process below with the **default relevance window** (last 3 sessions by mtime).
+2. Render the position card (the three sections: stage / recent / next).
+3. End with the next-action proposal as a question the user can confirm or correct.
+
+Do **not** print preamble like "What would you like me to recall?" or "Please specify a date range." The user already chose the skill; the only legal opening move is to start producing the card. Ask for narrowing only if Step 1 finds zero session files **and** `git log` shows no recent commits.
+
 ## Process
 
+Execute these steps as your **first action** after the skill loads. Do not narrate the plan, do not ask whether to proceed — run Step 1 immediately.
+
 ### 1. Resolve session directory
 
-```
-cwd = $(pwd)
-encoded = cwd with every "/" replaced by "-", wrapped in double dashes:
-   /Users/jason/pi/pi-mono  →  --Users-jason-pi-pi-mono--
-sessions_dir = ~/.pi/agent/sessions/$encoded
+Run this bash, do not just describe it:
+
+```bash
+cwd="$(pwd)"
+encoded="--$(echo "$cwd" | sed 's|^/||; s|/|-|g')--"
+sessions_dir="$HOME/.pi/agent/sessions/$encoded"
+[ -d "$sessions_dir" ] || { echo "no prior pi sessions for this cwd: $cwd"; exit 0; }
+ls -t "$sessions_dir"/*.jsonl 2>/dev/null | head -3
 ```
 
-If `sessions_dir` does not exist, exit cleanly: "no prior pi sessions for this cwd".
+If the directory does not exist, print exactly `no prior pi sessions for this cwd` and stop — nothing else to do.
 
 ### 2. Pick relevance window
 
@@ -44,64 +67,116 @@ ls -t ~/.pi/agent/sessions/$encoded/*.jsonl | head -3
 
 For each candidate file, read just the **first 3 lines** to get session metadata (id, model, cwd, timestamp). Skip files older than the window.
 
-### 4. Targeted extraction
+### 4. Targeted extraction (per session) — with a hard context budget
+
+A session jsonl can be hundreds of KB and a single tool result can be 10–20 KB. Never load full message bodies into context. Pull only what answers the three questions, truncate every excerpt, and enforce a byte budget.
+
+**Budget (non-negotiable):**
+
+- **≤ 8 KB total** extracted text per session into context.
+- **≤ 3 sessions** by default → worst case ≈ 24 KB.
+- Per user message: first 200 chars.
+- Per assistant text block: first 400 chars (final summaries / decisions only — see filter).
+- **Skip `toolResult` blocks entirely.** They are the biggest context killers and they rarely add signal that the surrounding text doesn't already convey.
+- **Skip `thinking` blocks entirely.**
+
+**What to pull from each in-window jsonl:**
+
+- `message` where `message.role == "user"` — keep only `.message.content[].text` truncated to 200 chars, drop anything else.
+- `message` where `message.role == "assistant"` — keep `.message.content[].text` blocks **only if** they contain one of: a heading, a final summary marker, a commit SHA-like 7-hex, an `https://` URL, or a terminator literal (`chain complete`, `audit complete`, `Final summary`, `## Summary`, `flow complete`). Truncate to 400 chars.
+- pi tool blocks of `name in ("edit", "write")` — keep just the target `path`, drop diffs.
+- pi tool blocks of lower-case `name == "bash"` — keep only those whose `input.command` matches `git commit|git push|gh issue|gh pr|gh release|npm publish`. Keep the command line only, drop output.
+
+**Implementation hint (jq, pi format — messages are nested under `.message`; toolCall/toolResult blocks live inside `.message.content[]`). Note the explicit role gate — do NOT remove it; pi emits `toolResult` records with their own `message.role` and they will leak in otherwise:**
+
+```bash
+jq -c '
+  select(.type == "message" and (.message.role == "user" or .message.role == "assistant")) |
+  . as $m |
+  {
+    ts: .timestamp,
+    role: .message.role,
+    text: (
+      (.message.content // [])
+      | map(select(.type == "text") | .text)
+      | join(" ")
+      | if $m.message.role == "user" then .[0:200] else .[0:300] end
+    ),
+    paths: (
+      (.message.content // [])
+      | map(select(.type == "toolCall" and (.name == "edit" or .name == "write")) | .arguments.path // .arguments.file_path // empty)
+    ),
+    cmds: (
+      (.message.content // [])
+      | map(
+          select(.type == "toolCall" and .name == "bash")
+          | .arguments.command
+          | select(test("git commit|git push|gh issue|gh pr|gh release|npm publish"))
+        )
+    )
+  }
+  | if .role == "assistant" then
+      select(.text | test("chain complete|audit complete|Final summary|## Summary|flow complete|^## |https://|[0-9a-f]{7,}"))
+    else . end
+  | select(.text != "" or (.paths | length) > 0 or (.cmds | length) > 0)
+' <file> | head -25
+```
+
+This drops `toolResult` and `thinking` via the explicit role gate, filters assistant text to genuine signals only, truncates per-role, and caps records per session at 25. Measured on a real 653 KB session: output ≈ 6 KB, well inside the 8 KB budget. If `jq` is unavailable, fall back to `grep -E` on raw text and live with the lower precision — still respect the 8 KB-per-session budget.
 
-Pull only these event kinds from each in-window jsonl:
+**If budget exceeded after filtering:** keep the first user message, the last 2 qualifying assistant text blocks, all matching `bash` commands, all edit/write paths. Drop intermediate text blocks. Never echo a `toolResult`.
 
-- `message` where `role=user` (intent)
-- `message` where `role=assistant` AND content includes one of: a heading, a final summary block, a list of changed files, a commit SHA, an issue URL
-- Tool calls of types: `Edit`, `Write`, `Bash` (filter by command keyword: `git commit|push|gh issue|gh pr`)
-- Any explicit handoff strings (`flow complete`, `Final summary`, `[flow] complete`)
+### 4b. Cross-reference live state (cheap, bounded)
 
-Implementation hint (jq):
+The session log alone says "what was discussed". To answer **stage** and **next** you also need what actually landed. Each probe below caps its own output — do not remove the caps:
 
 ```bash
-jq -c 'select(
-  (.type == "message" and .role == "user") or
-  (.type == "tool_use" and (.name == "Edit" or .name == "Write")) or
-  (.type == "tool_use" and .name == "Bash" and (.input.command | test("git commit|git push|gh issue|gh pr"))) or
-  (.type == "message" and .role == "assistant" and (.content | tostring | test("Final summary|flow complete|## Summary")))
-)' <file>
+git log --since="3 days ago" --pretty=format:"%h %ad %s" --date=short | head -10
+git status -sb | head -20
+# if GitHub is the tracker:
+gh pr   list --state open --limit 5 --json number,title,url 2>/dev/null
+gh issue list --state open --limit 5 --json number,title,url 2>/dev/null
 ```
 
-If `jq` is unavailable or the file format does not match, fall back to `grep`-based filters on the raw file. Keep extraction under 200 lines per session.
+Reconcile: a session that ended with a commit + merged PR → stage = shipped; a session that ended with `git status` dirty or an open PR → stage = in flight; a session whose last assistant turn proposed a follow-up command → that command *is* the next action. Each probe must be one command; do not page through history or fetch issue bodies.
 
-### 5. Synthesise a recall card
+### 5. Synthesise a position card
 
-Output exactly this shape, no more:
+Output exactly this three-section shape, no more. Each section answers one of the three questions.
 
 ```markdown
-## Recall: <cwd> — last <N> sessions
+## Where we are — <cwd>
 
-### <YYYY-MM-DD HH:MM> — session <short-id>
-- **Intent**: <one line drawn from the first user message>
-- **Touched**: <comma-separated file paths from Edit/Write tools>
-- **Side effects**: <commit SHAs / issue URLs / PR URLs>
-- **State**: <complete | incomplete: <reason>>
+### Stage (어디까지 왔나)
+<2–4 lines: current branch, last shipped version / merged PR, any open Release PR, any in-flight slice. One sentence per fact, no narration.>
 
-### <YYYY-MM-DD HH:MM> — session <short-id>
-...
+### Recent (최근 뭐했나 — last <N> sessions)
 
-## Continuation hypothesis
+- **<YYYY-MM-DD HH:MM> — <short-id>**: <intent in one line> → <files touched, condensed> → <side effects: commit SHA / PR / issue URL> — <complete | incomplete: <reason>>
+- **<YYYY-MM-DD HH:MM> — <short-id>**: …
 
-<one paragraph: what was likely left undone, which files/issues to look at first>
+### Next (다음 뭐 할까)
+<one paragraph: the single most plausible next action, named with the exact file / issue # / command that picks it up. If multiple candidates, rank them and pick #1; list #2–3 in one line.>
 ```
 
-Stop here. Do not start work. The hypothesis is the bridge to `/do`.
+Stop here. Do not start work. The Next section is the bridge to `/do` — it states an action, not a menu.
 
 ### 6. Hand off
 
-If the user confirms the hypothesis, invoke `/do` with the resolved intent + scope. If the hypothesis is wrong, ask one clarifying question and try once more.
+End with one short question: "이걸로 갈까?" (or English equivalent). If the user confirms the Next action, invoke `/do` with the resolved intent + scope. If the user picks a different candidate or corrects the framing, run Step 1 again with the narrower window and try once more.
 
 ## Privacy / safety
 
 - Sessions can contain secrets that were pasted in. Do not echo full message bodies in the recall card; extract only headings, file paths, URLs, SHAs.
 - Never write the recall card to a file in the repo. It lives in conversation context only.
 
-## Performance
+## Performance & context budget
 
-- Target: < 2 seconds wallclock for the cheap pass + targeted extraction across 3 sessions, even if individual jsonl files are multi-MB.
-- If a single jsonl is > 5 MB, sample: head -2000 + tail -2000 lines, plus any line containing `git commit`/`gh issue`.
+- **Wallclock target:** < 2 seconds for the cheap pass + targeted extraction across 3 sessions.
+- **Context budget:** ≤ 8 KB extracted per session, ≤ 24 KB total before rendering the card. This is the limit, not a goal.
+- **Always strip toolResult and thinking blocks.** They cause context bloat without changing the answer to the three questions.
+- If a single jsonl is > 5 MB, sample: `head -2000` + `tail -2000` lines (still feed them through the Step 4 jq filter — do not raw-cat).
+- If after filtering a session still exceeds 8 KB, keep first user message + last 2 qualifying assistant blocks + all matching bash commands + all edit/write paths; drop the rest.
 
 ## Limits