dsh-pstack 0.1.0 → 0.2.0-beta.1

package/assets/skills/figure-it-out/SKILL.md

@@ -4,51 +4,51 @@ description: "Design an auditable playbook when no narrower one fits: a large mi
 disable-model-invocation: true
 ---
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's `Task` tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
 # Figure it out
 
+> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+
 When the task matches no playbook, design one. The deliverable before any code is the workflow itself: a sequence of phases that scales rigor to the task, runs the scientific method, and leaves a decision trail a human can audit after stepping away.
 
 ## Start
 
-Call `todo_write` with a list whose first item is to read the Principles section of the **poteto-mode** skill. Then add the phases below as todos.
+Open a `todo_write` list whose first item is to read the Principles section of the `poteto-mode` skill, at its absolute resource path. Then add the phases below as items.
 
 ## Phase A: Frame
 
 Ground first, then commit. Don't start the run until you can state:
 
-- The definition of done as a falsifiable predicate (the **prove-it-works** principle skill).
+- The definition of done as a falsifiable predicate, as `principle-prove-it-works` requires; read its `SKILL.md` at its absolute resource path.
 - Scope, quantified: rough units and effort, plus the blockers grounding surfaced.
 - The rigor level, biased high. One-way doors and high blast radius get more. Reversible low-stakes steps get less. Rigor is gates and artifacts, not "try harder".
 
-Present the framing and tradeoffs before committing to a long run. Reversible work proceeds (the **never-block-on-the-human** principle skill), but a multi-hour run earns one checkpoint.
+Present the framing and tradeoffs before committing to a long run. Reversible work proceeds, as `principle-never-block-on-the-human` requires; read its `SKILL.md` at its absolute resource path. A multi-hour run earns one checkpoint, asked through `ask_user_question`.
 
 ## Phase B: Design the workflow
 
-Decompose into atomic, independently-landable units. Sequence riskiest-unknown-first. Scaffold and verification come before features (the **foundational-thinking** principle skill).
+Decompose into atomic, independently-landable units. Sequence riskiest-unknown-first. Scaffold and verification come before features, as `principle-foundational-thinking` requires; read its `SKILL.md` at its absolute resource path.
 
 - Build the verification harness before the work, with the baseline captured from the pre-change state, so the check reads as "old value vs new value".
-- For one-way-door design decisions, run the **architect** skill (it runs **arena**). Skip it for mechanical work whose shape is already concrete. A second arena over a settled design is over-engineering (the **laziness-protocol** principle skill).
-- Decide what fans out. Parallelize only across seams, and give each worker its own worktree or branch (the **separate-before-serializing-shared-state** principle skill). Don't over-fan. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill.
+- For one-way-door design decisions, read the `architect` skill's `SKILL.md` at its absolute resource path and run it; it runs `arena` in turn. Skip it for mechanical work whose shape is already concrete. A second arena over a settled design is over-engineering, per `principle-laziness-protocol`.
+- Decide what fans out. Parallelize only across seams, and give each worker its own checkout: the worker calls `create_worktree` in its own Session, or you create the checkouts one at a time and pass each absolute `path` as that worker's `cwd`. Read `principle-separate-before-serializing-shared-state` at its absolute resource path. Don't over-fan. Read the Subagents section of the `poteto-mode` skill at its absolute resource path before you spawn anyone. Start from the level the role line names, raise it for hard work and lower it for routine work by passing `reasoningEffort`; a child that cannot call `set_reasoning_effort` keeps the level you gave it.
 - Write the designed phase list down. That list is what the human reviews.
 
-Then execute the design. Add its steps to the todo list as concrete items between the Phase C and Phase D entries. Run each under the Phase C loop discipline, and weave the Phase D log through them, a row as each step lands, rather than saving the whole trail for the end.
+Then execute the design. Add its steps to the `todo_write` list as concrete items between the Phase C and Phase D entries. Run each under the Phase C loop discipline, and weave the Phase D log through them, a row as each step lands, rather than saving the whole trail for the end.
 
 ## Phase C: Run the loop
 
-Each unit is an experiment. State the hypothesis, make the smallest change, measure against the predicate on the real artifact, keep it if it advanced, revert it if it didn't. Apply the **sequence-verifiable-units** principle skill, verifying each unit before starting the next instead of batching checks at the end.
+Each unit is an experiment. State the hypothesis, make the smallest change, measure against the predicate on the real artifact, keep it if it advanced, revert it if it didn't. Read `principle-sequence-verifiable-units` at its absolute resource path and verify each unit before starting the next instead of batching checks at the end.
 
 - Verify by inspecting the artifact, never a self-report. When something passes too easily, suspect the observation method before the system.
-- Pair delegated work with a judge. If a worker games the gate, reset and harden the contract. If the gate itself is wrong, fix the gate in its own change rather than routing around it.
+- Pair delegated work with a judge: a second `pstack_subagent` child that reads the same artifact and the same predicate, never the worker's own report. If a worker games the gate, reset and harden the contract. If the gate itself is wrong, fix the gate in its own change rather than routing around it.
 - A verdict is VERIFIED, NOT VERIFIED, or INCONCLUSIVE. Inconclusive is not a pass. Don't hide a negative.
 
 ## Phase D: Keep the audit trail
 
