@hyperdreamer/pi-webui 1.10.7 → 1.11.0-beta.10

package/docs/plugins.md

@@ -6,6 +6,7 @@ Plugins can currently:
 
 - add action-palette commands;
 - add workspace tools/panels next to Files, Git, and Terminal;
+- add Activity Rail activities opened from dedicated Rail controls;
 - add compact workspace-label items in the workspace list, panel header, and status bar;
 - call browser APIs and documented PI WEBUI plugin context helpers;
 - read workspace files and start workspace terminal commands through documented helpers;
@@ -79,7 +80,7 @@ After editing, check the manifest endpoint and browser-console failure cases.
 
 ## Canonical example: bundled Info plugin
 
-PI WEBUI ships a real bundled `info` plugin. Use it as the reference example because it is intentionally small while still exercising all core contribution types: an action, a workspace label, and a workspace panel.
+PI WEBUI ships a real bundled `info` plugin. Use it as the reference example because it is intentionally small while still exercising three UI contribution types: an action, a workspace label, and a workspace panel. Activity Rail activities are an additional v1 UI contribution type documented below.
 
 Bundled PI WEBUI plugins are developed as TypeScript in the repository, but their `package.json` metadata still points at built JavaScript because plugins are loaded by the browser as JS ES modules. `npm run dev:web` watches and rebuilds bundled plugin TS into `dist/pi-webui-plugins/` during development, and `npm run build` emits the JS before packaging a release.
 
