dsh-super-code 0.3.11 → 0.4.0

package/builtin/skills/pstack/dsh/skills/how/references/explorer-prompt.md

@@ -0,0 +1,35 @@
+# Explorer Prompt Template
+
+Build each explorer subagent's prompt from this template. Fill in the placeholders.
+
+---
+
+Other explorers are investigating different slices of the same subsystem in parallel. Don't try to cover everything. Focus on your assigned angle and go deep.
+
+## Question
+
+> {QUESTION}
+
+## Your Exploration Angle
+
+{EXPLORATION_ANGLE}
+
+## Output
+
+### Components Found
+The key types, services, classes, and abstractions. For each: name, file path, and a one-sentence description of what it does.
+
+### Flow
+The execution flow step by step. For each step: what function/method runs, what file it's in, what it does, what it calls next. Include the data that flows between steps.
+
+### Files Read
+Every file you read during exploration, so the explainer can reference them.
+
+### Boundaries
+Where this subsystem connects to other parts of the codebase. The inputs and outputs.
+
+### Non-Obvious Things
+Anything surprising, historically motivated, or easy to get wrong. Things that look like they should work one way but work another.
+
+### Open Questions
+Anything you couldn't fully trace or understand. Be honest about gaps.

package/builtin/skills/pstack/dsh/skills/in-your-own-words/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: in-your-own-words
+description: "Restate in your own words what you think the user's goals are and what problem they're trying to solve. Use for /in-your-own-words."
+disable-model-invocation: true
+---
+
+Read [DSH host operations](../../DSH.md) once before executing this workflow.
+
+
+Restate in your own words what you think the user's goals are and what problem they're trying to solve.

package/builtin/skills/pstack/dsh/skills/interrogate/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: interrogate
+description: "Use for \"interrogate\", \"adversarial review\", \"multi-model review\", \"challenge this\", \"stress test this code\", \"find blind spots\", or \"tear this apart\". Adversaries try to break a change or design, and only findings proven by a run survive."
+disable-model-invocation: true
+---
+
+Read [DSH host operations](../../DSH.md) once before executing this workflow.
+
+
+# Interrogate
+
+Adversaries try to break a change or a design. A finding survives only when a run proves it. Report the findings. Do not apply fixes.
+
+## Frame
+
+The scope is what the user names. Otherwise it is the branch diff from its merge base with the base branch, through the working tree. State the intent with the **in-your-own-words** skill, from the user's message, the commits, and the PR description. Ask the user when the intent is unclear.
+
+## Fan out
+
+Run Phase A steps 3 and 4 and Phase B of the **arena** skill, with four changes. Read the `interrogate reviewers` line in place of `arena runners`. Copy the scope's uncommitted changes into each worktree. Spawn each adversary with a self-contained DSH review brief. In place of the arena task and rationale, give each adversary the scope, the intent, and this brief:
+
+> Break this change. Prove each finding with a run against the real code, such as a failing test, a repro script, or command output that shows the wrong behavior. For a design or plan, run a prototype or probe the current tree. Keep repros in your own worktree. Report each finding with a title, the exact command, the output it printed, and the output the intent requires. Leave out anything you did not run. That covers style, naming, structure, and risks that need a future change to matter. No findings is a valid result.
+
+## Verify
+
+Verify each finding per arena Phase F by rerunning its command. Keep a finding when the output shows the failure and the failure breaks the intent. Drop the rest. Merge findings that share a root cause.
+
+Skip arena Phases C, D, and E. Adversaries find different failures, so the verdict keeps every verified finding, not one adversary's list.
+
+## Output
+
+- **Intent**: the restatement.
+- **Findings**: for each verified finding, the command, its output, how it breaks the intent, and the adversaries that found it. Say "no verified findings" when none survive.
+- **Dropped**: for each adversary, the count of dropped findings and why.