-Log the run via the **show-me-your-work** skill. figure-it-out's work is usually ambitious enough to commit the trail so the reviewer can read it in the PR. The trail plus the diff is what lets the human come back and trust the work.
+Log the run as the `show-me-your-work` skill prescribes; read its `SKILL.md` at its absolute resource path. Its session-audit step needs the restricted history tool, which this package does not ship yet, so keep the decision trail inside the repository and report that part of the audit as unverified. figure-it-out's work is usually ambitious enough to commit the trail so the reviewer can read it in the PR. The trail plus the diff is what lets the human come back and trust the work.
 
 ## Phase E: Verify and hand back
 
-Check the whole against the Phase A predicate on the real product, not just the harness. Encode any recurring correction as a gate, a lint rule, a check, or a script (the **encode-lessons-in-structure** principle skill).
+Check the whole against the Phase A predicate on the real product, not just the harness. Encode any recurring correction as a gate, a lint rule, a check, or a script, as `principle-encode-lessons-in-structure` requires; read its `SKILL.md` at its absolute resource path.
 
 **Reply:** the playbook you designed, the rigor level and why, the decision-trail path, what's verified against the predicate, and what's still open.

package/assets/skills/how/SKILL.md

@@ -4,30 +4,30 @@ description: Use for "how does X work", code walkthroughs before changing someth
 disable-model-invocation: true
 ---
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's `Task` tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
 # How
 
+> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+
 Explore the codebase to answer "how does X work?" questions. Produce architectural explanations at the level of a senior engineer onboarding onto a subsystem, enough to build a working mental model, not so much that it reads like annotated source code.
 
-Every spawn is a `pstack_subagent` call with `agent: "general"`; tell it not to edit files. Explorers pass `role: "how explorer"` and every explainer passes `role: "how explainer"`; the tool resolves each from `~/.dsh/pstack-models.md`. When the file or line is missing, the child inherits the parent model.
+Every spawn is a `pstack_subagent` call with `agent: "general"` and `role: "how explorer"` or `role: "how explainer"`. Read that role's route from `$DSH_HOME/pstack-models.md`; the tool re-reads the file on every delegation, and a role the file does not name inherits the parent route. Never invent a model id: this package cannot know which routes a deployment serves. An effort is different, because the target model advertises its own list and `pstack_subagent` checks your value against it and names the real values when it refuses, so predict no ladder beyond that. Explorers are read-only by instruction, not by sandbox, so state the no-write rule in each brief and check `git status` after the child reports. Read the Subagents section of the `poteto-mode` skill at its absolute resource path before you spawn anything. Start from the level the role line names, raise it for hard work and lower it for routine work by passing `reasoningEffort`; a child that cannot call `set_reasoning_effort` keeps the level you gave it.
 
 ## 1. Assess complexity
 
 If the scope is ambiguous, state your interpretation and explore. The user can redirect.
 
-- **Simple** (a single module, a small utility, a narrow question such as "how does function X work"): no explorers. Spawn one explainer that explores and explains in one pass, built from `references/explainer-prompt.md` without the explorer-findings section. Go to step 4.
+- **Simple** (a single module, a small utility, a narrow question such as "how does function X work"): no explorers. Start one explainer child with `references/explainer-prompt.md` and no explorer findings; it explores and explains in one pass. Go to step 4.
 - **Complex** (a subsystem spanning multiple files or services, a cross-cutting feature, a full architectural overview): go to step 2.
 
 When in doubt, take the simple path.
 
 ## 2. Explore (complex only)
 
-Decompose the question into 2 to 4 angles, each a distinct slice of the subsystem. Spawn all explorers in a single message, each with `references/explorer-prompt.md` and its angle filled in.
+Decompose the question into 2 to 4 angles, each a distinct slice of the subsystem. Start every explorer as one batch of `pstack_subagent` calls, each with `references/explorer-prompt.md` and its angle filled in. Each call returns a child id and the report arrives as a completion notice, so nothing polls: move on once the notices are in.
 
 ## 3. Synthesize (complex only)
 
-Once all explorers have returned, spawn one explainer with `references/explainer-prompt.md` and every explorer's findings filled in.
+Once all explorers have returned, start one explainer child with `references/explainer-prompt.md` and every explorer's findings filled in. Starting it earlier drops whatever had not reported yet.
 
 ## 4. Present
 

package/assets/skills/how/references/explainer-prompt.md

@@ -20,7 +20,7 @@ The explorers each investigated a different angle of the same subsystem. Their f
 
 Write an explanation a senior engineer unfamiliar with this area could read and walk away with a solid mental model, understanding the architecture well enough to start working in it confidently.
 
-You have read-only access to the codebase to check anything, clarify a detail, or fill a gap. Use Read, `grep`, and `glob` as needed. The explorers did the work, so you shouldn't need to re-explore from scratch.
+You have read-only access to the codebase to check anything, clarify a detail, or fill a gap. Use Read, Grep, and Glob as needed. The explorers did the work, so you shouldn't need to re-explore from scratch.
 
 ## Output Format
 

package/assets/skills/in-your-own-words/SKILL.md

@@ -4,6 +4,4 @@ description: Restate in your own words what you think the user's goals are and w
 disable-model-invocation: true
 ---
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's `Task` tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
 Restate in your own words what you think the user's goals are and what problem they're trying to solve.

package/assets/skills/interrogate/SKILL.md

@@ -4,11 +4,11 @@ description: Use for "interrogate", "adversarial review", "multi-model review",
 disable-model-invocation: true
 ---
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's `Task` tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
 # Interrogate
 
