dsh-pstack 0.1.0 → 0.2.0-beta.1

package/assets/skills/setup-pstack/SKILL.md

@@ -1,76 +1,67 @@
 ---
 name: setup-pstack
-description: "Configure which routes pstack uses per role and at what reasoning budget. Writes ~/.dsh/pstack-models.md, the role file every pstack skill reads. Use for /setup-pstack, \"configure pstack models\", \"pstack budget\", or changing pstack's model choices."
+description: Configure which models pstack uses per role and at what reasoning budget. Detects the child model routes this deployment serves and writes `$DSH_HOME/pstack-models.md`, which overrides the skill defaults. Use for /setup-pstack, "configure pstack models", "pstack budget", or changing pstack's model choices.
 ---
 
 # Setup pstack
 
-Write `~/.dsh/pstack-models.md`, the role file that sets pstack's route per role.
+> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+
+Write `$DSH_HOME/pstack-models.md`, the role file `pstack_subagent` re-reads on every delegation and that sets pstack's model per role.
+
+That file is the only thing this skill writes. It never touches `package.json`, `cordis.patch.yml`, a native default model, or a credential.
 
 ## Steps
 
-### 1. Detect available routes
+### 1. Detect available models
 
-Call `list_subagent_models` with no arguments to list registered LLM providers. Then call it with each provider id to list that provider's models and their reasoning efforts. That is the dependable source. Never write a provider or model you have not confirmed is available. The value `inherit-parent` is always valid and means the child runs on the parent chat's route.
+Call `list_subagent_models()` with no arguments to list the LLM providers this deployment serves. Call `list_subagent_models({ provider })` to list that provider's models, then `list_subagent_models({ provider, model })` to list the reasoning efforts that exact model supports.
 
-If `list_subagent_models` is unavailable, ask the user for the provider/model pairs they can use, or fall back to `inherit-parent` for every role and say so.
+That adapter metadata is the only dependable source. This deployment decides which routes exist, and only the model's own advertised effort list says whether `max`, `xhigh`, `high`, or `medium` is available. Do not infer an effort ladder from a model id.
+
+When `list_subagent_models` is not available in this session, do not invent a route. Either ask the user for a `provider/model` pair they have already confirmed, or write `inherit-parent` for every role and say plainly that the choices are unverified. Never hardcode a model id, never ask for an API key, and never claim a route works because it looks plausible. `inherit-parent` and `auto` always work because they send no route at all.
 
 ### 2. Load current state
 
-If `~/.dsh/pstack-models.md` exists, read its `# budget` line and role values and treat them as current choices. Otherwise start from the defaults in step 5. A role not in step 5 is retired; drop it.
+The role list and the shape of a value come from this package's `../../docs/pstack-models.example.md`. Read that file. It is generated from the role manifest, so it is the list: do not re-derive role names from memory and never add a role the manifest does not name.
+
+If `$DSH_HOME/pstack-models.md` already exists, read it and treat its `# budget` line and its role values as the current choices, and keep every role the user changed by hand. Otherwise start from the example's `inherit-parent` values. A line whose role is not in the example, such as `how critics`, is from a retired role: list it for the user as retired, then drop it.
 
 ### 3. Budget, map, and confirm
 
-**(a) Ask for a budget.** Use `ask_user_question` with these four labels. Name the current budget when the file records one. With no file, say that `large` matches the skill defaults.
+**(a) Ask for a budget.** Prefer `ask_user_question` over free text. Offer these four options with these exact labels, and name the current budget when the file records one. With no file, say that no budget is recorded yet and that every role currently inherits the parent route.
 
 - `unlimited — max reasoning`
 - `large — xhigh reasoning`
 - `medium — high reasoning`
 - `small — medium reasoning`
 
-**(b) Apply it.** Build the working table from the defaults. On a re-run, keep any role you changed by family, list, or the `inherit-parent` alias. `unlimited`, `large`, `medium`, and `small` set the effort token of every real route, panel entries included, to `max`, `xhigh`, `high`, or `medium`. The effort token is the last token on the ladder `max` > `xhigh` > `high` > `medium` > `low`. If the result is not a detected route, use the same provider and model with the highest supported effort at or below the target, otherwise mark the role as needing a choice. `inherit-parent` does not change.
+**(b) Apply it.** Keep the route of every role the user set by family, list, or alias (`inherit-parent`, `auto`). Only the effort of a role that already names a route follows the budget. `unlimited`, `large`, `medium`, and `small` target `max`, `xhigh`, `high`, and `medium`.
 