package/builtin/skills/pstack/dsh/skills/ketchup/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ketchup
+description: "Catch the user up on what changed in this chat since their last message, in plain words and small visuals. List every item waiting on them with what they need to decide it from the reply alone. Use for /ketchup."
+disable-model-invocation: true
+---
+
+Read [DSH host operations](../../DSH.md) once before executing this workflow.
+
+
+# Ketchup
+
+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.
+
+## Gather what changed
+
+Keep this turn read-only. Make visuals only from what you already have: do not change code, start an app or a job, or post anything. Collect your own work since that message, reports from subagents, and messages from anyone else in this chat. Check the current state of each PR, CI run, or agent this chat touched. Check each number you will show against the facts it comes from, and say so when you correct one.
+
+An action item is a call or step only the user can take, such as a product choice, an approval, an irreversible action, or access you lack. Include any still waiting on the user, even one raised before their last message. Work you can still do yourself is not an action item. Never make up a call to fill the reply. A step the user did not ask for and the work does not need is not an action item, unless it is irreversible and waiting on the user: give it one line and no visual.
+
+One call can cover many items, such as each PR in a set awaiting merge. For each item, collect its link, what it changes for users, the evidence behind your pick, its risk, and your pick. Write "unknown" for a fact the call needs that you do not know. Leave out a link you do not have.
+
+## Write the reply
+
+Spend words on the calls, not on the story. Keep what happened under 100 words, not counting pictures, and shorter when less happened. Leave out work that changed nothing for the user. Give each item about 30 words. The reply grows with the number of items: two items need well under 150 words in all, not counting pictures, and thirty need far more. Never cut items or shrink them to stay under a word count: no count in place of a list, and no link in place of an item. A link can add depth, but the reply alone must be enough to decide.
+
+Open with one short sentence that names what waits on the user, or says nothing does. The action items give the detail. If nothing happened and nothing waits on the user, say so and stop.
+
+Then show what happened, pictures first. Embed inline the screenshots and videos the work produced, then any diagram that explains a change. Then sum up in one short bullet per thing the user asked for: what came of it, and whether it is done, still running, failed, or not checked. Write each line the way you would say it out loud: "Search was slow from a missing index", not "Search review: done" or "Slow search: missing index". Name any bug found and fixed on the way. Each line must stay true when read alone. Never mark something done that still waits on the user, and leave out anything the action items say. Under the summary, give at most three short lines that change what the user knows or must do. Then name in one line any work left that you can do yourself.
+
+Then list the action items. Ask the call the user owns, such as merge, approve, or pick, and give your pick. A step you would take first goes in your pick. So does anything that must happen first, and anything that cannot be undone. Give the number or link of each PR, issue, or agent a call is about, also in a call between options.
+
+Fit the shape to the call. A call about one item is one bullet: the call, your pick, what it changes for users, the evidence behind your pick, and its risk, with the item named once. When items share a call, write the call and your pick once, then give each item its own bullet, riskiest first: its link and name, what it changes for users, the evidence behind your pick, and its risk. Name an item's pick only where it differs from the call's. Give each item's risk even when it is low, such as "Low risk: only the colors change." Say what waiting costs only when it is more than a delay, such as a deadline or lost data.
+
+For a call between options, give every option the work weighed, each with what it gets the user and what it costs, and the current state when there is one. Those costs are the call's risk, so add no separate risk line. When the screenshots above show the options, write each option's gain and cost under its screenshot.
+
+## 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.
+
+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.

package/builtin/skills/pstack/dsh/skills/ketchup-video/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: ketchup-video
+description: "Catch the user up like /ketchup, with a short subtitled video of slides for what happened and the waiting calls as text under it. Use for /ketchup-video."
+disable-model-invocation: true
+---
+
+Read [DSH host operations](../../DSH.md) once before executing this workflow.
+
+
+# Ketchup video
+
+Follow [`/ketchup`](../ketchup/SKILL.md), but show what happened in a short subtitled video instead of its summary and visuals. Its window starts at the last message the user wrote before `/ketchup-video`, not before any earlier `/ketchup`. Writing and rendering the video in task-owned media/scratch paths is the one exception to its read-only rule. Leave source files unchanged; keep renderer/encoder process handles and stop only those owned processes. Use recoverable cleanup for generated frames, or retain them when it is unavailable. The reply is ketchup's opening sentence, the embedded video, one line naming any work left that you can do yourself, and the action items. When the video shows a call's options, call each option by the name the video gives it. If the render fails, say so in one line and give only the calls.
+
+## Slides
+
+Use the screenshots, recordings, diffs, and data the work produced, not the chat's prose about them. Before you draw, write the one sentence the user should leave with and one line per slide. Drop each slide that does not change what the user knows. Use at most 10 slides, and fewer is better. Neither note goes in the reply.
+
+Each slide makes one point. Build the slides on one picture and change it from slide to slide, rather than cut to an unrelated one. A color or shape means the same thing on every slide. Show the work in pictures, such as how a system works, a PR stack with each PR's state, a before and after of a fix, or options side by side. Point at what changed with arrows, highlights, and motion. A slide is never a bullet list, a status list, a table, or boxes with nothing connecting them.
+
+Keep text to the minimum. Put each label on the thing it names, in plain words a person would say, not tags like "Tests: pass". Never caption what a picture shows, and never give a fact twice, across slides or in the text under them.
+
+Show what came of each thing the user asked for, and whether it is done, still running, failed, or not checked. Never show something done that still waits on the user. Show any bug found and fixed on the way. If a visible change has no screenshot, say so on its slide and name what changed on screen. Draw only from facts you have. Never invent a number, and never draw a screen you did not capture.
+
+## Subtitles
+
+Give each slide one short subtitle line, about ten words, that says its point the way you would tell the user, from only what that slide shows. Say what the picture means rather than read out its labels. Put the subtitle in a strip below the slide, the same height on every slide and empty except for the subtitle, so it never covers the slide. Set it small, but readable when the video plays at chat size.
+
+## Render
+
+Render one silent landscape video, such as an mp4, with motion between slides. Every frame is the slide itself, edge to edge, above its subtitle strip. Make the frames from the slides, never by recording a screen, and burn each subtitle into its slide's frames so it stays on screen for the slide's whole hold. The hold is the time a slide is fully on screen, not counting the motion into or out of it. Hold each slide long enough to read the words it adds, at least one second for each three words. A slide adds its subtitle and each word that was not on the slide before it, including a label it changes. The first slide adds all its words. Words inside a screenshot do not count.
+
+Before you embed the video, check the rendered file. Look at one frame from each slide at chat size, and check that its subtitle is readable and covers nothing. Measure each hold by matching the file's frames to the slide, not with a still-frame detector, which counts the faint ends of a fade as still. Count the words each slide adds against its measured hold. Fix any slide you cannot read in that time, render again, and check again.

