feat(pstack): update Codex port to upstream 0.15.10

.github/workflows/validate.yml

@@ -0,0 +1,38 @@
+name: Validate Codex port
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: '1.3.14'
+      - name: Audit skills and model routes
+        run: ./scripts/audit.py
+      - name: Check installer syntax
+        run: bash -n scripts/install.sh scripts/check-upstream.sh
+      - name: Test the audit, plan checker, and isolated installation
+        run: python3 -m unittest discover -s tests -v
+      - name: Install PR watcher dependencies
+        working-directory: skills/poteto-mode/scripts
+        run: bun install --frozen-lockfile
+      - name: Test and typecheck the PR watcher
+        working-directory: skills/poteto-mode/scripts
+        run: |
+          bun run test
+          bun run typecheck

.gitignore

@@ -2,3 +2,4 @@
 *.tmp
 reports/
 node_modules/
+__pycache__/

AGENTS.md

@@ -6,6 +6,7 @@
 - Do not introduce Cursor-only paths, tools, model slugs, or agent types.
 - Codex collaboration agents inherit the session runtime unless the active tool schema says otherwise.
 - Keep external writes inside the user's explicit scope.
-- Run `./scripts/audit.py` before publishing changes.
+- Run `./scripts/audit.py` before publishing changes. For audit, installer, or plan-checker changes, also run `python3 -m unittest discover -s tests -v`.
+- Keep model and reasoning pairs verified in the current Codex schema. Luna has no Ultra effort. Full-history child forks inherit the parent; overrides need a fresh task-local child.
 - Update `UPSTREAM_COMMIT` only after the corresponding upstream changes have been reviewed and ported.
 

README.md

@@ -10,7 +10,7 @@ The engineering principles and playbooks remain pstack's. The runtime integratio
 - Codex browser, computer-use, GitHub, and automation tools
 - `.codex/skills` for global and project-local skills
 
