Harden portable pstack runtime neutrality

.github/workflows/portable-audit.yml

@@ -0,0 +1,37 @@
+name: Portable audit
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Compile maintenance scripts
+        run: python3 -m compileall -q scripts
+
+      - name: Check pack structure and mirrors
+        run: python3 scripts/audit_portability.py
+
+      - name: Reject new portability regressions
+        if: github.event_name == 'pull_request'
+        run: >-
+          python3 scripts/audit_portability.py
+          --strict
+          --changed-from "${{ github.event.pull_request.base.sha }}"

CONTRIBUTING.md

@@ -2,30 +2,74 @@
 
 ## Goals
 
-- Keep playbook / principle **intent** aligned with upstream pstack.
-- Keep vendor tool names out of skill bodies; put them only in `skills/pstack/references/adapters/`.
-- Every workflow must remain correct under the `generic` adapter (no multi-agent).
+- Keep playbook and principle **intent** aligned with upstream pstack.
+- Keep vendor tool names and concrete vendor model slugs out of portable skill bodies. Put runtime mechanics only in `skills/pstack/references/adapters/`.
+- Every workflow must remain correct under the `generic` adapter when multi-agent tools are unavailable.
+- Preserve real parallel fan-out on hosts that expose agent-spawn tools. Portability must not collapse the pack to the lowest common denominator.
 
-## Layout
+## Layout and sources of truth
 
-- Installable skills live under `skills/<name>/SKILL.md` (skills.sh compatible).
-- Shared runtime: `skills/pstack/references/{capability-contract.md,adapters/,agents/}`.
-- Playbooks: edit `skills/poteto-mode/playbooks/`, then `rsync` to `skills/pstack/playbooks/`.
+- Installable skills live under `skills/<name>/SKILL.md` and follow the Agent Skills layout used by skills.sh.
+- Shared runtime contracts live under `skills/pstack/references/{capability-contract.md,adapters/,agents/}`.
+- `skills/poteto-mode/playbooks/` is the canonical playbook directory. Mirror it to `skills/pstack/playbooks/` after edits.
+- `skills/pstack/references/adapters/` is the canonical adapter directory. Mirror it to `skills/poteto-mode/references/adapters/` after edits.
+- `skills/pstack/references/capability-contract.md` is canonical. Keep the copy under `skills/poteto-mode/references/` byte-identical.
+- Agent rubrics and `principles-summary.md` exist only under `skills/pstack/references/`; they are not mirrored into `poteto-mode`.
+
+Do not edit both sides of a mirror independently. The portable audit rejects drift.
 
 ## Re-port helpers
 
 After pulling newer upstream Cursor pstack sources:
 
 ```bash
-# copy upstream skills, then:
+# Copy upstream skills, then run the mechanical passes.
 python3 scripts/port_to_portable.py
 python3 scripts/port_pass2.py
-rsync -a skills/poteto-mode/playbooks/ skills/pstack/playbooks/
+
+# Refresh mirrors from their canonical directories.
+rsync -a --delete skills/poteto-mode/playbooks/ skills/pstack/playbooks/
+rsync -a --delete skills/pstack/references/adapters/ skills/poteto-mode/references/adapters/
+cp skills/pstack/references/capability-contract.md \
+  skills/poteto-mode/references/capability-contract.md
+```
+
+Adapters, `setup-pstack`, and portable entry skills are hand-maintained. Do not blindly overwrite them from upstream.
+
+## Required audit
+
+Run this before every pull request:
+
+```bash
+python3 -m compileall -q scripts
+python3 scripts/audit_portability.py
+python3 scripts/audit_portability.py --strict --changed-from origin/main
 ```
 
