chore(pstack): sync upstream pstack (cursor/plugins#538..#617)

.claude/skills/sync-upstream/SKILL.md

@@ -10,10 +10,10 @@ This repo is two branches. `upstream` is a verbatim mirror of `cursor/plugins/ps
 ## Steps
 
 1. **Branch.** From a worktree off `main`, create `sync/upstream-<date>`.
-2. **Mirror.** Run `scripts/sync-upstream.sh`. It fast-forwards `upstream` from `origin`, commits the new snapshot, and pushes it, or reports that nothing changed. If nothing changed, stop and say so.
+2. **Mirror.** Run `scripts/sync-upstream.sh`. It fast-forwards `upstream` from `origin`, commits the new snapshot, and pushes it, or reports that nothing changed. If nothing changed, stop and say so. If it warns that the previous sync has not landed, land it first. If it warns that `main` squash-merged it, run the `git merge -s ours` it prints before step 4, which makes the previous mirror the merge base.
 3. **Read why.** `gh api --paginate 'repos/cursor/plugins/commits?path=pstack&per_page=100'` lists upstream's commits. Read down to the previously synced SHA, which the script printed. Read the messages of the new ones so the merge preserves poteto's intent, not just the text.
 4. **Merge.** `git merge upstream`. Resolve each conflict per `references/translation.md`: take upstream's new substance and keep the port's translation of it. Resolve by structure too:
-   - A file the port deleted (`automations/`, `docs/`, `assets/`, `.cursor-plugin/`, `skills/make-bot-ui/`, `skills/setup-pstack/`) stays deleted. Before discarding upstream's edit, check whether it carries a rule that belongs somewhere the port kept. A new `setup-pstack` role means a new row in `skills/poteto-mode/references/models.md`.
+   - A file the port deleted (`automations/`, `docs/`, `assets/`, `.cursor-plugin/`, `skills/make-bot-ui/`, `skills/setup-pstack/`, the root `plugin.json`) stays deleted. Before discarding upstream's edit, check whether it carries a rule that belongs somewhere the port kept. A new `setup-pstack` role means a new row in `skills/poteto-mode/references/models.md`.
    - `skills/poteto-help/` is rewritten for Claude Code, not mirrored. When upstream changes its skill map, playbook phrases, or troubleshooting table, carry the substance across and keep the port's own setup, install, and merge-policy sections.
    - `README.md` is the port's own. Keep ours, and add any new skill to its table.
    - A new `skills/principle-*/SKILL.md` moves to `skills/poteto-mode/principles/principle-*.md`, rewriting its relative links: `../principle-x/SKILL.md` becomes `./principle-x.md`, and `../<skill>/` becomes `../../<skill>/`.
@@ -22,7 +22,7 @@ This repo is two branches. `upstream` is a verbatim mirror of `cursor/plugins/ps
 6. **Verify.**
    - `bun test ./scripts/check-port.test.ts`
    - `cd skills/poteto-mode/scripts && bun test orch watch-pr`
-   - `claude plugin validate .`. Its `No version specified` warning is expected (see Deliberate departures).
+   - `claude plugin validate .`. Its `No version specified` warning is expected (see Deliberate departures), and so is its warning that the root `CLAUDE.md` is not loaded as plugin context, since that file is for contributors to this repo.
    - `claude -p --plugin-dir . "/pstack:poteto-mode quote the sentence that says where sibling skills live"` must print an absolute path.
    - `claude -p --plugin-dir . "Spawn a pstack:poteto-agent that quotes the same sentence from its preloaded skill"` must print the same absolute path.
    - `claude -p --plugin-dir . "Spawn a pstack:read-only agent and ask it to create a file named probe.txt"` must report that it refused or could not.

.claude/skills/sync-upstream/references/translation.md

@@ -22,10 +22,12 @@ The standing rules for porting upstream pstack text. `bun scripts/check-port.ts`
 | Cursor restart | Claude Code restart or context compaction |
 | `/loop` | unchanged. Claude Code ships `/loop` (dynamic mode when no interval is given) |
 | Cursor's built-in `/babysit` | delete the reference |
+| a parent-supplied path to `poteto-mode/SKILL.md`, or a search of `~/.cursor/plugins/` for it | delete. `pstack:poteto-agent` preloads the skill, and poteto-mode names its siblings by absolute path |
+| a built-in PR tool for create, edit, retarget, and ready | delete. `gh` covers every PR operation |
 
 ## Models
 
-Upstream slugs (`claude-opus-5-5-max`, `gpt-5.6-sol-max`, `grok-4.7-xhigh-fast`, composer, codex) become role lookups in `skills/poteto-mode/references/models.md`. Write "the `<role>` model from poteto-mode's `references/models.md`" rather than a model name. Aliases `inherit-parent` and `auto` become "omit `model`". Delete every paragraph about slugs that fail to resolve, budget tiers, or `~/.cursor/rules/pstack-models.mdc`. Claude Code's `model` parameter accepts `opus`, `sonnet`, or nothing here. Never `haiku` or `fable`. No non-Claude models.
+Upstream slugs (`claude-opus-5-5-max`, `gpt-5.6-sol-max`, `grok-4.7-xhigh-fast`, composer, codex) become role lookups in `skills/poteto-mode/references/models.md`. Write "the `<role>` model from poteto-mode's `references/models.md`" rather than a model name. Aliases `inherit-parent` and `auto` become "omit `model`". Delete every paragraph about slugs that fail to resolve, budget tiers, or `~/.cursor/rules/pstack-models.mdc`. The Agent tool has no reasoning-level or speed setting, so delete "pick each subagent's reasoning level and fast or standard speed". poteto-mode's "Match the model to the job" keeps only what the model dial can express: escalate to the hardest-tasks model, keep verification on `swarm workers`, keep panels as listed. Claude Code's `model` parameter accepts `opus`, `sonnet`, or nothing here. Never `haiku` or `fable`. No non-Claude models.
 
 ## Paths
 
@@ -34,7 +36,8 @@ Upstream slugs (`claude-opus-5-5-max`, `gpt-5.6-sol-max`, `grok-4.7-xhigh-fast`,
 | `~/.cursor/skills/`, `.cursor/skills/` | `~/.claude/skills/`, `.claude/skills/` |
 | `.cursor/rules/*.mdc` | the project's `CLAUDE.md` |
 | `~/.cursor/projects/<slug>/agent-transcripts/<uuid>/<uuid>.jsonl` | `~/.claude/projects/<slug>/<session-id>.jsonl`, where `<slug>` is the absolute working directory with every non-alphanumeric character replaced by `-`. Subagent transcripts are `~/.claude/projects/<slug>/<session-id>/subagents/agent-<id>.jsonl`. A skill gets its own session id as `${CLAUDE_SESSION_ID}` |
-| a principle skill `principle-<name>` | `skills/poteto-mode/principles/principle-<name>.md`. Keep the `principle-<name>` token in prose; the lint resolves it |
+| a principle skill `principle-<name>`, "the **<name>** principle skill", or "the **principle-<name>** skill" | `skills/poteto-mode/principles/principle-<name>.md`. Write the `**principle-<name>**` token in prose; the lint resolves it |
+| the agent store ("path in the system prompt") | a path the root names in the brief |
 
 ## Companion tools
 
@@ -45,7 +48,9 @@ Upstream slugs (`claude-opus-5-5-max`, `gpt-5.6-sol-max`, `grok-4.7-xhigh-fast`,
 | `control-cli` (CLIs, TUIs) | the built-in `run` skill |
 | iOS surfaces | the iOS Simulator tool |
 | `create-skill` (Cursor built-in) | the `skill-creator` skill |
-| Origin (`origin pr ...`) | delete. `gh` is the only forge |
+| `/visualize` (Cursor built-in) | the session's visual tool: an inline widget or an Artifact, when the session has one |
+| Origin (`origin pr ...`, `--forge origin`) | delete. `gh` is the only forge, in prose and in scripts (`orch`, `worktree-audit.sh`) |
+| a stack as a base-branch chain changed with `gh pr edit --base` | `gh stack` (`link`, `sync`, `rebase`, `push`). GitHub restacks the rest server-side after a bottom PR merges, so upstream's post-merge retarget goes away |
 | Bugbot, Cursor's agentic security review | "review bots" (Bugbot, Copilot, Greptile, CodeRabbit, and similar). The file keeps its name `references/bugbot-triage.md` |
 | `setup-pstack` | edit `skills/poteto-mode/references/models.md` |
 
@@ -74,4 +79,8 @@ A sync must keep these even when upstream's line differs.
 - `skills/poteto-mode/scripts/merge-gate/` is port-only. It reuses watch-pr's readiness verdict without editing watch-pr, and adds the policy: allowed repos, human-only paths needing a human approval on the head, and head pinning with `--match-head-commit`. A PR in a GitHub native stack refuses `gh pr merge`, so the gate falls back to the merge-async REST endpoint with the same head SHA. Every playbook merges only through it, and a refusal is final: human-only changes are the user's to merge. The policy lives outside git, and editing it is on poteto-mode's always-pause list.
 - `principle-never-block-on-the-human` narrows its force-push example to "force-push to a shared branch", matching poteto-mode's Autonomy. Autopilot owners force-push their own branches with a lease on every rebase.
 - models.md uses only `opus` and `sonnet`. `fable` is dropped for cost: every role that upstream maps to it, and every panel slot, goes to `opus` or `sonnet`. interrogate runs two reviewers (`opus`, `sonnet`), accepting that both share one family and give less independent review than a cross-family pair.
+- `orch frontier set` walks the PR base chain with `gh` only. Upstream's `--forge` option and its Origin branch are removed, so the command takes no forge.
+- Autopilot-stack owners never force-push a branch once the root links it into the `gh stack`. They only add commits, and take the root's push as their new base and lease. Moving a PR out of a stack is the user's, since `gh stack modify` is interactive.
+- Shipping and Autopilot-full merge through `merge-gate`, never `gh pr merge --squash`, and never arm `--auto`, because GitHub merges at once without required checks.
+- `skills/poteto-mode/scripts/check-plan.test.ts` uses the port's plan template: "Ten lanes at the PR head" with no model, and the "Re-read them at every tick" marker.
 - `skills/poteto-help/` is rewritten, not ported line for line. Setup, Custom Modes, and the guide pages are replaced by `claude plugin` install and update, `models.md`, and the README's merge-policy section. Its skill map uses relative links, and the skill tells the model to give users the public GitHub URL.

README.md

@@ -36,6 +36,9 @@ You can also call the other skills directly:
 | `teach` | you want to understand a change or subsystem, built up diagram by diagram |
 | `recall` | you're resuming work and want your recent context rebuilt from past sessions |
 | `bro` | you want the last message restated in plain language |
+| `ketchup` | you want a short catch-up on what changed since your last message, with what still needs you |
+| `in-your-own-words` | you want the agent to play back your goal and the problem before it starts |
+| `sharpen` | you want a task approached the way a top expert would, without overspecifying it |
 | `correct` | agents keep repeating the same mistake in a repo and each one should become impossible |
 | `benchmark-checklist` | you ran a benchmark and want the measurement vetted before you report it |
 | `poteto-help` | you're new to pstack or unsure which skill fits. Type `/pstack:poteto-help` with a question |
@@ -54,7 +57,7 @@ You can also call the other skills directly:
 | `create-verification-skill`, `maintain-verification-skill` | a project needs a scripted way to prove app behavior |
 | `automate-me` | you want your own `<name>-mode` skill drafted from how you work |
 
-The 23 principles live in `skills/poteto-mode/principles/`. poteto-mode reads them on demand instead of loading them into every session.
+The 24 principles live in `skills/poteto-mode/principles/`. poteto-mode reads them on demand instead of loading them into every session.
 
 ## Letting agents merge
 

agents/poteto-agent.md

@@ -1,10 +1,10 @@
 ---
 name: poteto-agent
-description: Routing target for any subagent spawned inside a poteto-mode playbook step (code-writing delegates, ad-hoc helpers). Spawn a fresh `poteto-agent` for each new task, and resume one only in the strict cases that poteto-mode's Subagents section names. Loads the `poteto-mode` skill in full before any work, including its inline Principles index. Substituting `general-purpose` skips that and drifts.
+description: Delegate subagent for code-writing and helper tasks spawned during a poteto-mode run. Use for delegates, not as the runner for poteto-mode itself. Spawn a fresh `poteto-agent` for each new task, and resume one only in the strict cases that poteto-mode's Subagents section names. Loads the `poteto-mode` skill in full before any work, including its inline Principles index. Substituting `general-purpose` skips that and drifts.
 skills: [poteto-mode]
 background: true
 ---
 
 # Poteto subagent
 
-You are operating as poteto-mode's full agent style. Read the `poteto-mode` skill's `SKILL.md` in full before doing any work, including its inline Principles index. Read a principle's file under `principles/` whenever you apply that principle.
+You are operating as poteto-mode's full agent style. The chat that runs poteto-mode owns the playbook, the todo list, and every Agent spawn. You are one of its delegates. Read the `poteto-mode` skill's `SKILL.md` in full before doing any work, including its inline Principles index. Read a principle's file under `principles/` whenever you apply that principle.

scripts/check-port.test.ts

@@ -24,6 +24,7 @@ describe("findingsFor", () => {
     ["skills/x/SKILL.md", "Each a cloud agent.", "cursor-cloud-agent"],
     ["skills/x/SKILL.md", "mode: true", "cursor-frontmatter"],
     ["skills/x/SKILL.md", "Follow the **create-skill** skill.", "cursor-builtin-skill"],
+    ["skills/x/SKILL.md", "Draw it with a `/visualize` chart.", "cursor-builtin-skill"],
     ["skills/x/SKILL.md", "Triage the Bugbot comments.", "cursor-bugbot"],
     ["skills/x/SKILL.md", "Read **principle-made-up-name**.", "unresolved-principle"],
     ["skills/swarm/SKILL.md", 'Spawn with `environment: "cloud"`.', "cursor-tool"],
@@ -36,8 +37,24 @@ describe("findingsFor", () => {
     ["skills/poteto-mode/principles/principle-laziness-protocol.md", "Distinct from [x](../principle-build-the-lever/SKILL.md).", "unresolved-link"],
     ["skills/how/SKILL.md", 'See [x](../nope/SKILL.md "title").', "unresolved-link"],
     ["README.md", "See [x](skills/nope/SKILL.md).", "unresolved-link"],
+    ["skills/poteto-mode/SKILL.md", "## Principles\n\n- **Made Up Rule.** When nothing else fits.", "unresolved-principle-title"],
+    ["skills/poteto-mode/SKILL.md", "## Playbooks\n\n- **Made Up Playbook.** Something.", "unresolved-playbook-title"],
+    ["skills/poteto-mode/SKILL.md", "## Principles\n\n- **Made Up Rule.** See **principle-laziness-protocol** first.", "unresolved-principle-title"],
+    ["skills/x/SKILL.md", "Pick the reasoning-level per job.", "effort-dial"],
+    ["skills/poteto-mode/playbooks/babysit.md", "Publish it per `playbooks/autopilot-stack.md` step 7.", "unresolved-step"],
+    ["skills/x/SKILL.md", "Merge it per Autopilot-stack step 9.", "unresolved-step"],
+    ["skills/x/SKILL.md", "Run Opening a PR steps 2 and 9.", "unresolved-step"],
+    ["skills/x/SKILL.md", "Use step 9 of the Perf issue playbook.", "unresolved-step"],
+    ["skills/poteto-mode/SKILL.md", "## Principles\n\n- **Made Up Rule.** See **x** (**principle-laziness-protocol**).", "unresolved-principle-title"],
+    ["skills/poteto-mode/SKILL.md", "## Playbooks\n\n- **Made Up Playbook.** Per **principle-laziness-protocol**.", "unresolved-playbook-title"],
+    ["skills/poteto-mode/SKILL.md", "## Playbooks\n\n- **Cleanup.** Something. File: `playbooks/nope.md`.", "unresolved-playbook-title"],
     ["skills/poteto-mode/references/models.md", "| interrogate reviewers | `opus`, `fable` |", "fable-model"],
     ["skills/x/SKILL.md", 'Spawn with `model: "fable"`.', "fable-model"],
+    ["skills/x/SKILL.md", "Pick each subagent's reasoning level and fast or standard speed for the job.", "effort-dial"],
+    ["skills/x/SKILL.md", "Apply the **laziness-protocol** principle skill.", "principle-as-skill"],
+    ["skills/x/SKILL.md", "Parse it in a subagent (the **principle-guard-the-context-window** skill).", "principle-as-skill"],
+    ["skills/x/SKILL.md", "Read the leaf skill in full for any principle you apply.", "principle-as-skill"],
+    ["skills/x/SKILL.md", 'Spawn `subagent_type: "poteto-agent"`.', "unprefixed-agent"],
     [".claude-plugin/plugin.json", '  "version": "0.15.4",', "plugin-version"],
     [".claude-plugin/marketplace.json", '      "version": "1.0.0",', "plugin-version"],
   ])("%s flags %p as %s", (path, line, rule) => {
@@ -64,7 +81,18 @@ describe("findingsFor", () => {
     ["a link with an anchor", "skills/how/SKILL.md", "See [teach](../teach/SKILL.md#usage)."],
     ["a web link", "skills/how/SKILL.md", "See [docs](https://example.com/a/b.md)."],
     ["an in-page anchor", "skills/how/SKILL.md", "See [below](#step-1)."],
+    ["a principle title that resolves", "skills/poteto-mode/SKILL.md", "## Principles\n\n- **Test Behavior, Not Implementation.** Writing a test."],
+    ["a principle entry that names its file", "skills/poteto-mode/SKILL.md", "## Principles\n\n- **Sequence Work into Verifiable Units** (**principle-sequence-verifiable-units**). Multi-step work."],
+    ["a step range that exists", "skills/x/SKILL.md", "Run Opening a PR steps 1 to 3."],
+    ["a step named after its playbook", "skills/x/SKILL.md", "Use step 2 of the Perf issue playbook."],
+    ["a step that exists by path", "skills/poteto-mode/playbooks/babysit.md", "Publish it per `playbooks/autopilot-stack.md` step 3."],
+    ["a step that exists by title", "skills/x/SKILL.md", "Run Opening a PR step 2."],
+    ["a bold bullet outside both indexes", "skills/poteto-mode/SKILL.md", "## Autonomy\n\n- **Made Up Thing.** Something."],
+    ["a playbook title that resolves", "skills/poteto-mode/SKILL.md", "## Playbooks\n\n- **Opening a PR.** Invoked at the end."],
+    ["a playbook entry that names its file", "skills/poteto-mode/SKILL.md", "## Playbooks\n\n- **Multi-phase or multi-PR plan.** Work. File: `playbooks/multi-phase-plan.md`."],
     ["a principle link", "skills/poteto-mode/principles/principle-laziness-protocol.md", "See [x](./principle-build-the-lever.md)."],
+    ["the fast-path idiom", "skills/x/SKILL.md", "Take the fast path when the cache is warm."],
+    ["a prefixed agent", "skills/x/SKILL.md", 'Spawn `subagent_type: "pstack:poteto-agent"`.'],
     ["a version field elsewhere", "skills/poteto-mode/scripts/package.json", '  "version": "1.0.0",'],
   ])("allows %s", (_, path, line) => {
     expect(findingsFor(path, line)).toEqual([]);