package/builtin/skills/pstack/dsh/skills/maintain-formal-verification-skill/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: maintain-formal-verification-skill
+description: "Bring a project's formal verification back in line with the code after the code changes: find the commits that touched verified code, update the model, harness, or properties to describe the code as it is now, rerun, and say whether each failure is drift in the verification or a bug in the code. Use for /maintain-formal-verification-skill, \"is the model still true to the code\", or after merges and refactors that touched verified code without rechecking it."
+disable-model-invocation: true
+---
+
+Read [DSH host operations](../../DSH.md) once before executing this workflow.
+
+
+# Maintain a formal verification skill
+
+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
+
+Give each check one outcome, and say which:
+
+- **in sync**: no change since the last sync alters what the check describes, and the check passes.
+- **updated**: the code changed, the verification now describes the new code, and the check passes.
+- **bug**: the verification describes the current code, and the code breaks the property. This is a finding about the code. It is not drift.
+- **blocked**: the check could not be brought back in line or could not run. Say exactly why.
+
+A check can be both updated and bug: the update makes the verification describe the code again, and then the property fails on it.
+
+## Edit scope
+
+Edit only the verification: models, harnesses, property files, and the verify skill itself. Never edit product code during a run, unless the user asks you to. When a property fails on the current code, do not weaken the property or the model to make it pass. Report the failure.
+
+## Pass
+
+1. **Find the checks.** A verify skill has no fixed name, so find it by what it does: a project skill that runs a model checker, a prover, or another verifier against named code. Read each one you find, or the one the user named. For each check, collect the property, the code it covers, the bounds and assumptions, the command that runs it, and the commit where it was last confirmed to describe the code. If no verify skill exists, stop and point at `/create-formal-verification-skill`. If the skill does not record a sync commit, use the last commit that changed the verification files, and say that you did.
+
+2. **Run it as it is.** Run each check once before you change anything, and record the result. A pass here does not tell you that the code is correct. It tells you that the old description still holds. A failure here can be drift or a bug. Do not decide which until step 5.
+
+3. **Read every change to covered code.** Diff the covered files from the sync commit to the current commit, and read each commit message. Also look for code that moved: a covered function that is renamed, split, or moved to another file is still covered code. Also look for new code that touches the state that a check guards, such as a new function that writes the same fields. For each change, decide which of these it is:
+   - **No effect.** The change does not alter anything the verification describes, such as formatting, comments, or code paths that the verification does not cover. Check this against the model or harness, not against the commit message.
+   - **The verification no longer describes the code.** A step that was one indivisible action is now two, a branch was added or removed, a check moved, a new path reaches the guarded state, or a value now has a different range. The model or harness must change.
+   - **The promise changed on purpose.** The change alters what the code promises, and evidence in the change says that this is intended: the doc comment, the tests, the changelog, or the commit message. The property must change, and you must cite that evidence.
+   - **The promise may be broken.** The code changed, and no evidence says that the promise changed. Treat a failure that follows as a bug candidate.
+
+4. **Update from the code, not from the result.** Change the model or harness so that each changed part again points to code that a reviewer can open, and keep one indivisible step in the code as one step in the verification. Write the update from the code before you rerun, and do not shape it by what makes the check pass. Change a property only for a promise that changed on purpose. Write down the old wording, the new wording, and the evidence. Keep the bounds unless the change makes them wrong. If you must reduce a bound, say so in the report.
+
+5. **Rerun and judge each result.**
+   - **Pass:** the check can now pass on a description that has lost the ability to fail. Break the new code the way the property guards against, such as removing a new check or reordering a new step, and confirm that the check catches it. Then drop the break.
+   - **Fail:** replay the counterexample against the real code, step by step. If a step cannot happen in the code, the verification is wrong. Fix the verification, and say what was wrong. If every step can happen, it is a bug. Name the commit that introduced it, tell the counterexample as a sequence of steps in the code's own words, and state the harm in one sentence. If a cheap test or reproduction against the real code shows the bug, add it to the report as evidence. Do not commit it to the product code.
+
+6. **Update the verify skill.** Update the code that each check covers, the commands, the bounds, the assumptions, and the sync commit. Set the sync commit to the commit that you checked. Do not move the sync commit for a blocked check, and say so in the report. Then follow the verify skill once as the next agent would, so that you know its steps still run.
+
+## Report
+
+Tell the user, for each check:
+
+- the outcome, and the commits that you read;
+- what changed in the verification and why, with a short reason for each change: the code changed shape, or the promise changed on purpose (with the evidence);
+- the rerun result, and the break that you used to show the updated check can still fail;
+- each bug, in plain words: the counterexample as steps in the code's words, the harm, and the commit that introduced it;
+- what the verification still does not cover, including new code that it should cover and does not.
+
+Say outright which failures were drift in the verification and which were bugs in the code. For a check that passed before you updated it and fails after, say that the old pass was on a stale description.
+
+Put the verification updates in a change of their own, separate from any product fix.

