@evoclock/pi-agentic-driver 1.1.2 → 2.0.0

package/skills/sharpen-pi/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: sharpen-pi
+description: Before an approved task starts, test its expert approach, real user outcome and specification level, then retain one independent result check. Use explicitly when asked to sharpen a task.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Sharpen the work for Pi
+
+Adapted from Lauren Tan's new `sharpen` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. This is a short pre-work judgment pass, **not** a new task contract, rewritten user prompt, permission to relax owner-held safety limits or license to launch workers/effects.
+
+Before taking an approved task, ask three questions privately: How would a top practitioner approach this exact problem, including raw sources, actual methods and a check outside the proposed implementation? What outcome is the **user** really trying to obtain? Is the brief over- or underspecified for that outcome? Consult the named source or existing code only inside the granted data scope. Challenge busywork and speculative constraints that do not serve the goal, and add only clarifications that change a real decision. For a constraint owned by the repository owner, a safety rule or a product choice, **propose** a change; do not loosen it by yourself or substitute a preferred task.
+
+Retain at least one **independent, authorized outside check** of the end result, not the candidate's self-report or circular test. Name its expected observation, target and safe exit; if that check is not available, report it `blocked`/`unrun` rather than treating a plan as proof. Leave irreducible product decisions to the user, continue only reversible ordinary work that the existing grant already covers, and stop where a new owner choice is required. Fold the improved expert method and proportionate check into **the work itself** rather than narrating a framing exercise or handing back a rewritten prompt. If the user only requested a planning critique or no executable task/effect grant exists, return the smallest actionable clarification and do not implement anything.
+
+- **Positive BDD:** Given an approved task with accessible raw sources and a permitted independent result check, when Pi tests expert method, underlying user purpose and spec granularity before execution, then the same scoped task proceeds with one decision-changing improvement and a named external success observation, not a longer prompt.
+- **Refusal BDD:** Given an owner-held requirement, unclear goal, absent data/check/effect permission or only a request for critique, when sharpening would broaden or change the task, then keep the existing scope, name the pending owner choice and mark the unrun check `blocked`/`unrun`; do not rewrite the contract or execute unapproved work.
+
+Discovery of this skill is not proof that an expert method, outside result or Pi task was exercised.

package/skills/show-me-your-work-pi/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: show-me-your-work-pi
+description: Keep and audit one evidence-linked decision trail for approved multi-phase work, then present an independently checked Attention section. Use explicitly for a long reviewable run.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Show your work for Pi
+
+Adapted from Lauren Tan's `show-me-your-work`, its six-column TSV template and append-only `scripts/log.sh` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. This P47 leaf maps the full pinned run-boundary/TSV/audit method without creating a second writer or automatically executing the stock shell helper. Keep the **single** approved private record for an assignment; existing Markdown records need not be converted to TSV. No transcript access, reviewer or Git commit follows from reading a skill.
+
+## One append-only decision trail
+
+Before starting, identify the approved, version-controlled **private** evidence destination and single writer; if none exists, stop a long run rather than invent a hidden `.audit` file. The source defaults to untracked `decisions.tsv`/`.audit/<task>.tsv` and commits only for complex reviewer-needed work. Here commit only within the owner's separately approved scope; an ignored artifact is not version-controlled evidence. Keep a decision/checkpoint/pivot/failed gate row as it happens, not every tool call or a retrospective green story. Record timestamp, phase, decision, plain **why**, resolving evidence pointer and actual result (`INCONCLUSIVE`/`open` included); retain run identity and exact artifact/revision. If the owner selects TSV, use the pinned header `ts\tphase\tdecision\twhy\tevidence\tresult`, one physical line per row, neutralize tabs/newlines/CR and any cell with a leading (including leading-whitespace) spreadsheet formula prefix `=`, `+`, `-`, `@`. The stock `log.sh` writes header, UTC time and sanitizes immediate-prefix cells but is **not** bundled or invoked; do not assume it handles leading whitespace. An existing approved Markdown trail may carry the same fields without a format change.
+
+A run is one agent conversation including later turns; a replacement agent or new chat is a new run. On pickup read last entries; if another run wrote since, add a fresh `start` boundary naming the prior timestamp range and this actual run ID. Never claim concurrent Markdown/TSV appends are safe without single-writer ownership. Correct a wrong/invented row by appending a superseding entry with accurate pointer, never by rewriting history. Preserve an abandoned fork, retry or gate change that affected the result.
+
+## Audit and independent attention
+
+Before handback, name and obtain access to **this run's actual transcript and bounded range**. Audit only this run's stretches, bounded by its `start` rows, against decisions/actions, resolvable evidence and omitted pivots; do not glob unrelated Pi or Cursor chats. If transcript access is absent, audit only permitted tool/evidence results and say transcript-versus-trail audit `unrun`. Give the exact approved trail and transcript range to a fresh configured `independent-review` context **distinct from the author** via `/skill:setup-pstack-pi`, but only with model/data/route/budget grant. It checks weak evidence, skipped checks and risky scope pivots, not a new implementation. Without it, independent attention review is `blocked`, never “no flags”. A report is evidence, not approval.
+
+Hand back a short **Attention** section naming actual reviewer findings with specific row/moment pointers, saying `no flags` **only after** an actual independent review that found none, or explicitly stating review was not performed. The source's model-name reporting is replaced by the configured **role** in owner-facing copy; do not publish provider identity. Show exact completed/unrun checks and safe next step. Do not auto-file board items, launch a worker, edit skills or push the trail because the source method mentions review.
+
+- **Positive BDD:** Given an approved long task, single-writer private trail, accessible named transcript and distinct authorized reviewer, when Pi appends decisions and audits only this run's rows then reviewer spots weak proof, then the handback cites exact artifact, corrected append-only history and attributed Attention findings.
+- **Refusal BDD:** Given no evidence destination, transcript grant, reviewer identity/data route or owner Git scope, when auditing, independent review or committing would need it, then mark that phase `blocked`/`unrun`, keep existing records intact and do not invent a TSV log, transcript check, independent verdict or commit.
+
+Pi discovering this file is not an audited run, a cross-model review or a real Pi session journey.