-Spawn one reviewer per configured model to adversarially review code changes. The adversarial signal comes from model diversity, not assigned personas. The deliverable is a synthesized verdict. Do NOT auto-apply changes.
+> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+
+Spawn one reviewer per configured route to adversarially review code changes. The adversarial signal comes from model diversity, not assigned personas; when two entries resolve to the same route, say plainly that the review is one model reading the diff twice, because that is what it is. The deliverable is a synthesized verdict. Do NOT auto-apply changes.
 
 ## Step 1, Scope
 
@@ -26,15 +26,17 @@ Before spawning reviewers, state the intent in one clear paragraph from the user
 
 ## Step 3, Spawn Reviewers
 
-Launch all reviewers in a single message with `pstack_subagent`, one per entry on the `interrogate reviewers` line in `~/.dsh/pstack-models.md`, labeled Reviewer A, B, and so on to match the entry count. Pass `agent: "general"` and `role: "interrogate reviewers"`. If the file or line is missing, use the parent model and say so.
+Launch all reviewers in one batch of `pstack_subagent` calls with `role: "interrogate reviewers"`. That role is a panel, so one call starts one child per entry in the role file and the result lists every child id with its actual route; label them Reviewer A, B, and so on to match the entry count. A role the file does not name inherits the parent route, and that is not a different model.
+
+Each reviewer gets `agent: "general"` and a brief that forbids writes: it may read the diff and run read-only commands, and it must not edit files. That rule is an instruction, not a sandbox, so check `git status` before and after instead of trusting the report. The route comes from the panel entry, and the tool reports the route each reviewer actually got.
 
-Each reviewer gets `agent: "general"` and `role: "interrogate reviewers"`, and is told not to edit files. DSH routes each panel entry independently; an `inherit-parent` entry runs on the parent model. If a configured route is unavailable, run that reviewer on the parent model and say so. Do not block the review on the route issue.
+If an entry's route does not resolve, that reviewer does not start: the error names the role file and the bad line, which is the actionable fix. The remaining entries still start, and the report records each reviewer that was skipped and why. Do not substitute a route the user did not configure, and do not let one bad entry stop the review.
 
-Read `references/reviewer-prompt.md` and fill in the same template for every reviewer with the stated intent, the diff or file contents, the rubric from `references/rubric.md`, and the code-quality lens from `references/code-quality-review.md`. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill.
+Read `references/reviewer-prompt.md` and fill in the same template for every reviewer with the stated intent, the diff or file contents, the rubric from `references/rubric.md`, and the code-quality lens from `references/code-quality-review.md`. Read the Subagents section of the `poteto-mode` skill at its absolute resource path first. Start from the level the role line names, raise it for hard work and lower it for routine work by passing `reasoningEffort`; a child that cannot call `set_reasoning_effort` keeps the level you gave it.
 
 ## Step 4, Synthesize
 
-As results come back, build a unified picture. Parse every reviewer's findings. Merge findings that describe the same issue differently, and note which models raised each one. Findings two or more models raised independently are the highest signal. Read a lone model's finding, but weight it accordingly. Note disagreements. If one model flags something and another explicitly says the opposite, that is context for the verdict.
+As results come back, build a unified picture. Parse every reviewer's findings. Merge findings that describe the same issue differently, and note which route raised each one. Findings two or more reviewers raised are the highest signal only when their routes differ: reviewers on one route share the same blind spots, and the report says so instead of calling the overlap independent confirmation. Read a lone reviewer's finding, but weight it accordingly. Note disagreements. If one reviewer flags something and another explicitly says the opposite, that is context for the verdict.
 
 ## Step 5, Lead Judgment
 

package/assets/skills/interrogate/references/rubric.md

@@ -20,7 +20,7 @@ When you find a potential bug, trace the execution path. Don't just flag "this c
 
 Is the code fixing the actual problem or papering over a symptom?
 
-Answering this often requires looking beyond the changed files. Read the surrounding code (callers, callees, type definitions, sibling modules) and understand the architecture the change lives in. Use the tools available to you (Read, `grep`, `glob`) to follow the call chain, read the types, and understand why the code exists before judging whether the change addresses the right layer.
+Answering this often requires looking beyond the changed files. Read the surrounding code (callers, callees, type definitions, sibling modules) and understand the architecture the change lives in. Use the tools available to you (Read, Grep, Glob) to follow the call chain, read the types, and understand why the code exists before judging whether the change addresses the right layer.
 
 - Guard clauses that mask a deeper invariant violation
 - Retry logic that hides a broken contract

package/assets/skills/ketchup/SKILL.md

@@ -4,10 +4,10 @@ description: Catch the user up on what changed in this chat since their last mes
 disable-model-invocation: true
 ---
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's `Task` tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
 # Ketchup
 
+> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+
 Catch the user up on what changed in this chat since the last message they wrote before `/ketchup`, and help them understand each change, not only where it stands. Then lay out every call waiting on them so they can make it from your reply alone. Notifications and subagent results are not their messages. Assume the user remembers their last message and nothing after it.
 
 Use [`/bro`](../bro/SKILL.md)'s voice, not its task: plain words, short sentences, no jargon, like one person catching up another. Say what changed for the user, not how you did it. Say "the tests pass", not "CI is green". Leave out hashes, file paths, commands, build numbers, and test counts unless the user needs one to act. Call each PR, branch, or agent by a name the user would know, not by a label you invented. If a fact needs context to make sense, give the context or leave the fact out.