-**(c) Show the roles and confirm.** Show every role with its route, marking any real route not in the detected set as needing a choice. Also list each line step 2 dropped. Use `ask_user_question` to ask whether to accept as-is or change specific roles, offering the detected routes plus `inherit-parent`. For panel roles (arena runners, architect runners, interrogate reviewers) the value is a comma-separated list, and one child runs per entry. `arena cross-judge pool` is also a list. `swarm workers` is the default route for every worker.
+Apply a target only when that model's own `list_subagent_models({ provider, model })` list contains it. When it does not, use the highest effort at or below the target that the model does advertise, and say which role moved. When nothing at or below the target is advertised, mark the role as needing a choice instead of writing an effort the adapter would reject. `inherit-parent` and `auto` never change, because they carry no effort.
+
+**(c) Show the roles and confirm.** Show every role with its route, marking any route that does not resolve on this deployment as needing a choice. Also list each line step 2 dropped as retired. Ask whether to accept as-is or change specific roles, offering the confirmed routes plus `inherit-parent` and `auto`, which both mean this role runs on the parent chat model. Prefer `ask_user_question` over free text.
+
+For the panel roles (`arena runners`, `architect runners`, `interrogate reviewers`) the value is a list, and `pstack_subagent` starts one child per entry, alias entries included, so the list length sets the count. `arena cross-judge pool` is also a list, but `pstack_subagent` starts one child from it, chosen with `roleIndex`. `swarm workers` is a list as well: its first entry is the default route for every worker, a race passes `roleIndex` to give different arms different entries, and the caller still starts each worker itself. Two entries on the same route are not a cross-model panel; say so instead of implying model diversity.
 
 ### 4. Validate
 
-Every real route written must be in the detected set. `inherit-parent` always passes. If a chosen route is not available, stop and ask again.
+Every route written must be one this deployment serves, and every effort must appear in that exact model's advertised list. `inherit-parent` and `auto` always pass. If a chosen route does not resolve, stop and ask again rather than writing it and hoping the first delegation catches it. Remember that the effort you write is the level that role *starts* at: a caller may raise or lower it per delegation with `reasoningEffort`, and a running child may change its own, so a role line that names a modest level is not a mistake to correct.
 
 ### 5. Write the file
 
-Write `~/.dsh/pstack-models.md` with a `# budget` line and one line per role. Overwrite the whole file so re-runs stay idempotent.
-
-```text
-# pstack model configuration. One line per role. Delete a line to inherit the parent route.
-# Value: inherit-parent | <provider>/<model> [effort]
-# budget: large (xhigh)
-feature, refactoring: inherit-parent
-bug-fix: inherit-parent
-perf-issue: inherit-parent
-hillclimb: inherit-parent
-judgment and prose: inherit-parent
-hardest tasks: inherit-parent
-how explorer: inherit-parent
-how explainer: inherit-parent
-why investigators: inherit-parent
-why synthesizer: inherit-parent
-reflect tooling: inherit-parent
-reflect judgment, divergent, synthesizer: inherit-parent
-arena runners: inherit-parent, inherit-parent
-arena cross-judge pool: inherit-parent, inherit-parent
-swarm workers: inherit-parent
-architect runners: inherit-parent, inherit-parent
-interrogate reviewers: inherit-parent, inherit-parent
-```
+Read the old `$DSH_HOME/pstack-models.md` first, keep the user's own edits, name the retired roles you dropped, and confirm before overwriting. Then write the complete file in one pass, so a re-run of this skill produces the same bytes and converges: a `# budget` line naming the chosen label and its target effort, and one line per role, using the exact role keys from the example.
+
+Read `../../docs/pstack-models.example.md` from this package and write the same shape to `$DSH_HOME/pstack-models.md`, replacing each `inherit-parent` with the route the user confirmed. Do not retype the role keys from this skill: the example is generated from the role manifest, and a hand-written copy would drift from the parser.
 
 ### 6. Confirm
 
-Tell the user the file was written and that it applies to new sessions. Re-running this skill updates it.
+Tell the user the file was written and that it applies to the next delegation, because `pstack_subagent` re-reads it every time. A child that already started keeps the route it started with. Re-running this skill updates the file.
 
 ### 7. Offer a verification skill (optional)
 