package/skills/swarm-pi/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: swarm-pi
+description: For an approved bounded parallel investigation or comparison, split independent slices or race identical briefs, then reconcile every result into one evidence-backed report. Use explicitly for a swarm request.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Swarm for Pi
+
+Adapted from Lauren Tan's `swarm` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. This method is **not** a worker, cloud environment, capacity, containment or model-selection grant. The Cursor source's default worker provider, `auto`/parent fallback, cloud/local switch, `cloud_base_branch` and background `Task` calls are not Pi APIs. A Treehouse lease is not runtime isolation, and a worker report cannot authorize effects or certify the result.
+
+## Frame before fan-out
+
+Use the already loaded Pi session tasks for four phases — **Frame, Fan out, Aggregate, Report** — when available; otherwise keep a local checklist within an approved evidence file, not a second board. Name one done predicate, exact report/artifact, repository base/revision, data/effect route, worker budget and safe stop. Choose **partitioned independent slices**, a **race** of identical briefs, or a declared mixed shape. Before launching any race name its selection rule: `first pass`, `rank all` or `best-of`, with a real comparison check; never choose a winner post hoc. Set N and worker role/identity from the owner-approved project map through `/skill:setup-pstack-pi` and verify actual Pi worker capacity/data route; a missing or rejected role is `blocked`, not an invented default or alternate model. A model race needs each explicitly approved arm and budget, not the role map's one default.
+
+## Fan out with owned outputs
+
+Only after a Pi coordinator/worker route and isolation appropriate to the effects are approved, give each worker a **self-contained** goal, exact slice or common race brief, allowed paths, do-not-touch fence, immutable base/SHA, success and negative check, private output path and report shape. Distinct writing workers own distinct files/branches; a shared writer uses its existing trusted claim/serialization route, not hopeful instructions. For any measurement name sample count, one sample, ordering and independent oracle **in the brief**. Launch bounded independent jobs only within granted N and capacity; no automatic cloud instance, external provider, local host access or extra terminal/tab follows. Reports must state `PASS`, `ISSUES` or `BLOCKED`, cite their exact SHA and method, and list **all** proved issues for the slice. A completion receipt is not the report.
+
+## Aggregate and hand back
+
+Read each attributed terminal result and verify decisive evidence against source or the authorized real check. Discard a result missing its required SHA/method; an unsupported `PASS` is a gap. If a worker drops out, report N-1 coverage and the missing slice; **every required slice** needs real evidence before complete coverage. A new attempt after a malformed report requires an explicit permitted retry with reconciled state; never blindly resend an accepted effect. For a race use the preregistered selection rule and actual comparable outputs; do not call a lucky first response the winner without its predicate. Reconcile contradictions, include one table of statuses, issue one-liners, dropouts/unrun checks and the declared race rule. Do not paste raw private worker dumps into public copy. Owner-only merge, independent exact-artifact review and real Pi/user QA stay separate.
+
+- **Positive BDD:** Given an approved parallel task, distinct worker scopes/routes and budget, when Pi fans out self-contained briefs and checks every returned SHA, method and observable result, then one report covers all required slices or selects the race winner by its declared verified rule with gaps explicit.
+- **Refusal BDD:** Given no role/capacity/data route, overlapping writes, uncertain effect, missing worker result/SHA or unapproved retry, when fan-out or aggregation depends on it, then mark that slice `blocked`/`unrun`, do not spawn a fallback, replay an effect, invent consensus or report a partial swarm as complete.
+
+A discoverable skill or accepted dispatch receipt is not an executed swarm, verified worker result or the Pi session session.