@@ -36,10 +36,10 @@ For a call between options, give every option the work weighed, each with what i
 
 ## Visuals
 
-A visual is a picture: a screenshot, a video, a Mermaid diagram, a chart or diagram from `/visualize`, or a generated image. A Markdown table is not a visual, even with before and after columns.
+A visual is a picture: a screenshot, a video, a Mermaid diagram, or a chart rendered by a real tool available in this Session. There is no `/visualize` command here and no built-in image generator. A Markdown table is not a visual, even with before and after columns.
 
 When something is easier to grasp as a picture than as sentences, draw it: how a design or system works, a PR stack or dependency chain with each PR's state, a before and after of a fix, or options side by side. Never draw a status list, a list of action items, or boxes with nothing connecting them. Never give a fact twice, in text or across visuals.
 
 Keep each visual small enough to read at a glance: at most six boxes, with at most eight words in each. Write labels as plain words a person would say, not tags like "Tests: pass". A fact that needs a sentence belongs in the text, or nowhere.
 
-Embed screenshots and videos inline when the change is visible, not only as links. If a visible change has none, mark its summary line "No screenshot yet," and say there what changed on screen. Draw diagrams and charts from facts you have: a Mermaid diagram for how things connect and a `/visualize` chart for numbers. Never invent a number, and never draw or generate a picture of a screen you did not capture. Link only artifacts that exist.
+Embed screenshots and videos inline when the change is visible, not only as links. If a visible change has none, mark its summary line "No screenshot yet," and say there what changed on screen. Draw diagrams and charts from facts you have: a Mermaid diagram for how things connect, and a real available renderer for a numeric chart. Never invent a number, and never draw or generate a picture of a screen you did not capture. Link only artifacts that exist.

package/assets/skills/maintain-formal-verification-skill/SKILL.md

@@ -4,10 +4,10 @@ description: "Bring a project's formal verification back in line with the code a
 disable-model-invocation: true
 ---
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's `Task` tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
 # Maintain a formal verification skill
 
+> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+
 A formal check proves a property of what it describes. When the code changes and the verification does not, the check can keep passing while it describes code that no longer exists. That pass is the dangerous case, because it looks like a proof. This skill is the upkeep loop for a verify skill that `/create-formal-verification-skill` generated, or for any project-local skill that runs a model checker, prover, or code-level verifier against named code. The project-local skill handles a change that an agent makes while it uses that skill. This skill handles the changes that skipped it: merges, edits made without the skill, and drift that builds up across many commits.
 
 ## Outcomes

package/assets/skills/maintain-verification-skill/SKILL.md

@@ -4,10 +4,10 @@ description: "Periodic pass that keeps a project's verification skill and featur
 disable-model-invocation: true
 ---
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's `Task` tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
 # Maintain a verification skill
 
+> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+
 A feature map rots the moment the app changes. This skill is the upkeep loop for a skill generated by `/create-verification-skill` (or any project-local verification skill with a feature map). The unit of rigor is the feature, not every sentence: cover every feature file from source and exercise every feature live, without terminalising every bullet.
 
 ## Outcomes
@@ -28,7 +28,7 @@ Only edit the verification skill's own directory (its SKILL.md, features/, and a
 
 1. **Index hygiene.** Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.
 
-2. **Source wave.** One read-only subagent per feature file, launched concurrently. Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Children never drive the app and never edit files. Return shape: feature summary / source entry points / likely drift or none / one recipe.
+2. **Source wave.** One read-only `pstack_subagent` per feature file, launched concurrently. The brief carries the no-write rule and the feature path. That rule is instruction, not a sandbox, so check what each child reports instead of assuming it. Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Children never drive the app and never edit files. Return shape: feature summary / source entry points / likely drift or none / one recipe.
 
 3. **Reconcile.** Every feature file has a returned summary. Merge overlapping recipes into as few app states as practical. Spot-check cited drift; don't re-prove clean claims. Sweep recent churn for user-facing surfaces missing from the map — require a concrete source path before calling one missing.
 

package/assets/skills/no-comments/SKILL.md

@@ -4,10 +4,10 @@ description: Spawn Comment Sicko, fix accepted findings, and offer encodings for
 disable-model-invocation: true
 ---
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's `Task` tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
 # No comments
 
+> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+
 Spawn Comment Sicko. Act on accepted findings.
 
 Defer to Comment Sicko's fresh perspective.
@@ -18,9 +18,9 @@ Use the caller's files or diff. Otherwise use the current diff against the base
 
 ## Steps
 