package/builtin/skills/pstack/dsh/skills/maintain-verification-skill/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: maintain-verification-skill
+description: "Periodic pass that keeps a project's verification skill and feature map honest: parallel source readers per feature, one live session driving every feature, at most one PR of proven corrections. Use for /maintain-verification-skill or \"audit the verify skill\"."
+disable-model-invocation: true
+---
+
+Read [DSH host operations](../../DSH.md) once before executing this workflow.
+
+
+# Maintain a verification skill
+
+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
+
+Pick one, and say which:
+
+- **clean** — every feature got source and live coverage; nothing worth shipping. No branch, no PR.
+- **changed** — one PR ships proven doc, harness, or map corrections.
+- **blocked** — coverage could not finish or a proven fix could not ship safely. Say exactly what blocked it.
+
+## Edit scope
+
+Only edit the verification skill's own directory (its SKILL.md, features/, and any harness scripts it owns). Never edit product code during a run: a behavior the map describes that the app no longer does is either doc drift (fix the map) or a product regression (report it, don't paper over it in docs).
+
+## Pass
+
+0. **Locate the target.** Find the verification skill to maintain: the project-local skill whose body has launch/drive sections and a feature map (usually `.dsh/skills/verify-*/`). Several candidates → ask which one; none → stop and point at `/create-verification-skill` instead of inventing a target.
+
+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.
+
+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.
+
+4. **Live pass.** Required even when source looks clean. The coordinator owns all driving; follow the verification skill's own launch model — one long-lived instance driven serially for servers and UIs, or a fresh isolated session per drive for short-lived CLIs (the skill's Launch section decides, not this one). Exercise every feature at least once, and hold three invariants the whole pass, whatever the failure: (1) never drive an instance you haven't health-checked since it last did something surprising — doctor before first drive, doctor on each fresh session where sessions are the unit, doctor again after any failed drive, and where doctor can't see the failure (a wedged UI state on a healthy process), reset to a known state or relaunch rather than hoping; (2) evidence captured so far survives every cleanup, checked at its named location, not assumed; (3) nothing a drive started outlives that drive's usefulness — failed-iteration residue is cleaned whether the session is stuck, exited, or shared (for a shared instance, clean the residue, not the instance). A doctor failure caused by skill drift is drift: fix it under edit scope and retry once — restart whatever the fix invalidated, nothing more — before calling the pass `blocked`. A feature that can't be reached is `verified-unreachable` only with the concrete prerequisite (auth, entitlement, OS, external state) and the route attempted; if the map omits that prerequisite, that's drift. Any harness fix from triage gets re-driven live before it ships. Final teardown happens after the last drive of the run — including those re-proofs — so nothing outlives the run (evidence stays, per the skill).
+
+5. **Triage.** Wrong or missing user-POV description → doc drift, fix it. Working behavior the harness can't drive → harness gap, fix it; a harness fix follows the same helpers rule as generation (scripts executable, invocation documented in the skill body). App behavior that's actually broken → product gap; record it for the user, keep it out of this PR.
+
+6. **Ship or stop.** For changed: one PR of proven corrections, re-read every changed file first. For clean or blocked: no PR, report the outcome and the coverage honestly.
+
+Keep concise run notes (features covered, unreachable prerequisites, confirmed drift, outcome) in a scratch location; don't commit them.