package/skills/tasks/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: tasks
+description: Use the session task list to track work and promote owner-authorized tasks to the durable board.
+license: AGPL-3.0-only
+---
+
 # tasks — unified session task list + board promotion (v1)
 
 Owner-facing skill for the pi-agentic-driver session task list and
@@ -10,7 +16,7 @@ reimplement the documented behavior of
 [`@ladbabynpm/picc-tasks`](https://www.npmjs.com/package/@ladbabynpm/picc-tasks)
 v0.2.0 (MIT, Copyright (c) 2026 Ladbaby) as prior art: the same tool names,
 the same storage model (session JSONL snapshot entries plus a disk mirror at
-`~/.pi/tasks/{taskListId}/tasks.json`), and the same result text. No code is
+the per-profile task-list mirror), and the same result text. No code is
 copied; this is a clean AGPL-3.0-only reimplementation to the same behavior
 spec. picc-tasks is an independent project by its author, used as reference;
 it is not affiliated with, nor does it endorse, pi-agentic-driver.
@@ -125,4 +131,4 @@ mutates state, writes the board, or promotes.
 ## Out of scope in v1
 
 No Obsidian work. No automatic worker proposal store. No session-end prompt.
-No completed-task promotion. No Vogelkop writer-authority changes.
+No completed-task promotion. No external board writer-authority changes.

package/skills/tdd-pi/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: tdd-pi
+description: For an explicitly requested TDD or regression path, or a bug with an obvious cheap local test, demonstrate a focused red check before the smallest fix and green after. Use explicitly when the test seam is practical.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# TDD bug fix for Pi
+
+Adapted from Lauren Tan's unchanged `tdd` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md` and existing `../diagnosing-bugs/SKILL.md` for bug investigations. The source allows **skipping a new automated test** when the seam is impractical; it does **not** waive this project's stricter authorized red-capable reproduction requirement before a bug hypothesis/fix. No install, production access or broad harness follows from this skill.
+
+Use when the user explicitly asks for TDD, a failing/regression test, or an obvious cheap local bug test. Otherwise skip this method when the only candidate needs broad harness setup, brittle mocks, slow end-to-end infrastructure, production-only state, vague repro or large fixture churn. First identify intended behavior, observed failure, affected entry and smallest observable reproduction. Choose the narrowest existing unit/component/integration/regression seam that exercises **behavior**; do not create a new framework to clear a process checkbox. For an actual bug, if no authorized red-capable seam exists, stop the diagnosis/fix at its existing gate and report the needed permission or artifact; a proposed closest check is not observed red.
+
+When the seam is practical, write a focused test against an independent expected behavior, run it **before** production edits, and confirm it fails for the intended reason. A green test, unrelated failure, mock self-assertion or changed assertion that mirrors broken code is not red proof: correct the seam first. Make the smallest permitted cause fix that preserves adjacent contracts; rerun the same regression green and check the original scenario. Do not weaken a prior assertion without a genuinely changed accepted requirement. Keep fixtures scoped and stabilize flaky timing with a declared deterministic signal; first prove this defect, then consider sibling coverage within a separate grant.
+
+If a **new automated** failing test is impractical but an approved red-capable manual reproduction, targeted script, browser drive, snapshot or log assertion can exercise the same wrong behavior, record the actual before failure and after observation there instead. If none can run safely, mark bug repair `blocked` and offer the closest proposed check without claiming a fix. In the handback name exact pre-fix failure, post-fix run, nearby checks and every missing/unrun step; passing a fixture alone is not a real packaged app/user journey.
+
+- **Positive BDD:** Given an approved bug with an inexpensive executable behavior seam, when Pi observes a focused red result before editing, applies the smallest cause fix and reruns that check plus the original scenario, then the regression turns green for the right reason without losing negative behavior.
+- **Refusal BDD:** Given no safe red-capable seam, only brittle mocks, no edit/target grant or a test that was already green, when a fix is proposed, then hold bug diagnosis/fix `blocked`/`unrun`, report the closest check and do not invent red evidence or loosen tests to pass.
+
+Discovering a Pi TDD skill is not an executed red/green loop or the Pi session verification.