-1. Spawn `pstack_subagent` with `agent: "comment-sicko"`. Pass the scope. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill. Do not restate its rules.
-2. Inspect its report and diff. Reject application-code edits, scope escapes, exception-protected deletions, misstated `MUST KILL` reasons, and flags that treat kept intentional code as guilty. Reshape flags on our-code surprises stay actionable. Do not restore those comments. A keep survives only with proof it is about something we cannot change. Audit missed scoped lint and TypeScript suppressions. Correctness or safety suppressions stay actionable `MUST KILL`s. Restore deletions only with exact exceptions and scoped proof. Before accepting thin `IMPORTANT` or `do not remove` kills or keeps, run `/how` or `/why` on their symbol. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report with the failure named. Reject a second, report it open, and fail `/no-comments`.
-3. Fix trivial accepted flags directly by deleting a dead path, dropping a parameter, or using the real API. If any fix needs a shape, run `/architect` once for the accepted set and surrounding code. Stop at the sketch. Architect shapes. Step 4 implements.
-4. Implement the smallest root-cause fix in scope. Remove every named workaround. If the root cause is out of scope, land the smallest in-scope fix and report the rest open. The **principle-fix-root-causes** and **principle-redesign-from-first-principles** skills guide intent only. Neither authorizes widening the fence nor fixing instances outside it. Never bolt on symptom guards.
-5. Constraint comments say `do not remove`, `do not change wording`, or `talk to X before changing`. Leave keeps about things we cannot change. Offer the cheapest in-scope type, runtime, test, or CI lint. Wait for interactive approval. Unattended and eval require caller pre-approval. If approved, encode then delete. Otherwise delete, report the constraint open, and sketch out-of-scope work.
+1. Call `pstack_subagent` with `agent: "comment-sicko"` and the scope in the brief. That agent type is the only way to get Comment Sicko's persona, because the Host injects its preamble; a `general` child would lose it, and a missing preamble stops the call instead of degrading. Read the Subagents section of the `poteto-mode` skill at its absolute resource path first. Do not restate its rules. Start from the level the role line names, raise it for hard work and lower it for routine work by passing `reasoningEffort`; a child that cannot call `set_reasoning_effort` keeps the level you gave it.
+2. Inspect its report and diff. Reject application-code edits, scope escapes, exception-protected deletions, misstated `MUST KILL` reasons, and flags that treat kept intentional code as guilty. Reshape flags on our-code surprises stay actionable. Do not restore those comments. A keep survives only with proof it is about something we cannot change. Audit missed scoped lint and TypeScript suppressions. Correctness or safety suppressions stay actionable `MUST KILL`s. Restore deletions only with exact exceptions and scoped proof. Before accepting thin `IMPORTANT` or `do not remove` kills or keeps, read the `how` or `why` skill's `SKILL.md` at its absolute resource path and run it on their symbol. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report with the failure named. Reject a second, report it open, and fail this skill with the reason.
+3. Fix trivial accepted flags directly by deleting a dead path, dropping a parameter, or using the real API. If any fix needs a shape, read the `architect` skill's `SKILL.md` at its absolute resource path and run it once for the accepted set and surrounding code. Stop at the sketch. Architect shapes. Step 4 implements.
+4. Implement the smallest root-cause fix in scope. Remove every named workaround. If the root cause is out of scope, land the smallest in-scope fix and report the rest open. `principle-fix-root-causes` and `principle-redesign-from-first-principles` guide intent only; read either `SKILL.md` at its absolute resource path. Neither authorizes widening the fence nor fixing instances outside it. Never bolt on symptom guards.
+5. Constraint comments say `do not remove`, `do not change wording`, or `talk to X before changing`. Leave keeps about things we cannot change. Offer the cheapest in-scope type, runtime, test, or CI lint. Ask through `ask_user_question` and wait for the answer. An unattended run and the eval playbook need the caller's approval up front, because nobody can answer. If approved, encode then delete. Otherwise delete, report the constraint open, and sketch out-of-scope work.
 6. Report the deletion count, restored comments, reruns, architect sketch, fixes, encoding offers, encodings, unenforced constraints, and other open work.

package/assets/skills/poteto-help/SKILL.md

@@ -4,15 +4,15 @@ description: Guides users through pstack setup, /poteto-mode, and picking the sk
 disable-model-invocation: true
 ---
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's `Task` tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
 # Poteto help
 
+> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+
 Answer the user's question about pstack, hand them a prompt they can send, and link the file the answer came from. For a help question, don't start the work. The user asked how, and a pstack run spends real tokens, so let them send the prompt.
 
-A message that asks for work, such as "use pstack to fix this bug", is not a help question. Read [`poteto-mode`](../poteto-mode/SKILL.md), do the work under it, and mention once that there is no persistent mode in DSH.
+A message that asks for work, such as "use pstack to fix this bug", is not a help question. Read [`poteto-mode`](../poteto-mode/SKILL.md), do the work under it, and mention once that each new task has to start with `/poteto-mode` again.
 
-This file maps questions to the skills and guide pages that hold the answers. Those files own the details. Read the file you route to before you quote it, and trust it when it disagrees with this map. The links here point into the installed plugin, which the user may not be able to open, so give the user the file's public copy: `https://github.com/cursor/plugins/blob/main/pstack/` followed by its path.
+This file maps questions to the skills and guide pages that hold the answers. Those files own the details. Read the file you route to before you quote it, and trust it when it disagrees with this map. The links here are relative paths inside this package, so give the user the path itself and say when a page describes upstream behavior this port has not implemented.
 
 ## Find out what they need
 
@@ -26,39 +26,38 @@ Infer the need from the message and the conversation. A named situation, such as
 
 Check the state that changes the answer, and mention it only when it does:
 
-- No `~/.dsh/pstack-models.md` means `/setup-pstack` hasn't run for this user, so every role uses its default model.
+- No `$DSH_HOME/pstack-models.md` means `/setup-pstack` hasn't run for this user, so every role inherits the parent route.
 - No `verify-*` skill or other app harness in the project means agents have no scripted way to drive the app. Mention `/create-verification-skill` when the question is about proving a change works.
 - No formal verification skill in the project means no property is checked past what tests reach. Mention `/create-formal-verification-skill` when the question is about a race, an invariant, or another case tests rarely hit. When one exists and the code it covers changed after the commit it records as last in sync, mention `/maintain-formal-verification-skill` if the question touches that code.
 