-Check whether the project has a way to drive the real app for proof (a `verify-*` skill, or an existing harness). If not, offer once: "want a project-local verification skill, so agents can drive the app the way a user does and prove changes work? I can generate one with /create-verification-skill." On yes, invoke `/create-verification-skill`. On no, move on without pushing.
+Check whether the project has a way to drive the real app for proof (a `verify-*` skill, or an existing harness). If not, offer once: "want a project-local verification skill, so agents can drive the app the way a user does and prove changes work? I can generate one with /create-verification-skill." On yes, invoke `/create-verification-skill` (its `SKILL.md` is in this package's skill resources). On no, move on without pushing.
 
 ### 8. Offer a formal verification skill (optional)
 
-Check whether the project already has a formal verification skill. If not, offer once: "want a formal verification skill, so agents can prove a key property of your code holds in every case in scope, not only the cases tests reach? I can generate one with /create-formal-verification-skill." On yes, invoke `/create-formal-verification-skill`. On no, move on without pushing.
+Check whether the project already has a formal verification skill (a project skill that runs a model checker, a proof, or another verifier against the code). If not, offer once: "want a formal verification skill, so agents can prove a key property of your code holds in every case in scope, not only the cases tests reach? I can generate one with /create-formal-verification-skill." On yes, invoke `/create-formal-verification-skill` (its `SKILL.md` is in this package's skill resources). On no, move on without pushing.

package/assets/skills/sharpen/SKILL.md

@@ -4,8 +4,6 @@ description: Make a task deeper, not bigger, then rewrite the prompt. Use for /s
 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`.
-
 I want a deeper version of this task, not a bigger one. Before rewriting it, do four things:
 
 1. Say what a top professional in this field would do here that I'm not asking for.

package/assets/skills/show-me-your-work/SKILL.md

@@ -4,10 +4,10 @@ description: "Keep a reviewable decision trail for long-running or unattended wo
 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`.
-
 # Show me your work
 
+> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+
 Keep one canonical log.
 
 ## The format
@@ -35,13 +35,13 @@ ts	phase	decision	why	evidence	result
 
 ## Logging a row
 
-Write each entry the way you'd tell a teammate what you did. Plain words, concrete actions, no AI speak or abstract jargon (the **unslop** skill applies to log text too).
+Write each entry the way you'd tell a teammate what you did. Plain words, concrete actions, no AI speak or abstract jargon (apply `unslop` to log text too; read its `SKILL.md` at its absolute resource path).
 
-Use the helper `scripts/log.sh <logfile> <phase> <decision> <why> <evidence> <result>`. It stamps `ts`, writes the header on first use, strips stray tabs/newlines, and prefixes any cell starting with `=`, `+`, `-`, or `@` with a single quote. A bare `printf` appending a row works too, but mind those same bytes if cells come from generated or user-supplied text.
+Use the helper `scripts/log.mjs <logfile> <phase> <decision> <why> <evidence> <result>`; run it through `pstack_script` with `id: "log"`, which needs no `node` on PATH. It stamps `ts`, writes the header on first use, strips stray tabs/newlines, and prefixes any cell starting with `=`, `+`, `-`, or `@` with a single quote. A bare `printf` appending a row works too, but mind those same bytes if cells come from generated or user-supplied text.
 
 Log decision points and checkpoints, not every action: a fork chosen, a unit completed with its verification result, a pivot or revert with its trigger, a blocker surfaced, a gate fixed. For loop runs, one row per iteration. Skip the trivial and self-evident.
 
-A run is one agent conversation, including its later turns and any summary of it. A pickup, a replacement agent, or a new chat starts a new run. When a run adds to a log that already has rows, its first row has phase `start`, and so does its first row after another run's `start` row. So a run that comes back to a log in a later turn first reads the log's last rows to see whether another run wrote since. A `start` row names the `ts` range of the rows before it that this run did not write, and its evidence names this run, such as its agent id. Use phase `start` for nothing else.
+A run is one agent conversation, including its later turns and any summary of it. A pickup, a replacement agent, or a new chat starts a new run. When a run adds to a log that already has rows, its first row has phase `start`, and so does its first row after another run's `start` row. So a run that comes back to a log in a later turn first reads the log's last rows to see whether another run wrote since. A `start` row names the `ts` range of the rows before it that this run did not write, and its evidence names this run, such as its session id. Use phase `start` for nothing else.
 
 ## Where it lives
 
@@ -52,11 +52,11 @@ Commit it only when the work is ambitious enough that a reviewer needs the trail
 ## Rules
 
 - Append-only. A wrong call gets a new row that supersedes it. Never edit or delete history.
-- Prefer evidence produced by committed scripts over hand-made one-offs (the **encode-lessons-in-structure** principle skill).
+- Prefer evidence produced by committed scripts over hand-made one-offs, per `principle-encode-lessons-in-structure`; read its `SKILL.md` at its absolute resource path.
 
-## Audit the log against the transcript
+## Audit the log against the run's events
 
-At the end of the run, before handing back, check the log told the truth. Read this run's session log under `$DSH_HOME/sessions/<workspace-slug>/<session-id>/`. The system prompt names the workspace. Do not scan other workspace directories. Walk this run's rows against what actually happened. Each stretch begins at one of this run's `start` rows, or at the first row if this run created the log, and ends at the next `start` row of another run:
+At the end of the run, before handing back, check the log told the truth. Read this run's raw events through `pstack_history` (`scope: "current"`), paging with `fromSeq` and `nextFromSeq` and pinning `throughSeq` so later turns cannot join the basis. Don't read the session store directory or glob across workspaces: that reads unrelated private sessions. If the read is `denied` or `unavailable`, say which layer failed and mark this audit unfinished rather than certifying the log. Walk this run's rows against what actually happened. Each stretch of them begins at one of this run's `start` rows, or at the first row if this run created the log, and ends at the next `start` row of another run:
 
 - Check that every row maps to a real decision or action.
 - Check that each row's evidence resolves and shows what the row claims.
@@ -66,7 +66,7 @@ Correct the log, not the story. The audit never edits or removes a row, even an
 
 ## Cross-model review of the trail
 
-Before handing back, spawn a subagent on a different model family from the one that did the work. Self-review is not a substitute. The subagent reads the audit trail and the run's transcript, then flags what the user should pay attention to. Not a redo of the work, a scan for what's suboptimal or risky. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill.
+Before handing back, start a `pstack_subagent` on a role configured to a different provider or model family from the one that did the work. Self-review is not a substitute. Brief it with the audit trail and the raw events you paged, because it cannot read this run's log on its own. It flags what the user should pay attention to: not a redo of the work, a scan for what's suboptimal or risky. When no other family is configured, write `reviewed by <the route that actually ran>` and state that this was same-model review instead of claiming independence. Pick that subagent's role per the Subagents section of `poteto-mode`; read its `SKILL.md` at its absolute resource path. 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.
 
 - Decisions logged with weak or absent evidence.
 - Verification steps skipped or claimed without proof in the transcript.

package/assets/skills/show-me-your-work/scripts/log.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import { appendFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region .runtime-sources/skills/poteto-mode/scripts/log.ts
+/**
+* Append one well-formed row to a show-me-your-work decision log (TSV).
+*
+* A Node replacement for the upstream `scripts/log.sh`. The observable rules are
+* the shell script's, because `skills/show-me-your-work/SKILL.md` tells the model
+* to read this file in a spreadsheet:
+*
+* - The header is written once, and only when the file is missing or empty.
+* - Rows are appended, never rewritten. A network mount can make the emptiness
+*   test lie for a file that exists, and the cost is one stray header line, not
+*   the rows.
+* - Tabs, CRs, and LFs inside a cell become spaces, so a cell always stays on one
+*   line and a row always has exactly six columns.
+* - A cell starting with `=`, `+`, `-`, or `@` gets one leading quote. Evidence
+*   is attacker-controlled (PR titles, filenames, generated text), and a
+*   spreadsheet parses those four characters as a formula.
+* - The row ends with a newline.
+*
+* No shell, no `date` process, and no `tr`/`printf` semantics to reproduce.
+*/
+/** The exact header line, including its trailing newline. */
+const HEADER = "ts	phase	decision	why	evidence	result\n";
+/**
+* Usage text.
+*
+* The shell script printed `log.sh` here because that was its own name. The
+* shipped file is `log.mjs`, and an error that tells the reader to run a script
+* this package no longer contains is worse than one that names the real path. The
+* exit code and the stream are unchanged.
+*/
+const USAGE = "usage: log.mjs <logfile> <phase> <decision> <why> <evidence> <result>\n";
+/** Formula-leading characters a spreadsheet would evaluate. */
+const FORMULA_PREFIXES = [
+	"=",
+	"+",
+	"-",
+	"@"
+];
+/**
+* One cell as the spreadsheet sees it.
+*
+* Exported because the skill's own contract is worth a unit test: the rules are
+* about what lands in a cell, not about how a row is assembled.
+*/
+function cleanCell(value) {
+	const flat = value.replaceAll(/[\t\n\r]/g, " ");
+	return FORMULA_PREFIXES.some((prefix) => flat.startsWith(prefix)) ? `'${flat}` : flat;
+}
+/** `YYYY-MM-DDTHH:MM:SSZ`, the format `date -u +%Y-%m-%dT%H:%M:%SZ` prints. */
+function timestamp(now = /* @__PURE__ */ new Date()) {
+	return now.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** Read whether a file is missing or empty, treating any read failure as empty. */
+function isEmptyOrMissing(logfile) {
+	if (!existsSync(logfile)) return true;
+	try {
+		return statSync(logfile).size === 0;
+	} catch {
+		return true;
+	}
+}
+/**
+* Append one row.
+*
+* @param logfile - target TSV; its parent directories are created as needed.
+* @param cells - exactly five cell values: phase, decision, why, evidence, result.
+* @param now - injectable clock, so the timestamp format is testable.
+* @returns the row written, without re-reading the file.
+* @throws {TypeError} when `cells` does not hold exactly five values.
+*/
+function appendDecisionRow(logfile, cells, now = /* @__PURE__ */ new Date()) {
+	if (cells.length !== 5) throw new TypeError(`expected 5 cells after the logfile, received ${cells.length}`);
+	const absolute = resolve(logfile);
+	const directory = dirname(absolute);
+	if (directory !== "" && !existsSync(directory)) mkdirSync(directory, { recursive: true });
+	if (isEmptyOrMissing(absolute)) appendFileSync(absolute, HEADER);
+	const row = `${[timestamp(now), ...cells.map(cleanCell)].join("	")}\n`;
+	appendFileSync(absolute, row);
+	return row;
+}
+/** Run the CLI. Returns the process exit code. */
+function main(argv, io = {
+	stdout: (value) => process.stdout.write(value),
+	stderr: (value) => process.stderr.write(value)
+}) {
+	if (argv.length !== 6) {
+		io.stderr(USAGE);
+		return 1;
+	}
+	const [logfile, ...cells] = argv;
+	try {
+		appendDecisionRow(logfile, cells);
+		return 0;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		io.stderr(`log.mjs: ${message}\n`);
+		return 1;
+	}
+}
+const entryPoint = process.argv[1];
+if (entryPoint !== void 0 && resolve(entryPoint) === fileURLToPath(import.meta.url)) process.exitCode = main(process.argv.slice(2));
+//#endregion
+export { HEADER, USAGE, appendDecisionRow, cleanCell, main, timestamp };

package/assets/skills/swarm/SKILL.md

@@ -4,13 +4,13 @@ description: Fan out N parallel workers, drain them, and return one report. Use
 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`.
-
 # Swarm
 
+> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+
 ## Start
 
-Call `todo_write` with one entry per phase before launching anything.
+Open a `todo_write` list with one entry per phase before launching anything.
 
 1. Frame
 2. Fan out
@@ -21,12 +21,14 @@ Call `todo_write` with one entry per phase before launching anything.
 
 1. State the done predicate and the artifact or report the swarm must return.
 2. Choose the shape. Partition into slices, race N workers on identical briefs, or mix both. For a race or mixed shape, declare `first pass`, `rank all`, or `best-of` before spawning.
-4. Spawn every worker with `role: "swarm workers"` and `agent: "general"`. The tool resolves the route from `~/.dsh/pstack-models.md`; `inherit-parent` runs on the parent model. For a race, name each arm's role up front.
-5. Give each worker its own writable output when it writes. When workers verify or measure commits, each brief names the exact SHAs. A measurement brief also names the method (sample count, what one sample is, order). The worker records both in its result.
+4. Pick the worker route. Use `role: "swarm workers"` for every worker: that role is a list, not a panel, so you start each worker yourself with one `pstack_subagent` call each. A role the file does not name inherits the parent route. Never invent a model id. Without `roleIndex` the tool takes the first entry, which is the default route for every worker. For a model race, keep `role: "swarm workers"` and pass a different `roleIndex` per arm, so this call's result carries that arm's actual route instead of leaving it implied. The tool reports the entry and route this call selected; it cannot compare separate calls, so when two arms land on the same entry you must say in your synthesis that they share one route and that this is not a cross-model race. 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.
+5. Give each worker its own writable output when it writes: the worker calls `create_worktree({ name })` in its own Session, or you create the checkouts one at a time and pass each absolute `path` as that worker's `cwd`. Two workers in one checkout are not isolated, and the parallel writes will collide on shared files. When workers verify or measure commits, each brief names the exact SHAs. A measurement brief also names the method (sample count, what one sample is, order). The worker records both in its result.
 
 ## Phase B: Fan out
 
-Spawn all N workers in one message with `agent: "general"`, the slice or race arm, and `role: "swarm workers"`. Every worker gets its own writable output when it writes.
+Start all N workers in one batch of `pstack_subagent` calls with `agent: "general"` and the step 4 role. A worker is a managed activation, so there is no background flag and nothing polls: each result arrives as a completion notice. Every worker runs locally as a child of this Session; there is no cloud environment, no VM, and no per-arm machine.
+
+When a worker must start from a branch other than the current one, make that branch reachable locally and start the checkout from it: the worker calls `create_worktree({ name, from })` with a local revision, or you create the checkout yourself and pass its absolute `path` as the worker's `cwd`. Creation does not fetch, so a branch that only exists on a remote has to be fetched first; a missing local revision fails instead of silently branching off the current commit.
 
 Every brief stands alone. Include the goal, scope, exact slice or race arm, how to verify, and what to report. Reports use `PASS`, `ISSUES`, or `BLOCKED` with evidence. A worker that can prove a defect reports `ISSUES` and lists every issue it can prove, not only the first.
 

package/assets/skills/tdd/SKILL.md

@@ -4,8 +4,6 @@ description: Use only when the user explicitly asks for TDD, a failing test, or
 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`.
-
 # TDD Bug Fix
 
 When fixing a bug with a clear, cheap test path, make the broken behavior executable before changing production code. The goal is a focused regression test that fails before the fix and passes after it.

package/assets/skills/teach/SKILL.md

@@ -4,10 +4,10 @@ description: Explain a body of work plainly so a person actually understands it.
 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`.
-
 # Teach
 
+> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+
 **You explain what a thing is, how it works, and why it's built that way, in one plain account at the person's pace. The goal is that they understand it, not that you change anything.**
 
 Teach sits on top of `how` and `why`. Get your bearings on what the work is and what it touches, then run `how` for how it works and `why` for why it's that way. Those are real skill invocations that do their own digging. Blend what they find into one plain explanation, lead with what matters to the person, and go deeper when they ask. Reword freely for teaching, with one exception. Keep `why`'s confidence language intact (its hedges are findings, not style).

package/assets/skills/technical-writing/SKILL.md

@@ -4,10 +4,10 @@ description: "Layered technical-writing standard: Diátaxis structure, Google de
 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`.
-
 # Technical writing
 
+> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+
 Write so a tired engineer understands on the first read. Apply all four layers.
 
 Three rules sit above the layers:

package/assets/skills/typescript-best-practices/SKILL.md

@@ -4,11 +4,11 @@ description: TypeScript best practices. Use when reading or editing any .ts or .
 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`.
-
 # TypeScript best practices
 
-Apply the **type-system-discipline** principle skill first.
+> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+
+Apply `principle-type-system-discipline` first; read its `SKILL.md` at its absolute resource path.
 
 | Rule | Summary |
 |------|---------|
@@ -23,10 +23,12 @@ Apply the **type-system-discipline** principle skill first.
 | Type guards | Must verify the claim. A lying guard is worse than `as` because the bug hides behind a name that says it's safe. Name them `isX` or `hasX`. |
 | Exhaustiveness | Inline `const _exhaustive: never = x;` in default arms so the compiler errors when a new variant is added. |
 | `satisfies` over `as` | Validates the value without widening literal types. |
-| Boundary validation | Parse where data crosses in, into a named domain type. `Record<string, unknown>` (however spelled) stops at that parse. Trust types inside. See the **boundary-discipline** principle skill. |
+| Boundary validation | Parse where data crosses in, into a named domain type. `Record<string, unknown>` (however spelled) stops at that parse. Trust types inside. See `principle-boundary-discipline`; read its `SKILL.md` at its absolute resource path. |
 | Schema-derived types | Reach for `Pick`/`Omit`/`Parameters`/`ReturnType`/`Awaited`/`typeof` before declaring a new interface. |
 | Object args | Pass objects, not positional, so argument order is self-documenting. Skip on hot paths (per-frame render, tokenizers, parsers). |
 | Real tests | Don't mock what you can run. Prefer the framework's real test primitives with leak/disposable checks, and verify UI in a running build. Mock only what you can't run locally. |
 | Structured telemetry | Prefer structured logger diagnostics with enough context to debug from an id. No `console.log` in shipped code. |
 
 Examples: `references/patterns.md`.
+
+This skill is explicit-invocation only. DSH does not consume a `paths` glob, so opening a `.ts` or `.tsx` file does not attach it: load it by name when you want it applied.

package/assets/skills/unslop/SKILL.md

@@ -4,8 +4,6 @@ description: Cut AI tells from any writing.
 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`.
-
 # Unslop
 
 Edit text to remove AI patterns. Scan for the patterns below, then rewrite. Preserve meaning and match the intended tone.

package/assets/skills/why/SKILL.md

@@ -4,15 +4,15 @@ description: Use for 'why does X work this way', 'why we picked Y', design ratio
 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`.
-
 # Why
 
-Investigate the motivation and intent behind code. The companion `how` skill answers what the code does and how it works. `why` answers what forces led to its shape.
+> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+
+Investigate the motivation and intent behind code. The companion `how` skill answers what the code does and how it works; read its `SKILL.md` at its absolute resource path when you need it. `why` answers what forces led to its shape.
 
-Each spawn below names a `role` for `pstack_subagent`; the tool resolves it from `~/.dsh/pstack-models.md`, and a missing line inherits the parent model.
+Each spawn below names a role key. `pstack_subagent` reads the route from `$DSH_HOME/pstack-models.md` 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. 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.
 
-Every spawn is a `pstack_subagent` call with `agent: "general"`. DSH has no readonly mode; tell each investigator not to write files, and check `git status` afterward. Investigators must not write anything.
+Every spawn is `agent: "general"` with a brief that forbids writes. **Do not swap in a narrower preset or tool set.** A narrower set can drop MCP tools, which disables the MCP-backed investigators and the synthesizer's citation spot-checks. Investigators still must not write anything, and each brief says so; that rule is an instruction, not a sandbox, so check `git status` before believing a report.
 
 ## Operating Posture
 
@@ -22,7 +22,7 @@ Operate as a **careful, cautious, and precise investigator**. Be honest about wh
 
 The **target** is usually a chunk of code, a pattern, a feature, or a named design decision. The **question** is usually a design rationale, a tradeoff, a motivating edge case, an external constraint, dead code, or a broad history sweep.
 
-If the target is vague ("why do we do it this way?" with no clear referent), make your best guess from conversation context (open files, recent edits, the current working directory, what was just discussed). State your interpretation briefly so the user can redirect if you're off, then proceed.
+If the target is vague ("why do we do it this way?" with no clear referent), make your best guess from conversation context (open files, recent edits, cursor location, what was just discussed). State your interpretation briefly so the user can redirect if you're off, then proceed.
 
 ## Step 2. Establish the Code Anchor
 
@@ -34,7 +34,7 @@ Before spawning investigators, build the seed context inline: file paths and lin
 
 ### Discovery
 
-Before spawning investigators, list the MCP servers available in this DSH session from the tool catalog and any MCP tools already in context.
+Before spawning investigators, list the tools this Session actually has, and treat an MCP as available only when its own tools appear in that list. The DSH harness exposes no MCP directory to inspect, and this port does not read one: an MCP that is absent from the tool list is a recorded gap, never a guess.
 
 Map each available MCP to one evidence category:
 
@@ -48,7 +48,7 @@ Map each available MCP to one evidence category:
 
 Source control is always available through git and `gh`. For the other six, classify using the MCP name, server instructions, tool names, and resource descriptors. If an MCP could fit more than one category, choose the one matching its primary evidence. Record ambiguous cases in the coverage map.
 
-Spawn one investigator per category that has a matching MCP, all in a single message so they run concurrently, each owning exactly one tool or MCP. Don't ask one agent to cover multiple MCPs. `role: "why investigators"`.
+Spawn one investigator per category that has a matching MCP, all in one batch of `pstack_subagent` calls so they start together, each owning exactly one tool or MCP. Don't ask one agent to cover multiple MCPs. Use `role: "why investigators"`. Each call returns a child id and the reports arrive as completion notices, so nothing polls and the synthesizer waits for every investigator that was started.
 
 Each investigator's prompt is `references/investigator-prompt.md` filled in, plus:
 - the category playbook `references/sources/<source>.md` for the selected MCP, adapted from the examples in `references/source-playbook.md`
@@ -78,7 +78,7 @@ If your scope assessment suggests a single-commit trivial target where the PR de
 
 ## Step 4. Synthesize
 
-Spawn one synthesizer. `role: "why synthesizer"`. It gets:
+Spawn one synthesizer with `role: "why synthesizer"`. It gets:
 1. The investigator findings, including any null results and any categories skipped with justification
 2. The code anchor
 3. The user's original question

package/cordis.patch.yml

@@ -1,20 +1,39 @@
 # dsh-pstack bundle patch.
 #
-# Two rows, both installed by this package:
-#   - `pstack` mounts the bundled skill provider. Every pstack skill becomes a
-#     normal DSH skill: model-invocable skills reach the catalog, user-invocable
-#     skills reach the `/` menu.
-#   - `pstack-subagent` mounts the `pstack_subagent` tool, the DSH replacement
-#     for Cursor's `Task` tool. It resolves pstack role lines from
-#     `~/.dsh/pstack-models.md` and delegates through `ctx.subagents`.
+# `pstack` registers the bundled skill provider. `pstack-subagent` registers
+# `pstack_subagent`, which starts one child per activation and re-reads the role
+# file on every delegation. `pstack-history` registers `pstack_history`, the
+# restricted read-only history tool; it reads raw events through `sessionQuery`
+# and authorizes the caller and its direct children only.
 #
-# The `pstack` row requires `ctx.skills`, which `@deepseek-ai/dsh-base` provides.
-# The `pstack-subagent` row requires `ctx.tools` and `ctx.subagents`, also in
-# base-backed profiles. Installing this bundle into a profile that lacks them
-# leaves the rows pending, exactly like any other dependency-driven plugin.
+# The two worktree rows carry the README promise that worktree support ships as a
+# necessary dependency: the bundle turns the official integration on when the
+# profile does not have it, and mounts nothing when it does. `disabled: !!js` is
+# evaluated by the Loader at every mount decision, and each expression reads the
+# composed row list rather than a startup snapshot. The row handle is
+# `ctx[Symbol.for('cordis.entry')]` (this entry), not `ctx.fiber.entry`, which
+# resolves to the enclosing `include` row and therefore never sees these siblings.
+# `scripts/worktree-mount.ts` owns the text of both expressions and `check:assets`
+# fails when this file drifts from it. See
+# docs/decisions/2026-10-26-worktree-guard-reads-own-entry.md.
+#
+# `pstack-history` is appended after the unit-4 rows so no delivered line moves.
+# Row order is not part of the history contract; the two worktree guards, by
+# contrast, stay adjacent and byte-identical to their generator.
 - insert:
     - id: pstack
-      name: "dsh-pstack"
-
+      name: dsh-pstack
     - id: pstack-subagent
-      name: "dsh-pstack/subagent"
+      name: dsh-pstack/subagent
+      config:
+        maxDepth: 2
+    - id: pstack-worktree
+      name: '@deepseek-ai/dsh-experimental-worktree'
+      disabled: !!js "(() => { const own = ctx[Symbol.for('cordis.entry')]; const rows = own && own.parent && own.parent.data; if (!Array.isArray(rows)) return false; return rows.some((row) => row !== null && typeof row === 'object' && row.id !== 'pstack-worktree' && row.name === '@deepseek-ai/dsh-experimental-worktree' && row.disabled !== true) })()"
+    - id: pstack-tool-worktree
+      name: '@deepseek-ai/dsh-experimental-tool-worktree'
+      disabled: !!js "(() => { const own = ctx[Symbol.for('cordis.entry')]; const rows = own && own.parent && own.parent.data; if (!Array.isArray(rows)) return false; return rows.some((row) => row !== null && typeof row === 'object' && row.id !== 'pstack-tool-worktree' && row.name === '@deepseek-ai/dsh-experimental-tool-worktree' && row.disabled !== true) })()"
+    - id: pstack-history
+      name: dsh-pstack/history
+    - id: pstack-script
+      name: dsh-pstack/script