package/skills/teach-pi/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: teach-pi
+description: Teach an approved subsystem or change in plain language by combining verified how-it-works and evidence-backed why-it-is-that-way explanations. Use explicitly when someone asks to understand, not edit, a system.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Teach for Pi
+
+Adapted from Lauren Tan's unchanged `teach` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. Teaching is **read-only**. The pinned method invokes `how` for mechanics and `why` for historical reasons; in Pi, use each only if its reviewed skill actually loaded and the source/history/data route is approved. A planned `why-pi` file or temporary skill discovery is not proof the Pi session loaded it. Do not invent a motive from code shape, launch an image generator, read private chats or edit the system because teaching mentions those routes.
+
+First infer why this person asks (about to edit, reviewing, debugging, new to the area) and what they already know from the current conversation, not a quiz. Choose only the few ideas needed. Read bounded source for orientation, then use loaded `how-pi` or existing `how` to trace the entry-to-result mechanism and a loaded approved `why-pi`/`why` for cited reasons. For a broad subsystem both angles matter; for a small change one may suffice if the other does not affect the answer. Keep `why` scoped to the named question and permitted git/docs/issues, explicitly naming unsearched categories. When either skill or the required history route is unavailable, explain only what evidence permits and label that angle `blocked`/`unrun`; do not present a source-code inference as established history. If both routes run under an actual approved parallel budget, reconcile their findings against source; reports are not authority.
+
+Lead with one or two plain sentences defining the thing and its role **in this case**. Then build a single account of what it solves, how it works through the real action and why the supported design was chosen. Preserve the exact confidence/uncertainty of `why`'s evidence; never smooth a tentative reason into fact. A list of constants is reference, not a lesson. Start small and go deeper when the person asks; offer one natural next question at the end. No quiz, pacing theater, canned framing labels, lecture or walls of text. Use plain spoken wording, consistent concept names and short sentences; apply an actually loaded `unslop-pi` only if available, otherwise edit for clarity yourself.
+
+Show the relevant diff/source or small flow when it helps **within access scope**. For three or more genuinely moving parts that benefit from a picture, build the picture in a short progression (A→B, then A→B→C, then the next edge) rather than an all-at-once tangle; a simple point needs no diagram. A text or Mermaid series may suffice. Spatial drawings or generated images require a separately approved, actually available image route; if absent, use precise words or a local text sketch and label the visual step `unrun`, not a fabricated illustration. No public artifact or screenshot follows from an explanation.
+
+- **Positive BDD:** Given an approved learner question with loaded mechanics and rationale methods plus cited source/history, when Pi combines their checked findings at the learner's pace, then a short understandable explanation states what, how and why with original confidence and optional progressive illustration where useful.
+- **Refusal BDD:** Given missing `why`/`how`, unavailable history, unapproved image/data route or only source inference, when a historical motive or visual proof would depend on it, then teach the verified portion, mark the missing angle `blocked`/`unrun` and do not invent motive, image, skill invocation or system change.
+
+Skill discovery is not a taught user journey, historical proof or the Pi session-loaded skill.