-When the model rule is missing and it matters, ask whether the user wants to pick a model for each role and a reasoning budget now. It matters when the user is new, the question is about setup or cost, or the answer depends on which models run. Ask at most once per chat. If the need is also unclear, ask both questions together. Offer two choices:
+When the role file is missing and it matters, ask whether the user wants to pick a route for each role and a reasoning budget now. It matters when the user is new, the question is about setup or cost, or the answer depends on which models run. Ask at most once per chat. If the need is also unclear, ask both questions together. Offer two choices:
 
 - Now: give them `/setup-pstack` to type, and answer their question too.
-- Later: answer their question, and add one line saying every role keeps its default model until they run `/setup-pstack`.
+- Later: answer their question, and add one line saying every role keeps inheriting the parent route until they run `/setup-pstack`.
 
 ## Get set up
 
-1. Install with `/add-plugin pstack` in chat, or from Customize in the sidebar.
-2. Run [`/setup-pstack`](../setup-pstack/SKILL.md). It asks for a reasoning budget, maps a model to each role, and writes a rule. The rule applies to new chats. Then it offers once each to generate a verification skill and a formal verification skill for the project, unless the project already has one.
+1. Install the bundle into the profile you use: `dsh plugin --profile <profile> add dsh-pstack`, then enable the bundle when DSH asks, and start a new Session if it says the change needs one.
+2. Run [`/setup-pstack`](../setup-pstack/SKILL.md). It asks for a reasoning budget, maps a route to each role, and writes `$DSH_HOME/pstack-models.md`. That file applies from the next delegation on, because `pstack_subagent` re-reads it every time. It then offers once each to generate a verification skill and a formal verification skill for the project, unless the project already has one; both generators ship in this package.
 3. Start a real task with `/poteto-mode`, a goal, and a check that can pass or fail.
 
-Installing changes nothing until the user invokes a skill. Only `/setup-pstack` loads from the user's words. The [README](../../README.md) and [guide page 1](../../docs/guide/01-setup.md) have the details. Offer to word their first prompt with them, per [`references/prompting.md`](references/prompting.md).
+Enabling the bundle adds the skill catalog and the `pstack_subagent` tool; nothing runs until the user invokes a skill. Only `/setup-pstack` loads from the user's words. The [README](../../../README.md) and [guide page 1](../../docs/guide/01-setup.md) have the details. Offer to word their first prompt with them, per [`references/prompting.md`](references/prompting.md).
 
-If cost is the worry, say where the tokens go and how to spend fewer. pstack spends extra tokens on subagents and review panels. Rerun `/setup-pstack` and pick a smaller budget or cheaper models. A role set to `auto` or `inherit-parent` runs on the chat's model, which saves tokens when the chat runs on Auto or a cheaper model. A shorter panel list runs fewer subagents, one for each entry. Save `/poteto-mode` for work that needs rigor.
+If cost is the worry, say where the tokens go and how to spend fewer. pstack spends extra tokens on subagents and review panels. Rerun `/setup-pstack` and pick a smaller budget or cheaper models. A role set to `inherit-parent` or `auto` runs on the parent route, so it spends nothing extra on a second model. A shorter panel list runs fewer subagents, one for each entry. Save `/poteto-mode` for work that needs rigor.
 
-pstack runs inside DeepSeek Harness as the `dsh-pstack` bundle. Every skill is user-invocable with `/name`, and `/poteto-mode` delegates through `pstack_subagent`.
+This tree is the DSH build of pstack. The [DSH harness mapping](../../docs/harness/dsh.md) maps the Cursor names onto this host, and a step that needs a capability this port does not have is reported at the step that needs it, not silently skipped.
 
-DSH reads the same Agent Skills format. Workflow skills delegate through `pstack_subagent`, so per-role routes come from `~/.dsh/pstack-models.md` instead of Cursor model slugs.
+Every workflow skill here runs through this package's bundled skill provider, and the skills that delegate start `pstack_subagent` children whose routes come from `$DSH_HOME/pstack-models.md`. There is no Custom Mode and no loop command to type: start each task with `/poteto-mode`, register a long run as a goal with `create_goal`, and treat a multi-hour run as something you supervise in the same Session unless the goal round driver is mounted.
 
 ## Start a task with `/poteto-mode`
 
 `/poteto-mode` matches the task to a playbook, copies the playbook's steps into the todo list, and runs the other skills as the steps need them. A step it skips stays in the list as `skip: <reason>`. A good prompt states the goal and how to tell it's done. It doesn't list skills, because a hand-written sequence tends to drop or reorder steps the playbook would keep. Read [`references/prompting.md`](references/prompting.md) before you help word one. [Guide page 2](../../docs/guide/02-poteto-mode.md) has examples.
 
-Whether `/poteto-mode` stays on depends on how the user starts it:
+`/poteto-mode` has no persistent mode in this host, so every new task starts by invoking it again:
 