package/builtin/skills/pstack/dsh/skills/make-bot-ui/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: make-bot-ui
+description: "Build a UI and backend that submit tasks through the DSH MCP connection and show progress and results."
+disable-model-invocation: true
+---
+
+Read [DSH host operations](../../DSH.md) once before executing this workflow.
+
+
+# Build a UI that delegates to DSH
+
+Keep the original end-to-end workflow: a user clicks a page, a backend submits the chosen task, DSH handles it, and the page shows progress and results. Use this plugin's MCP connection instead of a host-specific webhook routine.
+
+1. In DSH Super Code settings, enable Connection deliberately and allow only the intended workspace. Use the displayed MCP URL and credential. Keep the credential in the backend's environment or a user-managed secret file; never in browser JavaScript, chat, logs or the Skill. Do not turn on caller approval unless the user explicitly requests it.
+2. Build the backend with an MCP client supporting Streamable HTTP (for example the project's existing MCP SDK). Connect to the configured URL using bearer authentication. Run `dsh_status` to verify identity, directory authorization and capacity. Do not launch a second DSH or read its profile to bypass a connection error.
+3. Discover the current tool schema through MCP. Before submission, call `dsh_sessions` for the chosen cwd. Let the user select an available existing taskId or explicitly choose a new conversation when `allowNewConversations` is true. Respect linked-connection and active-task counts. A taskId identifies the reusable conversation, not an individual turn: keep requestId records and prior results separate from its current turn. Do not silently reuse the latest conversation.
+4. Validate the UI's small, named action schema in the backend; browser fields and returned content are data, not permission to run arbitrary instructions. Map each allowed action to its fixed task prompt. Use the bundled [stable submission helper](references/submissions.md) for a stable requestId, canonical execution payload, same-ID admission and restart recovery. Include validated arguments, cwd, exact prompt, explicit conversation and confirmed optional model choice in that payload. Follow its conflict and persistence-error contracts; use `receipts()` to restore this backend's owned task IDs. Keep the MCP credential out of the payload/store. Do not replace the helper with a requestId-only cache or silently generate a new ID on retry. Use exact optional provider/model/effort IDs from `dsh_models`; omitted fields inherit the host.
+5. Track the returned taskId using `dsh_wait` and its returned cursor. Preserve the returned status strings, including `starting`, `running`, `waiting_confirmation`, `cancelling`, `finished`, `failed`, `cancelled`, `interrupted` and `unavailable`, and display unknown statuses explicitly. Only `finished`, `failed` and `cancelled` are settled. Keep observing `interrupted` and `unavailable`, which can still own active work; retain explicit cancellation and never resubmit automatically. Use `dsh_read` to retrieve paged public results when needed. A finished turn is not proof of correctness. Display `waiting_confirmation` even when caller approval is disabled and `callerApproval.pending` is empty; direct the user to DSH via the returned nextAction. The backend must not auto-approve. Cancel only the task this UI owns on an explicit cancel action, and observe its settled result rather than treating the cancellation request as completion.
+6. Bind the page backend to loopback by default. If remote access is requested, inspect the existing authenticated proxy or tailnet state and reuse its node; report the actual hostname/address and verified URL. Configure the minimal authorized bind/proxy route, then probe it from the intended client path. Installing or authenticating new network software needs its own authorization and the real provider's login flow. Keep the MCP credential server-side. Never guess an endpoint or claim that a localhost probe proves remote reachability.
+7. Verify the complete path with a harmless task in a task-owned workspace: user selection, submission, identical and concurrent same-ID retries, same-ID changed-content rejection, backend restart, progress, approval/error display and final public result. For retained HTTP evidence, use the [capture helper](../../scripts/capture.mjs) from this workspace: `node "<PSTACK_ROOT>/scripts/capture.mjs" curl -sS -i <URL>` (add request arguments as needed). It saves both response and exit status in a new project-local run directory; read and cite the returned files. Save screenshots under this project's evidence directory. Keep evidence for review and use recoverable cleanup when requested. Confirm that no credential enters browser bundles, responses, screenshots or logs. Test denied directories and disabled new conversations. Reuse one MCP session. On cleanup or replacement of a failed transport, attempt its terminateSession (HTTP DELETE) before closing the client and report any cleanup failure; then stop only this run's backend and keep its evidence. A local client close alone does not release the server connection.
+
+Report the real UI URL, selected DSH workspace/conversation, what was verified and any missing dependency. If MCP is unavailable, pause the connection-dependent phase with the exact setup needed; do not invent an equivalent host API or claim the bot was awakened.

package/builtin/skills/pstack/dsh/skills/make-bot-ui/references/submissions.md

@@ -0,0 +1,44 @@
+# Stable submissions
+
+Use the bundled `scripts/submissions.mjs` from the backend instead of writing another request cache. It uses only Node built-ins and leaves host configuration unchanged. Read it and this contract before integrating it. Import it at its actual installed absolute path, or copy it unchanged into the task-owned project if that project must run without this plugin installed; preserve its license provenance.
+
+One backend owns one task-owned JSON file. Do not point two backend processes at that file. The helper provides same-process concurrency and restart recovery, not a distributed lock or a power-loss guarantee. The file and failed atomic-write stages may contain task prompts: keep them private, ignored by Git, and exclude secrets. The helper writes no credentials and never cleans user files.
+
+```js
+import path from 'node:path'
+import { openSubmissions } from '<PSTACK_ROOT>/skills/make-bot-ui/scripts/submissions.mjs'
+
+const submissions = await openSubmissions(path.join(taskScratch, 'submissions.json'))
+
+// After validating browser fields, authorizing cwd and choosing the conversation:
+const payload = {
+  action, arguments: validatedArguments,
+  cwd: path.resolve(cwd), prompt: fixedPrompt,
+  conversation: conversation.mode === 'new'
+    ? { mode: 'new' } : { mode: 'existing', taskId: conversation.taskId },
+  selection: confirmedModelSelection ?? {},
+}
+const admission = await submissions.submit(requestId, payload, async (saved, stableId) => {
+  // callDshRun parses the MCP result and throws when isError is true.
+  const view = await callDshRun({
+    requestId: stableId, cwd: saved.cwd, prompt: saved.prompt,
+    ...(saved.conversation.mode === 'new'
+      ? { newConversation: true } : { taskId: saved.conversation.taskId }),
+    ...saved.selection,
+  })
+  return { taskId: view.taskId }
+})
+// admission = { requestId, replay, result: { taskId } }
+// Recover this backend's accepted task IDs after a restart:
+const ownedIds = new Set(submissions.receipts().map(row => row.result.taskId))
+```
+
+`submit` accepts a requestId matching `[a-zA-Z0-9_.:-]{1,128}`, a plain JSON object and a dispatch function. Include every field affecting execution in the payload. Object-key order is normalized; array order and actual values matter. Normalize paths, optional fields and conversation choices once at the backend boundary. The helper rejects non-finite numbers, sparse arrays and non-JSON values.
+
+- Identical concurrent submissions join one dispatch, including its rejection. Do not add an automatic retry loop around them.
+- Changed content with an existing or in-flight ID throws `error.code === 'request-conflict'`; map this to HTTP 409 before returning any cached receipt.
+- Intent is saved before dispatch. After an ambiguous transport error, the request stays unconfirmed. A later explicit retry uses the original payload and same requestId; DSH's own idempotency resolves whether it was accepted.
+- A successful dispatch must return a JSON object with `taskId`; save only the receipt fields the backend needs. Accepted receipts survive restart. `receipts()` returns copies, not mutable store data.
+- A corrupt/incompatible store fails startup. Initial persistence failure prevents dispatch. Result persistence failure is reported; a same-process retry saves the accepted receipt without dispatching again. After a crash, the original unconfirmed intent still recovers through DSH using its stable ID.
+
+Use `dsh_wait`/`dsh_read` for live state; a cached receipt is neither current status nor acceptance proof. The HTTP handler owns error presentation, transport lifetime, timeouts, allowed actions/directories and per-task authorization. Preserve exact host errors. Keep the helper's failed atomic-write stages for recovery rather than silently discarding state.

package/builtin/skills/pstack/dsh/skills/make-bot-ui/scripts/submissions.mjs

@@ -0,0 +1,86 @@
+import { mkdir, readFile, writeFile, rename } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+const identity = /^[a-zA-Z0-9_.:-]{1,128}$/
+function json(value, ancestors = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value !== 'object' || ancestors.has(value)) throw new TypeError('Expected finite, acyclic JSON data')
+  ancestors.add(value)
+  try {
+    if (Array.isArray(value)) {
+      if (Object.keys(value).length !== value.length) throw new TypeError('Expected dense JSON array')
+      return Array.from(value, item => json(item, ancestors))
+    }
+    if (![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new TypeError('Expected plain JSON object')
+    const result = Object.create(null)
+    for (const key of Object.keys(value).sort()) result[key] = json(value[key], ancestors)
+    return result
+  } finally { ancestors.delete(value) }
+}
+function object(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('Expected JSON object')
+  return json(value)
+}
+function receipt(value) {
+  const result = object(value)
+  if (typeof result.taskId !== 'string' || !identity.test(result.taskId)) throw new TypeError('Dispatch must return a taskId receipt')
+  return result
+}
+
+/** One backend owns this file. Dispatch owns transport/timeouts; this store never retries it. */
+export async function openSubmissions(file) {
+  const entries = new Map(), inflight = new Map()
+  let saved
+  try { saved = JSON.parse(await readFile(file, 'utf8')) }
+  catch (error) { if (error.code !== 'ENOENT') throw error }
+  if (saved !== undefined) {
+    if (saved?.version !== 1 || !Array.isArray(saved.entries)) throw new Error('Invalid submission store')
+    for (const row of saved.entries) {
+      if (!row || typeof row.requestId !== 'string' || !identity.test(row.requestId) || entries.has(row.requestId)) throw new Error('Invalid or duplicate stored requestId')
+      const payload = object(row.payload)
+      entries.set(row.requestId, { requestId: row.requestId, payload, ...(Object.hasOwn(row, 'result') ? { result: receipt(row.result) } : {}) })
+    }
+  }
+  let saving = Promise.resolve()
+  function save() {
+    const pending = saving.then(async () => {
+      await mkdir(dirname(file), { recursive: true })
+      const stage = file + '.' + randomUUID() + '.tmp'
+      // A failed rename retains this task-owned stage for recovery; never wipe the store.
+      await writeFile(stage, JSON.stringify({ version: 1, entries: [...entries.values()] }) + '\n', { mode: 0o600, flag: 'wx' })
+      await rename(stage, file)
+    })
+    saving = pending.catch(() => {})
+    return pending
+  }
+  return {
+    receipts() {
+      return [...entries.values()].filter(row => row.result).map(row => ({ requestId: row.requestId, result: structuredClone(row.result) }))
+    },
+    async submit(requestId, input, dispatch) {
+      if (typeof requestId !== 'string' || !identity.test(requestId)) throw new TypeError('Invalid requestId')
+      const payload = object(input), key = JSON.stringify(payload)
+      const pending = inflight.get(requestId)
+      if (pending) {
+        if (pending.key !== key) throw Object.assign(new Error('requestId already used for different content'), { code: 'request-conflict' })
+        return { ...structuredClone(await pending.result), replay: true }
+      }
+      const result = (async () => {
+        let row = entries.get(requestId)
+        if (row && JSON.stringify(row.payload) !== key) throw Object.assign(new Error('requestId already used for different content'), { code: 'request-conflict' })
+        if (!row) { row = { requestId, payload }; entries.set(requestId, row) }
+        await save()
+        if (row.result) return { requestId, replay: true, result: structuredClone(row.result) }
+        const accepted = receipt(await dispatch(structuredClone(row.payload), requestId))
+        row.result = accepted
+        await save()
+        return { requestId, replay: false, result: structuredClone(accepted) }
+      })()
+      inflight.set(requestId, { key, result })
+      try { return await result }
+      finally { if (inflight.get(requestId)?.result === result) inflight.delete(requestId) }
+    },
+  }
+}

package/builtin/skills/pstack/dsh/skills/no-comments/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: no-comments
+description: "Spawn Comment Sicko, fix accepted findings, and offer encodings for claimed constraints."
+disable-model-invocation: true
+---
+
+Read [DSH host operations](../../DSH.md) once before executing this workflow.
+
+
+# No comments
+
+Spawn Comment Sicko. Act on accepted findings.
+
+Defer to Comment Sicko's fresh perspective.
+
+## Scope
+
+Use the caller's files or diff. Otherwise use the current diff against the base branch, default `main`, including the working tree.
+
+## Steps
+
+1. Spawn `subagent` with a role-specific DSH brief. Pass the scope. Apply role preferences only through the actual schema and confirmed routes in DSH.md; otherwise inherit the host model and effort. 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.
+6. Report the deletion count, restored comments, reruns, architect sketch, fixes, encoding offers, encodings, unenforced constraints, and other open work.

package/builtin/skills/pstack/dsh/skills/poteto-help/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: poteto-help
+description: Guides users through pstack setup, /poteto-mode, and picking the skill, playbook, or principle for a task. Type /poteto-help with a question.
+disable-model-invocation: true
+---
+
+Read [DSH host operations](../../DSH.md) once before executing this workflow.
+
+
+# PStack for DSH
+
+For a help question, answer it and provide at most one suggested prompt; do not start a workflow. Read the linked adapted Skill before recommending it. For a direct request to do the work, route to that Skill. When the need is unclear, ask once whether it is setup, starting a task, choosing a workflow, fixing a run or personalizing conventions. If a Skill is absent from the short table below, read its native catalog entry and route by its actual description.
+
+PStack is an optional workflow package under Settings → Super Code preset → Preset Skills. The package switch updates existing conversations' catalog, subsequent loads and native slash menus after saving. It does not retract instructions already in context.
+
+Start with `/poteto-mode` plus your task. It routes to the included playbooks and reads their sibling Skills as references. You can also invoke any of the 58 Skills through the native `/` menu. Names shared with a project/user Skill use native priority; when Matt and PStack both supply tdd or teach, the earlier registered Matt entry wins.
+
+| Need | Workflow |
+|---|---|
+| Optional project budget and delegation preferences | [setup-pstack](../setup-pstack/SKILL.md) |
+| Types and architecture before implementation | [architect](../architect/SKILL.md) |
+| Independent candidate designs and synthesis | [arena](../arena/SKILL.md) |
+| Partitioned coverage or experiments | [swarm](../swarm/SKILL.md) |
+| Explain runtime behavior or decision history | [how](../how/SKILL.md), [why](../why/SKILL.md) |
+| Review existing work or risk beyond the diff | [interrogate](../interrogate/SKILL.md), [blast-radius](../blast-radius/SKILL.md) |
+| Recover prior context or summarize this chat | [recall](../recall/SKILL.md), [ketchup](../ketchup/SKILL.md) |
+| Create or maintain real feature verification | [create-verification-skill](../create-verification-skill/SKILL.md), [maintain-verification-skill](../maintain-verification-skill/SKILL.md) |
+| Review lessons or draft personal conventions | [reflect](../reflect/SKILL.md), [automate-me](../automate-me/SKILL.md) |
+| Build a UI that submits work to DSH | [make-bot-ui](../make-bot-ui/SKILL.md) |
+| Keep a sourced decision trail | [show-me-your-work](../show-me-your-work/SKILL.md) |
+| Generate or maintain a formal property check | [create-formal-verification-skill](../create-formal-verification-skill/SKILL.md), [maintain-formal-verification-skill](../maintain-formal-verification-skill/SKILL.md) |
+| Explain a model-checker's result | [statechart](../statechart/SKILL.md) |
+
+All 23 poteto-mode playbooks remain available: feature, bug fix, refactoring, perf, prototype, visual parity, runtime/trace forensics, investigation, eval, hillclimb, multi-phase planning, autonomous run, orchestrate, session pickup, pause, PR opening/babysitting/shipping, both autopilot modes, worktree cleanup and Skill authoring. Read the mode's routing table; playbooks are not extra slash commands.
+
+DSH.md defines portable delegation, models, history, tool discovery, permissions and optional dependencies. In particular, role names are prompt templates; the host owns actual model selection, delegation depth and approvals. A different-model review is labeled only when it actually used another allowed route. Missing history tools use an explicit handoff/export rather than private journals. External authoring/control/cleanup Skills are replaced with bundled DSH procedures.
+
+For a long run, name the finish predicate and keep a resume plan. DSH background completions resume the root; no extra host instance or fabricated loop command is needed. For a planning-only request, deliver the plan and stop before implementation. Remote publication, deletion and service exposure continue to follow the user's scope and host approvals.
+
+If setup preferences are absent and the answer concerns cost or role selection, offer setup once; otherwise use inherited host models. Reasoning budget requests an effort only where the actual route supports it; smaller panels reduce independent attempts, and concurrency only changes scheduling. When a verification harness or formal check is missing and relevant to the question, point to the corresponding creation Skill. Preserve the one-time optional offers; don't start either as part of answering help.
+
+Troubleshooting: if the package is missing from `/`, check its switch and preset composition; instructions already loaded cannot be removed by switching it off. If a role choice has no effect, confirm the preference was read and the actual tool exposes that route/effort. If writers collide, isolate output paths/worktrees. If an unattended task stops, inspect the checkpoint and actual notification/scheduler capability rather than inventing a custom mode or timer. Keep the user's finish predicate in the next prompt.

package/builtin/skills/pstack/dsh/skills/poteto-help/references/prompting.md

@@ -0,0 +1,51 @@
+# Word the prompt
+
+A prompt states the intent and the check for done. The playbook supplies the steps, so a few plain sentences beat a spec.
+
+## Put in
+
+- The goal. Say what is wrong or what the user wants.
+- The done check. It can pass or fail. "Make it better" and a duration are not checks.
+- The proof to show. Ask for the real command output, a video of the flow, the stored value, or a before and after number.
+- What the user already knows. A symptom, a repro step, a log, or a link saves the agent a search.
+- The real constraints. "repro first", "don't change any code yet", "zero behavior change", and "let me review before proceeding" each change what the agent does.
+
+## Leave out
+
+- The how. Say what to achieve, and leave the agent room to find a better way.
+- A list of skills or steps. A hand-written order drops or reorders steps the playbook keeps. Name a skill only to override one choice.
+- The user's theory of the cause, until the agent restates the problem. A stated guess narrows the search.
+
+## Load the context first
+
+- For a noisy report, ask the agent to restate the underlying issue in its own words and in plain English before it does anything else. A misreading shows up before any code exists.
+- In a fresh chat, `/recall` earlier work on the topic. Old chats hold context that the new agent lacks.
+- Before a change to unfamiliar code, ask `/how` for the mechanics and `/why` for the reasons. An agent with no traced model fixes the symptom at the first plausible spot.
+- Ask `/teach` to make the case for a choice, as in "convince me it fixes the cause and not the symptom". A case is easier to check than a summary.
+
+## Design before the plan
+
+- Never take the first design. Ask for prototypes of a few options, with screenshots or videos for UI, and pick from the evidence.
+- Let prototypes answer the open questions. Don't review an abstract plan adversarially, because reviewers invent risks that never happen.
+- For a shared package or API, ask for the README or a tutorial first, then work back to the code. The doc becomes the target the agent checks itself against.
+- Ask for the plan only after the design is settled. Each step of the plan ends in a check.
+
+## Follow up short
+
+- "do it", "continue", and "keep going until done" are whole prompts once the chat holds the task.
+- Start with "new task" when the subject changes. Otherwise the mode treats the message as the next step.
+
+## 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 task's bounded work/verify loop that predicate.
+- 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.
+- Give an exit: "if you're truly stuck after a few hours, stop and write up why".
+
+## Steer in one line
+
+- Restate the goal: "i said the goal is to repro. i did not ask for a fix yet."
+- Name the principle: "apply prove it works. show me the real output, not the build log."
+- A principle name works because the agent already read the rule. Its reply names the decision the rule changed.