-The port currently contains 44 skills, including `poteto-mode`, its playbooks, `swarm`, the workflow skills, and 21 engineering principles. The 0.14 port adds `bro`, `no-comments`, `technical-writing`, Babysit, Shipping, Autopilot-full, Autopilot-stack, Orchestrate, and safe worktree cleanup.
+The port tracks upstream **0.15.10** at [`4e5b1cf`](https://github.com/cursor/plugins/commit/4e5b1cf2ccb0ea3716f08c8ee0a5856b5ab93536), reviewed on October 5, 2026. It contains **50 skills**, including 24 engineering principles. This update adds `poteto-help`, `correct`, `benchmark-checklist`, three principle skills, a checked multi-PR plan, stronger architecture screening, and evidence-backed benchmark and PR verification guidance. See [the port record](docs/upstream-port.md) for adaptations and exclusions.
 
 ## Install
 
@@ -20,7 +20,7 @@ cd pstack-codex
 ./scripts/install.sh
 ```
 
-The installer backs up any same-named global skills before writing to `~/.codex/skills`. It does not touch unrelated skills.
+The installer validates the source, then backs up any same-named global skills before writing to `~/.codex/skills`. It preserves unrelated skills and existing pstack configuration. `./scripts/install.sh --dry-run` shows the changes without writing files. Local dependency caches are excluded.
 
 Restart Codex or start a new task after installation so the refreshed skill catalog loads.
 
@@ -34,6 +34,22 @@ Use setup-pstack and configure pstack with your recommended Codex settings.
 
 The setup skill writes `~/.codex/pstack/config.md`. When the active collaboration tool exposes model and reasoning-effort selection, the configuration routes verified Codex models by role; otherwise agents inherit the session runtime. It also controls fan-out, isolation, memory, verification, and publication policy.
 
+The recommended balanced setup uses only models available in Codex:
+
+| Role | Model and reasoning |
+|---|---|
+| Parent, complex implementation, and synthesis | `gpt-6.1-sol@high` |
+| Routine implementation | `gpt-6.1-sol@medium` |
+| Focused exploration and swarm workers | `gpt-6-luna@high` |
+| Hardest design work and demanding review | `gpt-6-astra@high` |
+| Review panels | Luna High, Sol High, Astra High |
+
+These choices balance the efficient Luna with Sol for sustained work and Astra for the hardest judgment. They follow [official Codex model guidance](https://learn.chatgpt.com/docs/models) and were verified against this session's model schema on October 5, 2026. Re-check availability when configuring another account or client. Luna supports up to Max, not Ultra. See [config.example.md](config.example.md) for all routes.
+
+Choose the parent in Codex's model picker. Routes control compatible child spawns and cannot change the active parent. A model override uses a fresh child with task-local context; full-history forks inherit. With no compatible override, children inherit the session runtime. Fan-out is capped by the live slot limit and configured maximum, with three children as the example cap.
+
+After upgrading an existing installation, rerun `setup-pstack` to review model changes and retire `how critics` and `cross-judge`. Installation preserves your existing configuration.
+
 ## Use
 
 Start rigorous work with:
@@ -67,6 +83,23 @@ After porting an upstream update, replace `UPSTREAM_COMMIT` with the reviewed up
 ./scripts/audit.py
 ```
 
+## Validate
+
+```bash
+./scripts/audit.py
+python3 -m unittest discover -s tests -v
+```
+
+The audit checks skill discovery, frontmatter, references, runtime dependencies, and model routes. Tests exercise unsupported models and efforts, inherited panel seats, incomplete plans, and installation with backup and config preservation. GitHub Actions also runs the bundled PR watcher tests and strict typecheck.
+
+The Multi-phase plan playbook includes a complete checklist template. Check a filled plan with:
+
+```bash
+node skills/poteto-mode/scripts/check-plan.mjs /path/to/plan.md
+```
+
+The Codex checker accepts a stated positive lane count and screenshots or terminal receipts. Choose lanes by the behavior being proved and run them within the runtime's capacity.
+
 ## Attribution
 
 pstack was created by [Lauren Tan](https://github.com/poteto) and is published in the [Cursor plugins repository](https://github.com/cursor/plugins/tree/main/pstack) under the MIT License. This repository is an independent Codex port and is not affiliated with Cursor or OpenAI.

UPSTREAM_COMMIT

@@ -1 +1 @@
-9490cc1cf95d5de2e4941196cdac00dd861812a4
+4e5b1cf2ccb0ea3716f08c8ee0a5856b5ab93536

config.example.md

@@ -3,31 +3,41 @@
 ## Parent task
 
 - runtime: Codex
-- recommendation: gpt-5.6-sol@xhigh for architecture and final synthesis
+- recommendation: gpt-6.1-sol@high for daily coding and final synthesis
 - boundary: pstack cannot change the active task model or reasoning effort; select them when starting the task
 
+## Budget
+
+- profile: balanced
+- policy: preserve the per-role efforts below; a requested large, medium, or small budget maps routes to xhigh, high, or medium only when that model supports it
+- verified: 2026-10-05 from the active Codex collaboration schema
+
 ## Model routes
 
-- default child: gpt-5.6-terra@medium
-- routine work: gpt-5.6-terra@high
-- complex work: gpt-5.6-sol@high
-- how explorers: gpt-5.6-terra@medium
-- why investigators: gpt-5.6-terra@medium
-- why synthesizer: gpt-5.6-sol@high
-- how critics: gpt-5.6-terra@high, gpt-5.6-sol@high, gpt-5.6-sol@xhigh
-- arena runners: gpt-5.6-terra@high, gpt-5.6-sol@high, gpt-5.6-sol@xhigh
-- architect runners: gpt-5.6-terra@high, gpt-5.6-sol@high, gpt-5.6-sol@xhigh
-- interrogate reviewers: gpt-5.6-terra@high, gpt-5.6-sol@high, gpt-5.6-sol@xhigh
-- cross-judge: gpt-5.6-terra@xhigh
-- reflect tooling: gpt-5.6-terra@medium
-- reflect judgment: gpt-5.6-sol@high
-- reflect divergent: gpt-5.6-terra@xhigh
-- reflect synthesizer: gpt-5.6-sol@high
-- swarm workers: gpt-5.6-terra@medium
+- default child: gpt-6-luna@medium
+- routine work: gpt-6.1-sol@medium
+- complex work: gpt-6.1-sol@high
+- bug-fix: gpt-6.1-sol@high
+- perf-issue: gpt-6.1-sol@high
+- hillclimb: gpt-6.1-sol@high
+- hardest tasks: gpt-6-astra@high
+- how explorers: gpt-6-luna@high
+- how explainer: gpt-6.1-sol@high
+- why investigators: gpt-6-luna@high
+- why synthesizer: gpt-6.1-sol@high
+- arena runners: gpt-6-luna@high, gpt-6.1-sol@high, gpt-6-astra@high
+- architect runners: gpt-6-luna@high, gpt-6.1-sol@high, gpt-6-astra@high
+- interrogate reviewers: gpt-6-luna@high, gpt-6.1-sol@high, gpt-6-astra@high
+- arena cross-judge pool: gpt-6-astra@high, gpt-6.1-sol@high, gpt-6-luna@high
+- reflect tooling: gpt-6-luna@medium
+- reflect judgment: gpt-6.1-sol@high
+- reflect divergent: gpt-6-astra@high
+- reflect synthesizer: gpt-6.1-sol@high
+- swarm workers: gpt-6-luna@high
 
 ## Runtime policy
 
-- model routing: pass a route's model and reasoning effort when the collaboration tool supports both; otherwise inherit the session runtime
+- model routing: pass a route's model and reasoning effort when the collaboration tool supports both; otherwise inherit the session runtime; use minimal task-local context for a model override
 - maximum parallel children: 3
 - default arena candidates: 3
 - default review panel: 3

docs/upstream-port.md

@@ -0,0 +1,57 @@
+# Upstream port record
+
+This update ports the pstack changes between `9490cc1cf95d5de2e4941196cdac00dd861812a4` and [`4e5b1cf2ccb0ea3716f08c8ee0a5856b5ab93536`](https://github.com/cursor/plugins/commit/4e5b1cf2ccb0ea3716f08c8ee0a5856b5ab93536). The reviewed upstream version is 0.15.10, checked on October 5, 2026. All 25 pstack commits in that range were reviewed.
+
+The original MIT license and attribution remain. Codex runtime instructions take precedence over upstream Cursor integration.
+
+## Changes reviewed
+
+| Upstream commit | Disposition |
+|---|---|
+| [63d938c](https://github.com/cursor/plugins/commit/63d938c) | Exclude the Grok default. Codex routes replace provider defaults. |
+| [4612556](https://github.com/cursor/plugins/commit/4612556) | Port workflow and schema-first boundary guidance. Adapt runtime tools. |
+| [bdf7aa3](https://github.com/cursor/plugins/commit/bdf7aa3) | Adapt the verified multi-PR checklist and executable plan checker. |
+| [799151d](https://github.com/cursor/plugins/commit/799151d) | Exclude make-bot-ui and its Grok Bot and Tailscale prerequisites. |
+| [6fecddb](https://github.com/cursor/plugins/commit/6fecddb) | Exclude registration of the excluded Bot UI skill. |
+| [73f8be4](https://github.com/cursor/plugins/commit/73f8be4) | Exclude Cursor invocation frontmatter. Preserve name and description discovery. |
+| [23a56e2](https://github.com/cursor/plugins/commit/23a56e2) | Adapt forge-neutral PR mechanics, stack verification, and schemas. Exclude Fable defaults. |
+| [efa2a53](https://github.com/cursor/plugins/commit/efa2a53) | Exclude Cursor plugin logo metadata. |
+| [7314f72](https://github.com/cursor/plugins/commit/7314f72) | Exclude the Cursor plugin image size change. |
+| [e8d856f](https://github.com/cursor/plugins/commit/e8d856f) | Port prose improvements, attack-the-premise, and test-behavior-not-implementation. |
+| [d7cde2b](https://github.com/cursor/plugins/commit/d7cde2b) | Port the prose punctuation pass while retaining Codex runtime wording. |
+| [71ed0d1](https://github.com/cursor/plugins/commit/71ed0d1) | Adapt version and skill counts to this port's manifest. |
+| [f8abedd](https://github.com/cursor/plugins/commit/f8abedd) | Port evidence-or-label claims. |
+| [f5bdd68](https://github.com/cursor/plugins/commit/f5bdd68) | Port operator-neutral wording and report only previously unreported status changes. |
+| [889ec4b](https://github.com/cursor/plugins/commit/889ec4b) | Replace provider defaults with Codex bug-fix, perf-issue, and hillclimb routes. |
+| [5bf2b15](https://github.com/cursor/plugins/commit/5bf2b15) | Adapt reasoning budgets to verified Codex model and effort pairs. |
+| [70b2dc8](https://github.com/cursor/plugins/commit/70b2dc8) | Port benchmark-checklist and workflow updates. Replace Opus and Grok defaults. |
+| [b42effe](https://github.com/cursor/plugins/commit/b42effe) | Adapt upgrade help to verified Codex models. |
+| [b0b9c7a](https://github.com/cursor/plugins/commit/b0b9c7a) | Port instruction reductions where they preserve Codex runtime and authorization rules. |
+| [12d587d](https://github.com/cursor/plugins/commit/12d587d) | Adapt consistent model-config reads, inherited routes, and the simplified How workflow. Retire How's critic panel. |
+| [23e4138](https://github.com/cursor/plugins/commit/23e4138) | Port explain-the-number, fresh-owner handoff, schema-first casts, and PR headings. Adapt hourly audits to Codex heartbeat automations. |
+| [9511e60](https://github.com/cursor/plugins/commit/9511e60) | Port correct, with architecture and types before lints, tests, or docs. |
+| [a586282](https://github.com/cursor/plugins/commit/a586282) | Port architecture screening for split ownership, duplicate APIs, exposed internals, and hand-synced lists. |
+| [e43c7ee](https://github.com/cursor/plugins/commit/e43c7ee) | Port the ordered performance mantras. |
+| [4e5b1cf](https://github.com/cursor/plugins/commit/4e5b1cf) | Adapt poteto-help to Codex installation, routes, collaboration, and scheduling. |
+
+## Codex adaptations
+
+Model routes use separate `model@reasoning_effort` values, with `inherit-parent` and `auto` for inheritance. The balanced example uses GPT-6.1 Sol, GPT-6 Luna, and GPT-6 Astra. These model slugs and effort ranges were verified against the active Codex schemas and [official model documentation](https://learn.chatgpt.com/docs/models). Model availability must be rechecked in each setup session. The parent model remains a user-selected Codex setting.
+
+Full-history child forks inherit their parent's model and effort. A route override therefore needs a fresh child with minimal task-local context. All fan-out respects the runtime's live capacity. An instruction to keep a task read-only replaces upstream spawn fields that Codex does not expose.
+
+The plan checker preserves the ordered PR blocks, verification rules, performance probe, and review gate. A stated positive number of lanes replaces the fixed ten-lane assumption. CLI and library lanes save terminal receipts; UI lanes save screenshots. Missing or duplicate lanes and missing receipts fail the checker.
+
+PR operations resolve one forge for the run. GitHub CLI remains the default. Origin is optional and only used when detected and able to resolve the repository. Graphite is not required. PR monitoring retains this port's tested GitHub watcher. Merge authority still needs the user's explicit landing scope. Verification receipts are tied to the patch and current head.
+
+Requested hourly follow-up uses a saved Codex heartbeat automation when available. The prompt reports meaningful changes only. No active scheduler is created by installing these skills. Installed playbooks are resolved from the actual pstack source path rather than assumed to live inside the application repository.
+
+Memory and transcript review use scoped Codex history, the active conversation, or supplied artifacts. Unavailable transcripts are an evidence gap. This port keeps its safe worktree cleanup and bounded Orchestrate implementation rather than importing upstream's cloud-agent, orch CLI, or fixed platform assumptions. Upstream guides are represented by the Codex README and poteto-help rather than copied with incompatible installation instructions.
+
+Comment Sicko is supplied as a prompt for a normal Codex collaboration reviewer. It is not a fabricated Codex agent type. The parent reviews its patch, preserves proven constraints without missing approval, and owns application-code fixes. Reflection does not authorize ticket writes or global memory changes.
+
+## Validation
+
+Run `./scripts/audit.py` and `python3 -m unittest discover -s tests -v`. The tests check actual rejection of invalid routes and incomplete plans, then install and reinstall in isolated temporary Codex homes. They verify skill contents, backups, existing configuration, unrelated skills, cache exclusion, and a dry run with no writes.
+
+The bundled watcher retains its 38 tests and strict TypeScript check. GitHub Actions runs these checks on pull requests and pushes to main. Structural validation and these deterministic tests prove packaging and checker behavior. They do not prove every workflow's future LLM behavior or a production application's runtime.

manifest.txt

@@ -1,20 +1,25 @@
 architect
 arena
 automate-me
+benchmark-checklist
 blast-radius
 bro
+correct
 create-verification-skill
 figure-it-out
 how
 interrogate
 maintain-verification-skill
 no-comments
+poteto-help
 poteto-mode
+principle-attack-the-premise
 principle-boundary-discipline
 principle-build-the-lever
 principle-encode-lessons-in-structure
 principle-exhaust-the-design-space
 principle-experience-first
+principle-explain-the-number
 principle-fix-root-causes
 principle-foundational-thinking
 principle-guard-the-context-window
@@ -30,6 +35,7 @@ principle-redesign-from-first-principles
 principle-separate-before-serializing-shared-state
 principle-sequence-verifiable-units
 principle-subtract-before-you-add
+principle-test-behavior-not-implementation
 principle-type-system-discipline
 recall
 reflect