-- Enter on `/poteto-mode` attaches the skill to one message. It fades as the chat moves on.
-- DSH has no persistent mode. Start each new task with `/poteto-mode`.
-
-DSH skills are documented at `https://deepseek-harness.github.io/deepseek-harness/`. Mid-chat, "new task" makes the mode match a fresh playbook. `/poteto-mode` already uses `poteto-agent` for the subagents its playbook steps spawn. To get the same style from a subagent of your own, spawn it with `agent: "poteto-agent"`.
+- Invoking `/poteto-mode` attaches the skill to the current task. A later task does not inherit it.
+- There is no Custom Mode and no keyboard shortcut that keeps it on, because this host has neither. Start each task with `/poteto-mode`.
+- A subagent of your own gets the orchestration style only as a `pstack_subagent` child with `agent: "poteto-agent"`, because the tool injects that preamble; `agent: "general"` does not.
 
 ## Pick a skill
 
@@ -77,7 +76,7 @@ The default answer is `/poteto-mode`, which runs most of the others when its ste
 | Know what a small diff could break outside itself | [`/blast-radius`](../blast-radius/SKILL.md) |
 | Settle types and module shape before code that crosses a function boundary | [`/architect`](../architect/SKILL.md) |
 | Get several attempts at one brief, merged into the best one | [`/arena`](../arena/SKILL.md) |
-| Run parallel checks over slices, or race workers, as worktree subagents | [`/swarm`](../swarm/SKILL.md) |
+| Run parallel checks over slices, or race workers, as local child Sessions | [`/swarm`](../swarm/SKILL.md) |
 | Have different models review a diff and try to break it | [`/interrogate`](../interrogate/SKILL.md) |
 | Fix a bug test-first when a cheap local test exists | [`/tdd`](../tdd/SKILL.md) |
 | Apply TypeScript rules to `.ts` or `.tsx` work | [`/typescript-best-practices`](../typescript-best-practices/SKILL.md) |
@@ -100,6 +99,8 @@ The default answer is `/poteto-mode`, which runs most of the others when its ste
 
 If a skill directory next to this one is missing from the table, read its frontmatter and route by its description. The `principle-*` directories are covered under principles below.
 
+`/recall`, `/reflect`, `/automate-me`, `/show-me-your-work`, the Eval playbook, Session pickup, and Worktree cleanup all ship, and they read session history through `pstack_history`. A live read of the calling session or a direct child is delivered; a cold read whose events cannot be attributed to the stored log reports the audit unfinished. Those flows have not been verified end to end on a real session yet. The long-running playbooks ship as ported text as well, and each one states the gate it cannot pass on this host.
+
 Close calls:
 
 - `/how` explains what the code does. `/why` explains the reasons. `/teach` runs one or both and explains the result plainly.
@@ -111,9 +112,9 @@ Close calls:
 
 Not in pstack:
 
-- The pre-commit cleanup and the verification skills are not shipped in DSH; use `/no-comments` and the project verification skill instead.
-- DSH has no loop command; use `schedule_create` and `create_goal` for long runs. Skill authoring is the authoring-a-skill playbook.
-- pstack has no `/orchestrate` skill. Orchestrate is a `/poteto-mode` playbook. If the slash menu shows `/orchestrate`, another plugin provides it.
+- No slop-strip or surface-control plugin ships here. Read the staged diff once yourself before a commit, and use a project verification skill, or a driver the repo already has, before you call a surface verified.
+- There is no loop command and no skill-drafting built-in. A long run is a goal (`create_goal`), a heartbeat reminder where a timed input fits, and a decision trail; skill authoring goes through the authoring playbook.
+- pstack has no `/orchestrate` skill. Orchestrate is a `/poteto-mode` playbook. The playbook is ported: its `.audit` store, `orch` CLI, depth-2 delegation, and inbox discipline are shipped text, while its cloud restart and cloud liveness steps are explicitly unsupported. None of it has been verified end to end.
 
 ## Playbooks and principles
 
@@ -126,9 +127,9 @@ Playbooks are step lists inside `/poteto-mode`, not skills, so they have no slas
 - "full autopilot on this queue" runs Autopilot-full. "stack them, don't ship" runs Autopilot-stack.
 - "run the eval playbook" runs Eval.
 
-DSH does not ship a competing babysit skill, so `/poteto-mode` owns these phrases. The Playbooks section of [`poteto-mode`](../poteto-mode/SKILL.md) lists every playbook and when it applies. [Guide page 6](../../docs/guide/06-verify-and-ship.md) covers opening, babysitting, and landing a PR.
+Every playbook in the Playbooks section of [`poteto-mode`](../poteto-mode/SKILL.md) is ported to this harness: all 23 files ship as text, and each one that depends on a capability this host lacks states that gate at the step that needs it. Babysit needs a watcher that can wake the Session before `drive` or `background` means anything, Shipping needs a real driver for the surface, Orchestrate needs `pstack_script` for scripted bookkeeping but permits a disclosed manual-file fallback when the tool is unavailable, Hillclimb accepts no win without a working measurement harness, and Visual parity needs an image diff actually run before it can claim parity. None of those flows has been verified end to end. [Guide page 6](../../docs/guide/06-verify-and-ship.md) covers opening, babysitting, and landing a PR.
 