package/skills/technical-writing-pi/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: technical-writing-pi
+description: Write or review an approved technical document using one Diátaxis mode, clear reader-facing sentences and unambiguous terminology. Use explicitly for a scoped guide, explanation, reference or tutorial.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Technical writing for Pi
+
+Adapted from Lauren Tan's `technical-writing` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. This skill combines **Diátaxis mode, Google developer style, STE-informed instructions and Global English syntax**; the rules serve the reader rather than a mechanical sentence limit. Writing does not grant public publication, document scope, product-copy changes or permission to reveal internal evidence. An actually loaded `unslop-pi` can polish a draft; if absent, apply plain wording directly and do not claim invocation.
+
+## Choose one document mode
+
+Ask whether the reader is learning or doing work, and whether the content guides **action or understanding**. Pick one mode for the document: **tutorial** (learning by doing; say what will be built and show an early visible result at each step), **how-to** (competent reader's task, direct steps and conditional forks), **reference** (dry, complete lookup facts mirroring actual code/options/errors), or **explanation** (one bounded why question with evidence, alternatives and clearly supported opinion). Split and link incompatible modes rather than insert reference tables into a tutorial or persuasion into a how-to. PR copy and commit messages need brevity and clarity, not a Diátaxis document mode; public copy also follows the owner message gate and omits internal identities, commands, evidence paths and development history.
+
+## Write to the reader
+
+Cut words without a job, choose short everyday words and prefer the codebase's **actual** symbol, path, flag or command over a renamed synonym. Explain a necessary pattern the first time. Vary sentence length deliberately; one thought per sentence does not mean every sentence must be clipped. Explanation may weigh trade-offs, while reference states checked facts without opinion. Use “you” and present tense where appropriate, name actors, give a condition **before** the action, put the common case before exceptions and write procedures as commands. Never call a step “easy”, “simply” or “quickly” to mask its prerequisites. Use informative sentence-case headings, one h1, no skipped levels, numbered sequences and parallel bullets with a complete lead-in. Keep code/real paths exact and UI labels distinct; indent code snippets with tabs when following this source standard. Validate every count, tree or option against the actual revision and include a safe regeneration instruction when a count must be maintained, rather than repeating an earlier inventory.
+
+For STE-informed steps, aim for one instruction per sentence, usually under about 20 words; for descriptive sentences prefer about 25 when clarity allows. Move a warning before its risky action and use articles so the target is unambiguous. Give each action one consistent name. For Global English, place “only” and “not” beside what they modify; shorten noun stacks, resolve pronouns with a real noun, keep verbs and structural words, disambiguate “and”/“or”, and favor periods over em dashes or semicolons. Avoid `a/b`, “(s)”, idioms and unexplained metaphors. Do not make a sentence worse merely to meet a style count: fix its structure or leave a clear exception. Keep examples, links and code excerpts within approved data scope. Use descriptive links rather than “click here”. Product UI strings follow the product's separate copy route.
+
+If an abstraction word obscures an action, propose the concrete replacement to the owner with a small diff; do **not** edit a shared `unslop` catalog on this skill's authority. Keep an explanation human and specific, not a checklist of bans. Review the final document at its real destination for the declared mode, factual paths, useful headings, runnable authorized steps and accidental private/public leakage. No automatic install or script execution follows from an example command in documentation.
+
+- **Positive BDD:** Given an approved audience, facts and document destination, when Pi selects one mode and checks reader-facing steps, terminology and real examples at the target revision, then the document serves its purpose without ambiguity or unfounded claims.
+- **Refusal BDD:** Given missing audience/source facts, conflicting modes, an unapproved public destination or unavailable writing skill, when a document or PR body would assert unsupported details, then mark those claims `blocked`/`unrun`, keep private material private and do not publish or invent results.
+
+A Pi-discoverable writing skill is not an authored user manual, approved public copy or live Pi documentation check.

package/skills/typescript-best-practices-pi/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: typescript-best-practices-pi
+description: Review an approved TypeScript file or change for precise domain types, parsed outside data, exhaustive variants, real tests and useful diagnostics. Use explicitly for .ts or .tsx work.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# TypeScript best practices for Pi
+
+Adapted from Lauren Tan's unchanged `typescript-best-practices` and its `references/patterns.md` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. Apply the **actual loaded** `principle-type-system-discipline-pi` first if available; its drafted directory or a source citation is not proof it loaded. The source's Cursor `paths` trigger does not automatically register this Pi skill for every `.ts` or `.tsx` file. This is a method for approved scope, not an automatic repository-wide rewrite, package install or runtime validation guarantee.
+
+**Model legal states.** Prefer literal-discriminated variants such as `{ kind: 'loading' } | { kind: 'ready'; value: T }` over a boolean plus optional-field bag. Brand distinct semantic primitives only when mixing them is a real risk, using the repo's existing readonly brand convention; parse at creation before downstream trust. Construct non-empty tuples, pairs or start-plus-duration ranges only when they remove a **proved** impossible state. Keep ordinary `T[]` if all its operations are total; strengthen to `NonEmpty<T>` only when a loose type forces `!`, a cast or a “never happens” throw. Require exhaustive variant handling through a discriminant switch and an inline `never` assignment, so a new case fails compilation; a silent default loses the signal.
+
+**Parse at the real boundary.** Outside RPC/IPC, JSON, files, config, environment and database data is `unknown`, not `any` or a cast. Look for the repository's existing runtime schema and infer its type before hand-writing a property-by-property guard; do not add a new dependency for one guard. Narrow with a discriminant, then `in`, `typeof`/`instanceof`, an honest `isX`/`hasX` guard, and only a justified `as` **after validation**. A lying guard is worse than a visible cast. Use `satisfies` for checked literals when it preserves their narrow types. Parse once at the outside entry into a named domain value; retain runtime guards until every external caller is proved to pass that entry. For forward-compatible wire formats ignore unknown fields **only when the actual protocol contract permits it**; persisted blobs need version-aware parsing and explicit failure handling. A type, Treehouse lease or compiler pass is not security containment.
+
+**Derive and verify.** When an authoritative proto, OpenAPI, GraphQL or migration type owns a shape, derive with `Pick`, `Omit`, `Parameters`, `ReturnType`, `Awaited` or `typeof` before inventing a parallel interface. Prefer object args for interchangeable positional values, but skip extra allocation on measured hot paths. Use real test primitives and disposable/leak checks when practical; mock only unavailable boundaries and verify the UI in a running approved build when the task requires user proof. Record enough structured logger context to debug by ID rather than adding shipped `console.log`. Check source examples against this repo's actual libraries before borrowing their syntax: a sample `z.infer` does **not** authorize installing a schema package. Capture a bad input/type mismatch and a good case at the permitted boundary; no compiled example is a real app proof.
+
+- **Positive BDD:** Given an approved typed change with outside input, existing schema/test seam and a finite variant model, when Pi narrows valid and invalid input at entry, derives the owning shape and compiles an exhaustive decision, then bad semantics fail type or runtime checks while the approved user path works.
+- **Refusal BDD:** Given an unknown outside caller, missing schema/library, ungranted package/app effect or unverified guard removal, when an unsafe cast or broad typed rewrite is proposed, then keep the boundary, mark the needed check `blocked`/`unrun` and do not claim compiler success proves runtime safety.
+
+This skill's discovery is not a typed migration, real browser test or Pi loading.

package/skills/unslop-pi/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: unslop-pi
+description: Edit approved prose to remove AI-sounding patterns and filler without changing facts, voice, evidence or intended audience. Use explicitly for a writing cleanup.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Unslop for Pi
+
+Adapted from Lauren Tan's `unslop` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. Preserve the source's **stable rule numbers and intentional gaps** so sibling skills can cite them. This is a language edit, not permission to alter product behavior, evidence, legal/licence text, quoted user words, code identifiers, owner-approved public copy or publication destination. Preserve meaning, necessary uncertainty, human warmth and the intended voice. A heuristic finding is not an automatic deletion.
+
+Scan the scoped text, then replace only real offenders with concrete wording:
+
+- **3, 5 content:** remove unsupported decorative “highlighting/ensuring/showcasing” clauses; name the actual source for “experts believe” or cut the claim.
+- **7–12 language:** replace vague AI vocabulary (“delve”, “pivotal”, abstract “landscape”, “tapestry”) and fancy “is” (“serves as”, “stands as”) with plain facts. Say “Y” directly instead of “not just X, but Y”. Do not force threes, cycle synonyms for one thing, or use a fake “from X to Y” range.
+- **13–19 style:** remove em dashes as punctuation rather than swapping in a hyphen or en dash; use a period or a comma. Limit colons to a real list/example. Do not bold every proper noun, write inline-header bullets that repeat their label, title-case headings, decorative emoji or curly quotes in the edited prose. A meaningful bold label followed by new information can stay.
+- **20, 22 communication:** drop canned chatbot openings/closers and praise that adds no answer. Give the actual answer without sycophancy.
+- **23–25 filler:** shorten “in order to” to “to”, “due to the fact that” to “because”; remove throat-clearing, stacked hedges and generic conclusions. Keep a real evidentiary caveat.
+- **26 jargon:** replace metaphor nouns with the actual mechanism, for example “substrate” → “base”, “wedge in” → “add”, “evacuate” → “move”, “endgame” → “last phase”, or a metaphorical “ratchet” → the actual check or tightening limit. Keep established code symbols and terms that mean a specific thing in their real domain; do not invent a new synonym.
+- **27–33 plain speech:** state a concrete action, observation or number rather than a feeling that fits any project. Split sentences the reader must reread. Prefer the named actor to passive voice when known, remove empty adverbs, use everyday words and literal phrasing, but avoid over-compressed arrows, missing articles and verbless fragments. A short sentence is not automatically clear.
+
+Read the original and edited sentence together. Check facts, scope, citations, approval language and denial conditions **byte-for-byte where their wording is binding**; do not weaken “blocked” into “maybe”, or erase a meaningful “unrun”. If the rule makes a sentence sound mechanical or changes a quote, leave the clear original and explain the exception. When a new abstract metaphor repeatedly causes confusion, **propose** its concrete replacement and a small diff to the owner; do not edit a shared `unslop` catalog automatically. For public PR copy the owner's message gate governs exact publication; a text cleanup does not approve it. If source facts or destination are unavailable, return only a bounded wording suggestion and label factual verification `unrun`.
+
+- **Positive BDD:** Given approved draft prose with checked facts and audience, when Pi applies the numbered patterns and checks the replacement against the original, then the result reads naturally with the same meaning, evidence, warmth and necessary uncertainty.
+- **Refusal BDD:** Given binding quoted text, a legal notice, unverified claims or no edit/publication grant, when a pattern would change authority or factual meaning, then keep that text, mark the check `blocked`/`unrun` and do not silently rewrite or publish it.
+
+Pi discovering this skill is not a reviewed document, approved public message or the Pi session writing session.

package/skills/why-pi/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: why-pi
+description: Investigate why a design or code path exists using cited history, decisions, incidents and available records; distinguish documented intent from inference. Use how for current runtime behavior.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Why for Pi
+
+Adapted from Lauren Tan's `why` and its `references/` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. `how` answers what code does; `why` investigates the forces behind its shape. Investigate cautiously. No default subagent identity, Task tool, MCP access, source permissions or worker route transfers from Cursor. Resolve configured `development` and `independent-review` roles via `../setup-pstack-pi/SKILL.md` when those roles are actually required. Do not assume that a Pi search tool implies access to private tickets, chat or analytics. This is read-only investigation, not authority to alter code or a decision.
+
+1. State the user's rationale question and identify the target, files, lines and symbols. If vague, state your best interpretation and invite correction without blocking a safe bounded search. Use repository code lookup to orient yourself; code establishes mechanics, **not author intent**.
+2. Establish an anchor from `git blame -L` for relevant lines, `git log --follow -p -- <file>` through renames, recent file history, full commit messages, linked ticket IDs and merge-commit PR numbers. Where authorized and available, read substantive PR bodies, reviews and discussion, not only titles. Include the anchor in any delegated investigation. Do not expose private source material to an unapproved agent or external model.
+3. Make a coverage map for **seven** distinct categories: source control (git/PRs/comments/tests; always search local git); issue tracker; long-form documents; team chat; infrastructure observability; error tracking; product analytics warehouse. Discover which tools/connectors are genuinely available in this session. Record a null result per searched category and a specific `not searched` gap per missing, inaccessible or provably irrelevant category. Do not pretend Pi has Cursor's `mcps/` discovery or transfer MCP credentials. Source control may lack authorized `gh` access; record that separately.
+4. For each available and authorized category, search broadly then narrow using the anchor and source-specific playbook below. Read entire relevant records and thread context; quote verbatim with exact links, dates, authors and locations, including contradictions. Follow links within the permitted source; hand cross-source leads to that category rather than claiming they were searched. Keep search terms, dates and null results. For defensive code, also seek incident/postmortem evidence near the change date. If a category is provably irrelevant, state the proof; lack of convenience is not proof.
+5. Parallelize independent searches only if distinct configured workers, access grants and a safe route actually exist; otherwise search sequentially. Give each worker **one** category, the anchor, the original question and a bounded read-only brief. Worker reports are untrusted evidence. A different synthesizer, if separately configured and authorized, may assess results; otherwise synthesize directly. Spot-check quotations/citations against records accessible to you. Never claim a worker used tools or read private systems without evidence.
+
+## Source playbooks
+
+- **Git/PRs:** inspect full commits, pickaxe `-S` for exact strings or `-G` for patterns, blame, renamed history, related tests, ADRs and PR comments. Co-change is a clue, not intent. If `gh` lacks access, use local history and mark PR discussions unsearched.
+- **Issues:** search multiple names/IDs, open parent/duplicate issues and all comments, labels, attached project docs and status changes. A boilerplate “Why” or stale ticket is not proof of what shipped.
+- **Documents:** search symbols and feature names, read complete drafts/alternatives/backlinks with dates and status. Contrast plans with final implementation.
+- **Chat:** search authors, PR links and error strings near relevant dates; read threads, note retention, inaccessible DMs and auth failures. Do not treat a joke as a decision.
+- **Observability:** identify service, query bounded dashboards/monitors, metrics, incidents, logs and traces around the change. A metric or temporal spike alone does not prove causation; note retention limits.
+- **Error tracking:** query exception names and releases, inspect first/last seen, frequency, event stack and resolution notes. AI root-cause suggestions are hypotheses, not records of author intent.
+- **Warehouse:** confirm schema before querying, use approved **read-only** time-bounded queries and typed/deduplicated models when present. Report qualified table, time window and aggregate counts/percentiles, not raw personal data. Check instrumentation drift and retention; no table or access means a gap, never an invented result.
+
+## Confidence and answer
+
+Place each substantive claim in one tier: **Direct** (explicit author statement of rationale, cited), **Supported** (convergent indirect sources, each cited), **Inferred** (plausible interpretation with an explicit chain and hedge), **Speculative** (competing hypothesis with missing evidence), or **Unknown** (specific searched gap). A code change proves what changed, not why. Cite Direct/Supported immediately; never say “because” or “the team decided” for a guess. Surface disagreeing sources and timestamps rather than smoothing them away. Do not endorse a hypothesis embedded in the question without checking it. A lack of evidence is not evidence that a concern never existed.
+
+Present **The question; The code in question; What we found; What we can reasonably infer; Competing hypotheses; What we don't know; Sources consulted; Confidence summary**. Omit only empty inference/hypothesis sections. Sources consulted names **all seven categories** with concrete searches/results or reasons not searched. If the user intends a change, add **Preserve / Change / Avoid / Risk** constraints, with evidence and unverified gaps. Do not equate a plan, text review or git history with runtime verification.
+
+- **Positive BDD:** Given an approved rationale question and accessible history plus selected record categories, when Pi anchors the code, searches available categories, checks citations and separates confidence tiers, then the reader gets cited direct reasons, qualified inference, contradictions and an explicit seven-category coverage map.
+- **Refusal BDD:** Given inaccessible private records, an unconfigured worker or only code mechanics, when the rationale would require undocumented intent, then search only authorized sources, label missing categories and unknown motives, and do not manufacture a decision, run a credentialed connector or present an unverified guess as fact.
+
+Pi discovering this skill is not MCP access, historical confirmation, a live Pi session or permission to publish private rationale.