-Review the diff. Adapters and `setup-pstack` are hand-maintained — do not blindly overwrite them.
+The baseline audit checks:
+
+- skill frontmatter and unique skill names;
+- the complete playbook and adapter inventories;
+- byte-identical playbook, adapter, and capability-contract mirrors;
+- Cursor-only frontmatter keys;
+- portability smells such as concrete Cursor model slugs, `subagent_type`, `AskQuestion`, Cursor transcript paths, and ambiguous mechanical-rewrite wording.
+
+The non-strict repository-wide scan reports existing portability debt as warnings. The strict changed-file scan prevents a pull request from adding or preserving those patterns in files it touches.
+
+## Semantic review after mechanical porting
+
+Regex passes are only the first step. Review every changed skill for meaning:
+
+1. Replace vendor calls with the narrowest capability verb. Read-only investigation uses `explore`; code changes use `implement`; independent criticism uses `review`.
+2. Replace concrete model names with `model_role` and let the active adapter or override resolve a real model.
+3. Keep product decisions in `ask_user`; obtain observable facts through exploration or verification.
+4. Keep write scopes disjoint before using `parallel`.
+5. State the fallback when the host cannot spawn helpers or drive the real runtime surface.
+6. Remove claims that a mode, transcript path, MCP discovery mechanism, or background task API exists on every host.
+
+A mechanically valid sentence can still be semantically wrong. Phrases such as “`explore` / `implement` helper” are a sign that the port has not chosen the actual capability.
 
 ## skills.sh
 
-- `description` frontmatter is the trigger surface.
-- Prefer installing the whole pack so `pstack` adapters sit beside leaf skills.
+- The `description` frontmatter field is the trigger surface and must stay quoted for reliable parsing.
+- Prefer installing the whole pack so the `pstack` entry skill, adapters, playbooks, and leaf skills remain available together.

README.md

@@ -1,52 +1,67 @@
 # pstack (portable)
 