-pstack has no planning skill. DSH plan mode works alongside it. For work that spans phases or stacked PRs, asking `/poteto-mode` for a plan runs the [Multi-phase plan playbook](../poteto-mode/playbooks/multi-phase-plan.md), which writes the plan and doesn't implement it. For a design question, the Prototype playbook or `/architect` settles it in code first.
+pstack has no planning skill. Cursor's Plan Mode works alongside it. For work that spans phases or stacked PRs, asking `/poteto-mode` for a plan runs the [Multi-phase plan playbook](../poteto-mode/playbooks/multi-phase-plan.md), which writes the plan and doesn't implement it. For a design question, the Prototype playbook or `/architect` settles it in code first.
 
 Principles are one-rule skills that `/poteto-mode` reads and cites in its replies. The user rarely invokes one. They steer with the names instead, as in "apply prove it works. show me the real output." Typing `/principle-<name>` still loads one on demand. [Guide page 8](../../docs/guide/08-principles.md) lists them.
 
@@ -136,22 +137,22 @@ Principles are one-rule skills that `/poteto-mode` reads and cites in its replie
 
 | Symptom | Fix |
 |---|---|
-| The mode stopped applying after a few turns | DSH has no persistent mode. Start each new task with `/poteto-mode`. |
+| The mode stopped applying after a few turns | Nothing keeps it on here: a skill attaches to the task that invoked it. Start each task with `/poteto-mode`. |
 | A question got treated as the next step of the last task | Say "new task", or say the turn doesn't need the mode. |
-| A new model choice had no effect | The rule from `/setup-pstack` applies to new chats. Start one. |
+| A new model choice had no effect | The file from `/setup-pstack` applies to the next delegation. A child that already started keeps the route it started with. |
 | Runs cost more than expected | See the cost paragraph under Get set up. |
 | A skill didn't load on its own | Only `/setup-pstack` loads from the user's words. The others load when the user types them or when `/poteto-mode` runs them, and it doesn't run every skill. |
-| Parallel agents overwrote each other | Give each agent its own worktree, or run them as worktree subagents, which each get their own machine. |
-| An overnight run moved but finished nothing | a wake mechanism needs a check that can pass or fail, not a duration. See [guide page 7](../../docs/guide/07-overnight.md). |
+| Parallel agents overwrote each other | Give each writer its own `create_worktree` checkout and pass its absolute path as that child's `cwd`. There is no cloud machine, and a shared checkout is not isolation. |
+| An overnight run moved but finished nothing | The run needs a check that can pass or fail, not a duration. Give the run a goal with a checkable predicate and, at most, a heartbeat reminder; automatic rounds need the goal round driver mounted, so otherwise the run is a supervised Session. See [guide page 7](../../docs/guide/07-overnight.md). |
 | The reply claims success from a green build | Ask for the real command, flow, stored value, or profile. That's the prove-it-works principle. |
 
 For a run that drifts, [`references/prompting.md`](references/prompting.md) has one-line steers. [Guide page 10](../../docs/guide/10-recipes-and-pitfalls.md) has more pitfalls and the recipes worth copying.
 
 ## Make pstack my own
 
-- [`/automate-me`](../automate-me/SKILL.md) drafts a personal mode skill from the user's own history, to use alongside `/poteto-mode`.
-- [`/reflect`](../reflect/SKILL.md) after a session turns its lessons into skill edits the user approves.
-- `/poteto-mode write a skill for <workflow>` runs the authoring playbook. The eval playbook tests a skill change blind.
+- [`/automate-me`](../automate-me/SKILL.md) drafts a personal mode skill from the user's own history through `pstack_history`, to use alongside `/poteto-mode`.
+- [`/reflect`](../reflect/SKILL.md) after a session turns its lessons into skill edits the user approves, auditing the run from its raw event log.
+- `/poteto-mode write a skill for <workflow>` runs the authoring playbook, which is ported; validate the result with this package's asset check, because there is no built-in drafting or evaluation tool. The eval playbook tests a skill change blind and checks file reads in the candidate's own events. Those history-backed audits are not yet verified end to end on a real session.
 - Fix a misbehaving skill in its own PR, not inside the feature work where it went wrong.
 
 [Guide page 9](../../docs/guide/09-make-it-yours.md) covers each of these.

package/assets/skills/poteto-help/references/prompting.md

@@ -38,7 +38,7 @@ A prompt states the intent and the check for done. The playbook supplies the ste
 ## Before stepping away
 
 - Say "im going to bed" or "im stepping away" so the agent stops asking.
-- Write done as checks every iteration can run, and give the wake prompt that predicate.
+- Write done as checks every iteration can run, and register that predicate as a goal so a long run has something to converge on.
 - Ask for a fresh worktree off a named base.
 - Pre-answer what the agent would stop for, such as "don't ask me before committing".
 - Ask for a decision log to audit later.

package/assets/skills/poteto-help/references/recipes.md

@@ -42,7 +42,7 @@ Swap in the real paths, skills, and done checks. Informal wording works.
 
 ## Away and back
 
-- `/poteto-mode im going to bed. <goal> in a fresh worktree off <base>. done means <checks>. keep a decision log. don't ask me before committing. Arm a `schedule_create` heartbeat for the finish condition. if you're truly stuck after a few hours, stop and write up why.`
+- `/poteto-mode im going to bed. <goal> in a fresh worktree off <base>. done means <checks>. keep a decision log. don't ask me before committing. register the predicate as a goal and keep going until it holds. if you're truly stuck after a few hours, stop and write up why.`
 - `/show-me-your-work catch me up on what you did last night.` Read its Attention section first.
 - `/ketchup` catches you up on this chat since your last message and lists every call that waits on you.
 - `/poteto-mode full autopilot on this queue. each item is independent.`