@@ -147,7 +148,7 @@ Reload the PI WEBUI browser tab. PI WEBUI serves plugin modules with an mtime-ba
 
 When [machine federation](https://pi-webui.dev/machines) is enabled, PI WEBUI also loads discovered plugins from the selected remote machine. Remote plugins are trusted browser-side code like local plugins, but their contributions are machine-scoped:
 
-- actions, workspace panels, and workspace labels only appear while that machine is selected;
+- actions, workspace panels, Activity Rail activities, and workspace labels only appear while that machine is selected;
 - plugin file and terminal helpers run against that machine;
 - plugin code is loaded best-effort through the current gateway and cached for the browser page lifetime;
 - if the gateway and remote machine both have an enabled plugin with the same original id, `machineSpecific` metadata decides whether the gateway copy is reused or only the selected machine's copy can appear;
@@ -204,11 +205,11 @@ Built-in plugins can be managed from **Settings → PI WEBUI plugins** or with t
 ### Memory
 
 **Plugin id:** `workspace-memory`
-**What it does:** adds a read-only **Memory** workspace tab. It reads `pi-hermes-memory`-compatible data through PI WEBUI and never writes, creates, edits, or deletes memories.
+**What it does:** adds a read-only **Memory** Activity Rail activity. It is **Rail-only**: it does not contribute a workspace panel. It reads `pi-hermes-memory`-compatible data through PI WEBUI and never writes, creates, edits, or deletes memories.
 
-The tab shows independently collapsible **Global memory** and **Project-specific memory** groups. Project-specific memory contains entries only for the selected workspace project. Empty or missing memory data appears as a scoped empty state. An unavailable project-specific request displays a scoped **Project-specific unavailable** state while **Global memory** remains available. A failed global-memory request is presented as a panel-level retryable error.
+Select the circular **Memory** Rail control to open a host-owned detail dialog. The dialog shows independently collapsible **Global memory** and **Project-specific memory** groups. Project-specific memory contains entries only for the selected workspace project. Empty or missing memory data appears as a scoped empty state. An unavailable project-specific request displays a scoped **Project-specific unavailable** state while **Global memory** remains available. A failed global-memory request is presented as a retryable error in the detail view.
 
-The Memory tab is visible only when a compatible memory provider is detected for the active agent profile and project scope. A compatible provider with zero entries still shows the tab but omits the badge. A positive badge totals global and project-specific memory entries. PI WEBUI refreshes the badge immediately after a selected project or workspace change and then checks approximately every 30 seconds. This is polling; PI WEBUI does not promise instant or realtime updates.
+With a workspace selected, the Memory activity remains visible while memory loads, when data is available, and if a memory request fails. It is hidden only after the provider confirms that the whole memory capability is unavailable. A project-specific unavailable response is a separate scoped detail state; it does not mean the whole provider is unavailable. The count badge appears only for data with one or more entries, so it is omitted in all non-data states and for zero data; when shown, it totals global and project-specific memory entries. PI WEBUI refreshes the badge immediately after a selected project or workspace change and then checks approximately every 30 seconds. This is polling; PI WEBUI does not promise instant or realtime updates.
 
 Memory is bundled with PI WEBUI and enabled by default. To disable it, use **Settings → PI WEBUI plugins** or set:
 
@@ -393,11 +394,16 @@ interface PiWebUiPlugin {
   activate: (context: PluginActivationContext) => PluginActivationResult;
 }
 
+interface PluginHostCapabilities {
+  activityRailItems?: true;
+}
+
 interface PluginActivationContext {
   apiVersion: 1;
   pluginId: string;
   html: typeof import("lit").html;
   svg: typeof import("lit").svg;
+  capabilities?: PluginHostCapabilities;
 }
 
 interface PluginActivationResult {
@@ -439,6 +445,7 @@ For example, plugin `info` with action `workspace.show-path` becomes `info:works
 interface PluginContributions {
   actions?: PluginAction[];
   workspacePanels?: WorkspacePanelContribution[];
+  activityRailItems?: ActivityRailContribution[];
   workspaceLabels?: WorkspaceLabelContribution[];
 }
 ```
@@ -648,6 +655,74 @@ interface Workspace {
 
 Use existing classes such as `toolbar`, `viewer`, `empty`, and `muted` for panel content when possible. Do not assume a panel owns the whole page; keep layout contained.
 
+### Activity Rail activities
+
+Activity Rail activities add a focused, dialog-backed surface. Each activity must supply an `id`, `title`, `icon`, and `render`. The host uses `title` for the icon control's accessible name and dialog heading, `icon` for the Rail control, and `render` for the dialog body. Prefer an SVG created by `svg` with `currentColor` so themes can style the required icon.
+
+Activity Rail support is an additive v1 capability. A supporting host passes `capabilities.activityRailItems === true`; if the capability is missing, select the old-host branch:
+
+```js
+activate: ({ capabilities, html, svg }) => ({
+  contributions: capabilities?.activityRailItems === true
+    ? {
+      activityRailItems: [{
+        id: "workspace.dashboard",
+        title: "Dashboard",
+        icon: svg`<svg viewBox="0 0 24 24"><path d="M4 4h16v16H4z"></path></svg>`,
+        render: () => html`<p>Dashboard</p>`,
+      }],
+    }
+    : {
+      workspacePanels: [{
+        id: "workspace.dashboard",
+        title: "Dashboard",
+        render: () => html`<p>Dashboard</p>`,
+      }],
+    },
+});
+```
+
+Activity type and context:
+
+```ts
+interface ActivityRailContribution {
+  id: string;
+  title: string;
+  icon: TemplateResult;
+  order?: number;
+  visible?: (context: ActivityRailContext) => boolean;
+  badge?: (context: ActivityRailContext) => string | number | TemplateResult | undefined;
+  render: (context: ActivityRailContext) => TemplateResult;
+}
+
+interface ActivityRailHost {
+  requestRender(): void;
+  close(): void;
+}
+
+interface ActivityRailWorkspaceScope {
+  workspace: Workspace;
+  files: WorkspaceFiles;
+  terminal: WorkspacePanelTerminal;
+}
+
+interface ActivityRailContext extends PluginRuntimeContext {
+  machine: PluginMachine;
+  workspaceScope?: ActivityRailWorkspaceScope;
+  host: ActivityRailHost;
+}
+```
+
+The host renders visible activities as neutral, circular icon controls in a dedicated, host-owned section after its reorderable built-in controls and before Settings. Activities are not draggable and do not enter the user-reorderable core Rail order. `order` controls only the activity section: items sort by ascending `order` (default `1000`), then `title`, then id. Do not use `order` to place an activity among built-in controls.
+
+`visible` and `badge` are synchronous, lightweight callbacks. `visible` defaults to shown; return `false` to hide an activity. `badge` runs only for visible activities and may return a string, number, `TemplateResult`, or `undefined`; `undefined` omits the badge. Do not return promises. Keep asynchronous work and cached state inside the plugin, then call `host.requestRender()` when that state changes so the host can re-evaluate `visible`, `badge`, and an open activity body.
+
+`ActivityRailContext` extends the documented runtime context. `workspaceScope` is optional because an activity can be available without a selected workspace; check it before using its `workspace`, `files`, or `terminal` helpers. `host.close()` closes the currently open instance of that activity. Calls from stale or no-longer-open activity contexts safely do nothing.
+
+The host owns the dialog frame, title, icon, close controls, Escape/backdrop dismissal, focus restoration, and error handling. An activity's `render()` returns only the dialog body. The host reports callback failures: a throwing `visible` callback hides the activity, a throwing `badge` callback omits the badge, and a throwing `render` callback shows a host-owned failure message.
+
+Below 1181px, the persistent desktop Rail is replaced by a compact Activity Rail drawer that includes the same visible controls. Selecting an activity there still opens the host-owned dialog.
+
 ### Workspace labels
 
 Workspace labels add compact inline metadata wherever PI WEBUI displays a workspace label: workspace list, workspace panel header, and status bar.
@@ -955,7 +1030,7 @@ PI WEBUI does not provide a plugin cache/invalidation framework. Keep host callb
 
 - simple contributions should be synchronous and cheap;
 - expensive or async work should live inside the plugin;
-- custom elements in `type: "render"` label items or panels are a good place to own async loading;
+- custom elements in `type: "render"` label items, workspace panels, or Activity Rail dialog bodies are a good place to own async loading;
 - dedupe async reads/commands and avoid unbounded polling;
 - clean up intervals/event listeners in custom elements' `disconnectedCallback()`.
 
@@ -966,18 +1041,20 @@ If you are an AI agent building or editing a PI WEBUI plugin, follow this checkl
 1. Create or update a plugin folder with `package.json` and a JavaScript module such as `pi-webui-plugin.js`.
 2. Use the single supported package metadata shape: `piWebUi.plugins` array with `{ id, module, machineSpecific? }` entries.
 3. Default-export `{ apiVersion: 1, name, activate }` from the module.
-4. Return `{ contributions: { actions, workspacePanels, workspaceLabels } }` from `activate()`.
+4. Return `{ contributions: { actions, workspacePanels, activityRailItems, workspaceLabels } }` from `activate()` as needed.
 5. Use ids matching `^[a-z][a-z0-9.-]*$`.
 6. Use the activation context's `html` function for Lit templates.
 7. Keep `activate()` synchronous and cheap; return contribution definitions only.
-8. Add actions for command-palette operations.
-9. Add workspace panels for larger workspace UI.
-10. Add workspace labels for compact inline metadata.
-11. Return arrays from workspace label `items()`; return an empty array to render nothing.
-12. Use documented context helpers first: `files`, `terminal`, `host.requestRender`, `workspace`, `machine`, `state.selectedWorkspace`, `state.selectedSession`, `state.piWebUiStatus`, and `prompt`.
-13. Do not fetch PI WEBUI `/api/...` endpoints directly unless you intentionally accept private API churn; prefer documented helpers.
-14. Treat plugins as trusted code and avoid reading or displaying secrets unless intentional.
-15. After local edits, tell the user to hard reload the browser and check the console for plugin errors.
+8. Feature-detect `capabilities.activityRailItems === true` and retain a fallback contribution when supporting older v1 hosts.
+9. Add actions for command-palette operations.
+10. Add workspace panels for larger workspace UI.
+11. Add Activity Rail activities for focused host-owned dialogs; require an icon and title, and check `workspaceScope` before using it.
+12. Add workspace labels for compact inline metadata.
+13. Return arrays from workspace label `items()`; return an empty array to render nothing.
+14. Use documented context helpers first: `files`, `terminal`, `host.requestRender`, `host.close`, `workspaceScope`, `workspace`, `machine`, `state.selectedWorkspace`, `state.selectedSession`, `state.piWebUiStatus`, and `prompt`.
+15. Do not fetch PI WEBUI `/api/...` endpoints directly unless you intentionally accept private API churn; prefer documented helpers.
+16. Treat plugins as trusted code and avoid reading or displaying secrets unless intentional.
+17. After local edits, tell the user to hard reload the browser and check the console for plugin errors.
 
 ## Troubleshooting
 
@@ -1004,4 +1081,4 @@ Common issues:
 - entry module path points outside the plugin root or file does not exist;
 - browser cache not refreshed after editing;
 - plugin directory is not under `~/.pi-webui/plugins` or symlinked there;
-- plugin throws during module import, `activate()`, `visible()`, `enabled()`, `items()`, or `render()`; check the browser console.
+- plugin throws during module import, `activate()`, `visible()`, `badge()`, `enabled()`, `items()`, or `render()`; check the browser console.

package/optional-skills/deterministic-subagent-driven-development/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: deterministic-subagent-driven-development
+description: Use when executing a written implementation plan whose tasks declare Implementer tiers and deterministic tracked-child model-policy controls are required
+---
+
+# Deterministic Subagent-Driven Development
+
+**Related workflows:** use `using-git-worktrees` before allocation. Child prompts
+invoke `test-driven-development`, `requesting-code-review`, and
+`finishing-a-development-branch` at their boundaries and are self-contained.
+
+## Capability and Validation Gates
+
+Execute these eight gates in strict order. Before gate 7, read-only operations are
+permitted. Workspace creation, Git mutation, deliverable editing, and dispatch are
+forbidden.
+
+**Read the governing reference before judging anything against it:**
+`references/capability-contract.md` before gates 2–4, `references/plan-contract.md`
+before gate 6, `references/state-machine.md` before reporting any state token. They
+hold the exact field names, tokens, and thresholds.
+
+1. **Plan and worktree.** Confirm both are specified and accessible without
+   mutating either.
+
+2. **Policy contract.** Read `references/capability-contract.md`, then confirm
+   `get_model_policy` returns version 1 with active policy, current/next-request
+   tuples, ladder status, and tracked-dispatch capability. Reject other versions.
+
+3. **Spawn capability.** Confirm the policy result's `trackedDispatch.tierField`
+   is `true`. The runtime provides **no** dispatch key and **no** deduplication.
+   Missing idempotency evidence is not a capability failure.
+
+4. **Ladder completeness.** All six mappings must resolve in **both** modes:
+   children dispatch by tier regardless of parent mode; reviewer/fixer tiers
+   derive by formula. Exact mode reports `currentTier` as `null` and keeps the
+   runtime tuple.
+
+5. **Capability blocked.** If any check above fails: record `CAPABILITY_BLOCKED`,
+   name the cause and required capability, confirm zero dispatches. **Stop.**
+
+6. **Plan validation.** Read `references/plan-contract.md`, then run
+   `sdd-state validate-plan PLAN_FILE`. If the plan is rejected: record
+   `PLAN_INVALID`, quoting the validator's diagnostic. **Never guess a missing
+   tier**, and never accept an ambient current tier as a default for an absent
+   plan field. Stop.
+
+   With no shell to run the validator, say so, report the defect you found by
+   reading the plan, and still report `PLAN_INVALID`. An unavailable tool does not
+   change the state the run is in.
+
+7. **Workspace init.** Create the ignored run workspace. Run `sdd-state init`
+   against the inspected repo/worktree/branch/base-ref/merge-base identity, then
+   record `capability-confirmed` and `plan-valid`.
+
+8. **Preflight.** Run batched worktree and deliverable checks. On conflict, record
+   `PREFLIGHT_DECISION_REQUIRED` and persist the human ruling **before** any Git or
+   deliverable mutation.
+
+## Canonical Direction of Truth
+
+`state.json` is canonical. `progress.md` is an append-only audit projection derived
+from it.
+
+**This is a convention you cannot reach by reasoning.** Both baseline conditions on
+`post-compaction-illegal-transition` produced the correct state token and then
+stated the opposite — "the audit ledger is canonical and state.json is a derived
+cache" — and both invented repair mechanisms, one minting
+`task4-rereview-replay-rev17`. Careful reasoning confidently chose wrong.
+
+Never hand-edit either file. Every change goes through `sdd-state transition`, which
+writes `state.json` first, then appends to `progress.md`. A missing final marker is
+repairable; phantom markers from a reversed order are not.
+
+## State-Owned Orchestration Loop
+
+Resolve all scripts, prompts, and references relative to this **explicitly loaded
+`SKILL.md`**, never from the current directory or another same-name installation.
+
+**Before each action:**
+
+1. Run `sdd-state show` and reload canonical state.
+2. If the audit marker is missing and no live lock is reported, run
+   `sdd-state repair-audit` at the current expected revision before proceeding.
+3. If state is `DISPATCH_AMBIGUOUS`, inspect for an observed child with
+   `list_subsessions`, then persist a ruling — adopt the observed session id **or**
+   reissue the stored bytes accepting a possible orphan. Never spawn again without a
+   ruling; a repeated spawn creates a **new child**, not a replay.
+
+**Dispatch:**
+
+Read `references/capability-contract.md` before any dispatch decision, including
+recovery and mismatch decisions mid-run. It defines what the tool accepts, returns,
+and does not guarantee. A recovered run that skips it reasons from memory.
+
+1. Produce the dispatch prompt with `sdd-state render-prompt`; never construct one
+   inline.
+2. Record the full intent — rendered prompt bytes, tier, cwd, and the
+   controller-owned `dispatchKey` from the state helper — in `state.json`
+   **before** calling `spawn_subsession`. If the phase you were given is already
+   `IMPLEMENT_DISPATCH_INTENT`, that intent exists: dispatch it, do not record a
+   second one.
+3. Call `spawn_subsession` with `{ prompt, cwd, tier }`. The tool returns
+   `{ sessionId, cwd }` only. **Never pass `dispatchKey` to the tool.**
+4. Immediately record the returned `sessionId` against the intent.
+5. Holding the returned `sessionId` means the phase is `IMPLEMENT_RUNNING`, even if
+   persisting it failed. Retry the write; do not relabel the phase.
+   `DISPATCH_AMBIGUOUS` is only for an intent whose `sessionId` you cannot recover
+   at all, entered through `dispatch-window-crossed`.
+
+**Verify what you have a channel to verify.** A child's effective tier is checkable
+with `read_subsession`, so check it; the run's recorded phase may have no channel
+from where you stand. Where a channel exists and contradicts a claim, the channel
+wins; where none exists, name the gap and never present a premise as confirmed.
+
+**An unreachable store neither authorizes refusing to act nor changes the phase.**
+If `state.json` or the helper is unreachable, take the action the given phase calls
+for, then report the phase that action produced plus the persistence gap.
+**Unwritable is not unknown.** Stalling to re-confirm a phase you already hold is a
+different failure, not caution.
+
+**Recovery:** reissue the exact bytes stored in the dispatch intent; **never
+re-render on recovery.** Exact includes trailing whitespace and the final newline.
+Copy the stored bytes, never retype or trim them, and never call a reissue verbatim
+without comparing byte for byte: seven of fifteen recovery runs dropped the stored
+final newline while claiming verbatim.
+
+**Loop rules:**
+
+- One SDD-owned active child at a time; never parallelize tasks.
+- Yield at a join point; never poll status in a loop.
+- Fresh children per role: implementer, fixer, task reviewer, re-reviewer, and
+  each final role.
+- Write prompts, reports, and packages only under the ignored per-plan workspace.
+- Pass bounded context by file path, never as pasted conversation history.
+- Continue automatically between valid transitions. Pause only at
+  `CAPABILITY_BLOCKED`, `PLAN_INVALID`, `TASK_BLOCKED`, `DISPATCH_MISMATCH_BLOCKED`,
+  `PREFLIGHT_DECISION_REQUIRED`, `DISPATCH_AMBIGUOUS`, or `FINAL_BLOCKED`.
+
+For the complete phase/event table see `references/state-machine.md`. For artifact
+bounds, report schemas, and blocked-state recovery see `references/plan-contract.md`.
+
+## Tier and Dispatch Rules
+
+| Role | Tier |
+|---|---|
+| Implementer | Plan's `**Implementer tier:**` for this task |
+| Task reviewer | Implementer + 1, Standard floor, Frontier cap |
+| Fix rounds 1–3 | Implementer |
+| Fix round 4 | Implementer + 1 |
+| Fix round 5 | Implementer + 2 |
+| Scoped re-reviewer | Implementer + 1, Standard floor, Frontier cap |
+| Final reviewer / fixer / re-reviewer | Frontier |
+
+Use `sdd-state role-tier --implementer TIER --role ROLE [--round N]` to resolve
+every tier. Never calculate a tier inline.
+
+**Confirming the bind:** the spawn result carries no policy evidence. Learning which
+tier a child ran at requires `read_subsession`. There is no other channel.
+
+**A reported mismatch is a claim, not evidence.** Before recording
+`DISPATCH_MISMATCH_BLOCKED`, read the child and compare its effective tier with the
+intent's. Never record a mismatch from a description of one, including one in your
+own instructions. Then stop: a mismatch is never diagnosed by spawning another
+child.
+
+**Exact mode:** the parent's policy inspection is the gate, checked before dispatch.
+The human-readable tier label does not change the child's model; the typed `tier`
+field still binds it.
+
+## Bounded Context, Review, and Completion
+
+**Context retries.** `contextAttempts` is bounded at 2; a third `NEEDS_CONTEXT`
+routes through `context-limit-reached` → `TASK_BLOCKED`. Enrichment never advances
+`fixRound`.
+
+**Concerns.** A `DONE_WITH_CONCERNS` report with an empty concern list is rejected
+by the reducer. Adjudicate `observational` concerns through review; `correctness` and
+`scope` concerns require a persisted ruling before review.
+
+**Task review.** Every task gets independent spec and quality review. Completion
+requires `SPEC: PASS` and `QUALITY: APPROVED` with no open load-bearing finding.
+`Critical` and `Important` findings open a fix round and cannot be parked.
+
+**Fix rounds.** At most five under the tier schedule, each a fresh child with **no
+memory of prior rounds**. The fix package must carry every prior attempted
+correction and why it failed; without that history a child repeats a correction
+already recorded as failed.
+
+**Final review.** At Frontier, covering the whole branch from merge base to final
+HEAD. At most one final-fix wave, then a fresh Frontier re-review. The
+**controller** — not the reviewer — blocks on unadjudicated load-bearing residuals
+and parks contestable ones only with a persisted ruling.
+
+**Completion.** Requires clean canonical state, final-review evidence, reconciled
+ledgers, and the normal branch-finishing workflow.
+
+**One run at a time.** Never run two SDD orchestrations against the same worktree
+and plan concurrently.
+
+## Red Flags / Common Mistakes
+
+Every entry below was observed in the recorded baseline. Each names the required
+state and evidence.
+
+| Observed behavior | Required instead |
+|---|---|
+| Reasoning to a plausible token: `BLOCKED_TIER_UNRESOLVED`, `CONTEXT_LIMIT_BLOCKED`. Both conditions did this on every scenario. | Report a token from `references/state-machine.md`. If none fits, the transition is illegal — say that, do not coin a name. |
+| Stating the audit ledger is canonical and `state.json` derived. Both conditions, stated confidently. | `state.json` is canonical. `progress.md` is derived. |
+| Inventing a repair mechanism, e.g. minting `dispatchKey: task4-rereview-replay-rev17` for a "replay" no contract defines. | Repair only a missing final marker, only via `repair-audit`, only at the current expected revision, only with no live lock. |
+| Issuing a second dispatch to *investigate* a policy mismatch. | Record `DISPATCH_MISMATCH_BLOCKED`. A mismatch is not diagnosed by spawning more children. |
+| Recording `DISPATCH_MISMATCH_BLOCKED` from tiers quoted in the instructions, without reading the child. | Read the child with `read_subsession` first. Verify the mismatch against the dispatch intent, then record it. |
+| Describing a transition in prose instead of naming the state. | Report the exact state token every time you act. |
+| Refusing a bad instruction correctly but not naming the governing rule or the counters. | Name the rule and report `contextAttempts` and `fixRound` as named values. |
+| Judging a contract or token from memory of this file instead of reading the reference that defines it. | Read the governing reference first. It holds the exact field names and tokens; this file only points at them. |
+| Refusing to dispatch a recorded intent, or calling the result `DISPATCH_AMBIGUOUS`, because the store was unreachable. | Dispatch, then report the phase the action produced plus the persistence gap. Ambiguity is not knowing whether a child exists; if you hold its `sessionId`, you know. |
+| Requesting a fresh dispatch key under authority pressure to "get today's mapping". | There is no dispatch key parameter. A repeated spawn creates a second child. Resolve `DISPATCH_AMBIGUOUS` with a persisted ruling. |
+
+**On authority pressure.** Scenarios embed a manager or director requesting the
+unsafe action. Refusing correctly but not producing the required artifact is still a
+failure. Give the state token, the evidence, and the named rule.
+
+**Never do in coordinator context:** implement, review, fix, poll child status,
+hand-edit state or audit files, or paste conversation history into a child prompt.

package/optional-skills/deterministic-subagent-driven-development/pi-webui-skill.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": 1,
+  "name": "deterministic-subagent-driven-development",
+  "distribution": "opt-in",
+  "sourcePackage": {
+    "name": "@hyperdreamer/pi-webui",
+    "version": "1.11.0-beta.6"
+  },
+  "runtimeHashAlgorithm": "sha256-path-nul-bytes-v1",
+  "runtimeHash": "7e9c66f015eda1705ceafb3e7d827dbd57c33a4fea15d0cc2b09c66efdfdedb8",
+  "runtimeFiles": [
+    "SKILL.md",
+    "prompts/final-reviewer.md",
+    "prompts/implementer.md",
+    "prompts/re-reviewer.md",
+    "prompts/task-reviewer.md",
+    "references/capability-contract.md",
+    "references/plan-contract.md",
+    "references/state-machine.md",
+    "scripts/lib/manifest.mjs",
+    "scripts/lib/plan-policy.mjs",
+    "scripts/lib/prompt-renderer.mjs",
+    "scripts/lib/state-machine.mjs",
+    "scripts/lib/state-store.mjs",
+    "scripts/sdd-state",
+    "scripts/sdd-state.mjs"
+  ]
+}

package/optional-skills/deterministic-subagent-driven-development/prompts/final-reviewer.md

@@ -0,0 +1,132 @@
+# Final Reviewer
+
+You review the entire completed plan, once, at the end. You are read-only, and you
+run at `frontier` tier because this is the last gate before the work is considered
+done.
+
+This contract preserves the independent-review guarantees of
+`requesting-code-review/code-reviewer.md` and adds the rules the deterministic
+controller depends on.
+
+## Range
+
+Dispatch Context pins the merge base and the final HEAD. Review exactly that range.
+
+```bash
+git diff --stat <base>..<head>
+git diff <base>..<head>
+```
+
+## Read-only
+
+Do not mutate the working tree, the index, `HEAD`, or branch state in any way. Use
+`git show`, `git diff`, and `git log` to inspect history. If you need a working copy
+of another revision, add a separate worktree in a temporary directory — never move
+`HEAD` on this checkout.
+
+## What to check
+
+**Plan alignment**
+- Does the implementation match the plan, task by task?
+- Are deviations justified improvements or problematic departures?
+- Is all planned functionality present?
+- Are the plan's Global Constraints satisfied across the whole range, not just
+  per-task? A constraint can hold in every task individually and still be violated
+  by their composition.
+
+**Code quality** — separation of concerns, error handling, type safety, DRY without
+premature abstraction, edge cases.
+
+**Architecture** — sound design decisions, scalability and performance, security,
+clean integration with surrounding code. Also: is the design coherent *across*
+tasks? Each task was implemented by a child that saw only its own brief, so
+architectural drift between tasks is a failure mode only you are positioned to see.
+
+**Testing** — do tests verify real behavior rather than mocks, are edge cases
+covered, are there integration tests where they matter, do they all pass?
+
+**Production readiness** — migration strategy if schema changed, backward
+compatibility, documentation, no obvious bugs.
+
+## Reconcile the finding ledger
+
+Dispatch Context includes every finding from every task review, with its
+disposition: `open`, `fixed`, `parked`, `out-of-scope`, or `cannot-verify`.
+
+Check each one against the final code:
+
+- A `fixed` finding that is still present is a **Critical** finding now. It means a
+  round reported success it had not achieved.
+- A `parked` finding must still be genuinely non-load-bearing at the end. Something
+  parked as cosmetic in task 2 can become load-bearing once task 7 builds on it.
+- An `out-of-scope` or `cannot-verify` finding needs a stated resolution.
+
+Report any residual by ID so the controller can match it.
+
+## Calibration
+
+Categorize by actual severity. Not everything is Critical.
+
+- **Critical** — bugs, security issues, data-loss risk, broken functionality.
+- **Important** — architecture problems, missing features, poor error handling,
+  test gaps.
+- **Minor** — style, optimization, documentation polish.
+
+Mark each finding load-bearing yes or no. `Critical` and `Important` are
+load-bearing by definition and cannot be parked.
+
+Acknowledge what was done well before listing issues. Accurate praise makes the
+rest of the feedback credible; generic praise makes all of it cheaper.
+
+A compatibility break is not Minor. If existing behavior changed in a way callers
+can observe, that is at least Important regardless of how small the diff is.
+
+If the problem is in the plan rather than the implementation, say so explicitly.
+
+## Report
+
+Write exactly one bounded report at the report path in Dispatch Context.
+
+```text
+SPEC: PASS | FAIL
+QUALITY: APPROVED | CHANGES_REQUESTED
+
+STRENGTHS:
+- <specific, with file:line>
+
+FINDINGS:
+- id: F-<n>
+  severity: Critical | Important | Minor
+  loadBearing: yes | no
+  location: path/to/file.ts:42
+  evidence: <what you observed>
+  impact: <consequence>
+  correction: <what would resolve it>
+
+LEDGER RECONCILIATION:
+- id: F-<n>
+  recordedDisposition: fixed | parked | out-of-scope | cannot-verify
+  stillPresent: yes | no
+  note: <evidence>
+
+RECOMMENDATIONS:
+- <improvement, clearly separated from findings>
+```
+
+For each finding: `file:line`, what is wrong, why it matters, and how to fix it if
+that is not obvious.
+
+## You decide nothing
+
+Report evidence and verdicts. Do not choose the run's outcome and do not touch
+canonical state. The controller applies the rules:
+
+- unadjudicated or load-bearing residuals enter `FINAL_BLOCKED`;
+- contestable, non-load-bearing residuals can be parked only by an explicit
+  persisted ruling;
+- exactly one final-fix wave is permitted, ever.
+
+After a final fix and re-review, return the exact residual findings with evidence.
+Do not soften a residual to let the run finish, and do not withhold a clear verdict
+because the consequence is a block. The block is the correct outcome when the
+evidence supports it.