-Full portable [Agent Skills](https://agentskills.io) pack adapted from [Cursor pstack](https://github.com/cursor/plugins/tree/main/pstack) by Lauren Tan (poteto).
+A portable [Agent Skills](https://agentskills.io) distribution of [Cursor pstack](https://github.com/cursor/plugins/tree/main/pstack) by Lauren Tan (poteto).
 
-Same engineering system — principles, playbooks, how/why/architect/arena/swarm/interrogate, verification, unslop — without hard-coding one vendor runtime. Thin adapters map capabilities to Claude Code, Droid, OpenCode, Codex, and others; parallel subagents are the default on modern hosts.
+It preserves the same engineering system—principles, playbooks, `how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, verification, and prose cleanup—without hard-coding one vendor runtime. Thin adapters map capability verbs to Claude Code, Codex, Droid, OpenCode, Cursor, and unknown Agent Skills hosts. Modern hosts keep real parallel subagents; single-agent runtimes degrade explicitly and safely.
 
 ## Install
 
-See **[INSTALL.md](./INSTALL.md)** for global install and optional per-agent wiring. Keep Cursor on the official pstack plugin.
+Use this portable pack on Agent Skills-compatible coding agents other than Cursor. Cursor users should keep the official pstack plugin.
 
 ```bash
 npx skills add https://skills.sh/p/3EVEFJjSrRBr1mI4 -g -s '*' -y
 ```
 
-After `-g`, skills land in each agent’s global skills dir (e.g. `~/.claude/skills/`, `~/.agents/skills/`). Do not symlink from the git checkout unless you are developing this repo.## What’s included
+See [INSTALL.md](./INSTALL.md) for per-agent selection, model override paths, migration notes, and smoke tests. After global installation, skills usually land under an agent-specific directory such as `~/.claude/skills/`, `~/.codex/skills/`, or the shared `~/.agents/skills/` tree.
 
+## What is included
 
-| Area          | Skills / assets                                                                                                                                                                                                                                                               |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Entry         | `pstack`, `poteto-mode`                                                                                                                                                                                                                                                       |
-| Workflow      | `how`, `why`, `recall`, `blast-radius`, `architect`, `arena`, `swarm`, `interrogate`, `figure-it-out`, `teach`, `reflect`, `automate-me`, `setup-pstack`, `show-me-your-work`, `create-verification-skill`, `maintain-verification-skill`, `tdd`, `typescript-best-practices` |
-| Quality       | `unslop`, `no-comments`, `technical-writing`, `bro`                                                                                                                                                                                                                           |
-| Principles    | all 21 `principle-*` leaf skills                                                                                                                                                                                                                                              |
-| Playbooks     | 23 under `skills/pstack/playbooks` and `skills/poteto-mode/playbooks`                                                                                                                                                                                                         |
-| Runtime       | `capability-contract.md` + adapters: `generic`, `claude-code`, `droid`, `opencode`, `codex`, `cursor`                                                                                                                                                                         |
-| Agent rubrics | `skills/pstack/references/agents/{poteto-agent,comment-sicko}.md`                                                                                                                                                                                                             |
-| Optional | `references/automations/benny` (Cursor-oriented templates under `skill-templates/`; not installable Agent Skills) |
+| Area | Skills and assets |
+| --- | --- |
+| Entry | `pstack`, `poteto-mode` |
+| Workflow | `how`, `why`, `recall`, `blast-radius`, `architect`, `arena`, `swarm`, `interrogate`, `figure-it-out`, `teach`, `reflect`, `automate-me`, `setup-pstack`, `show-me-your-work`, `create-verification-skill`, `maintain-verification-skill`, `tdd`, `typescript-best-practices` |
+| Quality | `unslop`, `no-comments`, `technical-writing`, `bro` |
+| Principles | all 21 `principle-*` leaf skills |
+| Playbooks | 23 mirrored under `skills/poteto-mode/playbooks/` and `skills/pstack/playbooks/` |
+| Runtime | `capability-contract.md` plus `generic`, `claude-code`, `codex`, `droid`, `opencode`, and `cursor` adapters |
+| Agent rubrics | `skills/pstack/references/agents/{poteto-agent,comment-sicko}.md` |
+| Optional | `references/automations/benny`, a Cursor-oriented source pack that is not installed as Agent Skills |
 
+## How portability works
 
+1. Skills express intent with the capability verbs `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, and `model_role`.
+2. Before delegation, the lead reads the matching adapter under `skills/pstack/references/adapters/`.
+3. The adapter maps those verbs to the host's actual tools, helper types, model controls, and fallback behavior.
+4. Parallel fan-out remains the default when the host exposes agent-spawn tools. The workflow collapses to the lead agent only when spawning is missing or denied.
+5. `/setup-pstack` resolves role-appropriate models through a host-specific override file. Portable skills must not require Cursor model slugs.
+6. The lead agent always owns synthesis, the final patch judgment, and verification on the narrowest meaningful real surface.
 
+The portable layer is an instruction protocol, not an emulator. It preserves workflow intent across hosts, but it cannot manufacture features a host does not expose. A runtime without subagents, model selection, browser control, or persistent modes will use the documented fallback and state the limitation.
 
-## How portability works
+## Session and mode behavior
+
+`/poteto-mode` is sticky when the active host supports persistent skill or mode state. On hosts without that lifecycle, treat it as active for the current conversation and invoke it again after a fresh session or a context reset. The engineering rules and playbooks remain portable even when the host cannot provide a native mode flag.
 
-1. Skills speak in capability verbs: `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, `model_role`.
-2. Before delegation, read the matching adapter under `pstack/references/adapters/` (`claude-code`, `droid`, `opencode`, `codex`, …).
-3. Prefer real subagent fan-out (`parallel`) on modern hosts. Collapse only when spawn tools are missing or denied.
-4. Model slugs are resolved via `/setup-pstack` overrides + `model_role`, not hard-required Cursor defaults.
+## Maintenance and audits
 
+The repository contains a structural and portability audit:
 
+```bash
+python3 scripts/audit_portability.py
+python3 scripts/audit_portability.py --strict --changed-from origin/main
+```
 
-## Not bundled (same as upstream)
+GitHub Actions runs the structural audit on `main` and on pull requests. It also rejects new vendor leakage in changed files, including concrete Cursor model slugs, Cursor-only tool fields, transcript paths, and drift between mirrored playbooks or adapters.
 
-Upstream poteto-mode references these but does not ship them in pstack:
+See [CONTRIBUTING.md](./CONTRIBUTING.md) before syncing a newer upstream revision. Mechanical regex porting is followed by a semantic review; capability verbs must describe the actual job rather than merely replacing vendor vocabulary.
 
-- `deslop`, `control-cli`, `control-ui` (Cursor `cursor-team-kit`) — use local equivalents
-- Cursor built-in `/create-skill` — use your agent’s skill authoring flow
+## Not bundled
 
+Upstream poteto-mode references tools that are not part of pstack itself:
 
+- `deslop`, `control-cli`, and `control-ui` from Cursor's `cursor-team-kit`; use equivalent cleanup and runtime-control tools available on the active host.
+- Cursor's built-in skill-authoring flow; use the active agent's corresponding authoring or validation workflow.
 
 ## Credits
 
-Adapted from pstack by Lauren Tan. See `NOTICE.md` and `LICENSE` (MIT).
+Adapted from pstack by Lauren Tan. See [NOTICE.md](./NOTICE.md) and [LICENSE](./LICENSE) for attribution and MIT licensing.