repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

fix: update ultra authoring and pulse completions

bac700bb55b24ad544f878bc1d42b11cce3977d2

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (46)

CHANGELOG.md

Modified
21 21 - Remove unused The System renderer dependencies
22 22 - Add terse artifact detail budgets for System docs; plans stay at module/interface/package/class level and avoid real code snippets
23 23 - Fix The System runtime warning so it stays quiet until a project opts into `.system`
24 +- Add `/ultra runs` to inspect, stop, delete, and resume saved Ultra runs
25 +- Add `/ultra` autocomplete for saved workflows and the `runs` subcommand
26 +- Fix Ultra tool-step cleanup so teardown errors do not hide a completed workflow step
27 +- Remove Ultra's exported authoring skill; `/ultra` now injects the workflow authoring prompt internally
28 +- Keep Ultra's `workflow` tool hidden until `/ultra` activates it
29 +- Fix Pulse TAB completion
25 31 ## 0.0.3

README.md

Modified
113 113 ```json
115 115 "extensions": ["extensions/*/index.ts"],
116 - "skills": ["extensions/ultra/skills", "extensions/lazy/skills"]
116 + "skills": ["extensions/lazy/skills"]

docs/super/plans/2026-06-22-goldfish.md

Modified
15 15 **Phase:** Single-plan implementation
17 +**Status:** Reconciled on 2026-08-10 against current code and history; `extensions/goldfish` exists and the task-gate experiment shipped.
19 21 ## File Map
78 80 - Create: `extensions/goldfish/index.ts`
79 81 - Test: `extensions/goldfish/__tests__/harness.test.ts`
81 -- [ ] **Step 1: Delete old extension**
83 +- [x] **Step 1: Delete old extension**
86 88 rm -rf extensions/forget
89 -- [ ] **Step 2: Create package metadata**
91 +- [x] **Step 2: Create package metadata**
91 93 Write `extensions/goldfish/package.json`:
113 -- [ ] **Step 3: Create README**
115 +- [x] **Step 3: Create README**
115 117 Write `extensions/goldfish/README.md`:
125 127 The widget shows current state above the editor.
128 -- [ ] **Step 4: Write failing harness test**
130 +- [x] **Step 4: Write failing harness test**
130 132 Write `extensions/goldfish/__tests__/harness.test.ts`:
159 161 Expected: fail because `extensions/goldfish/index.ts` does not exist.
161 -- [ ] **Step 5: Create minimal extension**
163 +- [x] **Step 5: Create minimal extension**
163 165 Write `extensions/goldfish/index.ts`:
183 185 - Modify: `extensions/goldfish/index.ts`
184 186 - Test: `extensions/goldfish/__tests__/goldfish.test.ts`
186 -- [ ] **Step 1: Write failing state tests**
188 +- [x] **Step 1: Write failing state tests**
188 190 Write tests for:
202 204 Expected: fail because helpers are missing.
204 -- [ ] **Step 2: Implement pure state helpers**
206 +- [x] **Step 2: Implement pure state helpers**
206 208 Add event types, `createState()`, `applyEvent()`, `replayGoldfish()`, `currentTask()`, and export them under `__test`.
220 222 - Modify: `extensions/goldfish/index.ts`
221 223 - Test: `extensions/goldfish/__tests__/goldfish.test.ts`
223 -- [ ] **Step 1: Write failing tool tests**
225 +- [x] **Step 1: Write failing tool tests**
231 233 - check exit `2` abandons.
232 234 - check timeout abandons.
234 -- [ ] **Step 2: Implement `goldfish` tool**
236 +- [x] **Step 2: Implement `goldfish` tool**
236 238 Use a single `task` tool with `action` enum.
237 239 Return structured `details`.
241 243 - expanded: full task context and check output.
242 244 - expansion hint uses `keyHint("app.tools.expand", "to expand")` if available in current imports/patterns.
244 -- [ ] **Step 3: Verify tests**
246 +- [x] **Step 3: Verify tests**
258 260 - Modify: `extensions/goldfish/index.ts`
259 261 - Test: `extensions/goldfish/__tests__/goldfish.test.ts`
261 -- [ ] **Step 1: Write failing visibility tests**
263 +- [x] **Step 1: Write failing visibility tests**
263 265 Test a fake `ExtensionAPI` with active tools:
266 268 - active => normal tools plus `task` allowed.
267 269 - active tool baseline excludes tools not active at session start.
269 -- [ ] **Step 2: Write failing hard-gate tests**
271 +- [x] **Step 2: Write failing hard-gate tests**
271 273 Test `beforeToolCall`/`tool_call` handler logic:
274 276 - idle task is allowed.
275 277 - active non-task is allowed.
277 -- [ ] **Step 3: Implement visibility and gate**
279 +- [x] **Step 3: Implement visibility and gate**
279 281 Use `pi.getActiveTools()` / `pi.setActiveTools()`.
280 282 Capture baseline after registering `task` on `session_start`.
295 297 - Modify: `extensions/goldfish/index.ts`
296 298 - Test: `extensions/goldfish/__tests__/goldfish.test.ts`
298 -- [ ] **Step 1: Write failing widget tests**
300 +- [x] **Step 1: Write failing widget tests**
304 306 - expanded lines show id, title, done command, timeout, checks, tool calls, last result.
305 307 - widget output truncates to width.
307 -- [ ] **Step 2: Implement widget**
309 +- [x] **Step 2: Implement widget**
309 311 Follow `notes` and `goal`:
328 330 - Modify: `extensions/goldfish/index.ts`
329 331 - Test: `extensions/goldfish/__tests__/goldfish.test.ts`
331 -- [ ] **Step 1: Write failing guidance tests**
333 +- [x] **Step 1: Write failing guidance tests**
333 335 Test generated guidance text:
336 338 - active: says current task and done command.
337 339 - blocked tool response tells model exact next allowed action.
339 -- [ ] **Step 2: Inject guidance at correct time**
341 +- [x] **Step 2: Inject guidance at correct time**
341 343 Use `before_agent_start` or `context` event to prepend/append a short state block.
342 344 Keep it under 12 lines.
357 359 - Modify as failures indicate.
359 -- [ ] **Step 1: Run smoke without active task**
361 +- [x] **Step 1: Run smoke without active task**
367 369 Expected: model must call `task.create` before file tools are usable.
369 -- [ ] **Step 2: Run smoke with achievable task**
371 +- [x] **Step 2: Run smoke with achievable task**
377 379 Expected: task is created, normal tool is used, check closes.
379 -- [ ] **Step 3: Iterate until smoke behavior is sane**
381 +- [x] **Step 3: Iterate until smoke behavior is sane**
381 383 If the model fails to create tasks, strengthen guidance and hidden-tool behavior.
382 384 If rendering is noisy, tighten collapsed render output.

docs/super/plans/2026-06-29-ultra-subagent-extensions.md

Modified
9 9 **Tech Stack:** TypeScript, Pi coding-agent SDK (`@earendil-works/pi-coding-agent`), TypeBox, vitest, biome, dprint, markdownlint.
11 +**Status:** Reconciled on 2026-08-10 against current code; checkboxes reflect present repo state, not original execution order.
11 13 ## Global Constraints
13 15 - **Default `subagentExtensions` is `"all"`**; `"none"` is the opt-out. The setting union is exactly `"none" | "all"`.
30 32 - Temporarily modify: `extensions/ultra/drivers.ts:62` (revert at the end)
31 33 - Scratch: `<scratchpad>/spike-web.json`
33 -- [ ] **Step 1: Temporarily force extensions on**
35 +- [x] **Step 1: Temporarily force extensions on**
35 37 In `extensions/ultra/drivers.ts`, change line 62 from `noExtensions: true,` to `noExtensions: false,`. (Leave the other `no*` flags `true`.) This is a throwaway hack reverted in Step 5.
37 -- [ ] **Step 2: Write the spike workflow spec**
39 +- [x] **Step 2: Write the spike workflow spec**
39 41 Write `<scratchpad>/spike-web.json`:
57 -- [ ] **Step 3: Run headless and observe**
59 +- [x] **Step 3: Run headless and observe**
59 61 Run (the prompt forces the model to call the `workflow` tool with the inline spec):
65 67 Expected (the two assumptions): the probe agent reports **`search=ok`** (web_search ran AND returned results → auth/activation carried into the isolated sub-agent) and **`fetch=unavailable`** (web_fetch was NOT allowlisted → the allowlist gates _extension_ tools, not just core ones).
67 -- [ ] **Step 4: Record the result**
69 +- [x] **Step 4: Record the result**
69 71 Note in your working notes: did `search=ok`? did `fetch=unavailable`? These are the two kill criteria below.
71 -- [ ] **Step 5: Revert the hack**
73 +- [x] **Step 5: Revert the hack**
73 75 Restore `extensions/ultra/drivers.ts:62` to `noExtensions: true,`. Confirm `git diff extensions/ultra/drivers.ts` is empty.
92 94 - Produces: `UltraSettings.subagentExtensions: "none" | "all"`; `ULTRA_DEFAULTS.subagentExtensions === "all"`. Consumed by Task 5 (`index.ts`).
94 -- [ ] **Step 1: Write the failing tests**
96 +- [x] **Step 1: Write the failing tests**
96 98 Add to `extensions/ultra/__tests__/settings.test.ts`:
137 139 - Any `mergeUltraSettings(...)` test that asserts a full literal object (around line 78-84) — add `subagentExtensions: "all",`.
138 140 - Any `loadUltraSettings(...)` test asserting a full literal object (around line 138-143) — add `subagentExtensions: "all",`. (Tests that assert `toEqual(ULTRA_DEFAULTS)` need no change — they reference the constant.)
140 -- [ ] **Step 2: Run to verify failure**
142 +- [x] **Step 2: Run to verify failure**
142 144 Run: `npx vitest run extensions/ultra/__tests__/settings.test.ts`
143 145 Expected: FAIL (`subagentExtensions` undefined / property missing).
145 -- [ ] **Step 3: Implement**
147 +- [x] **Step 3: Implement**
147 149 In `extensions/ultra/settings.ts`:
178 180 : into.subagentExtensions,
181 -- [ ] **Step 4: Run to verify pass**
183 +- [x] **Step 4: Run to verify pass**
183 185 Run: `npx vitest run extensions/ultra/__tests__/settings.test.ts`
184 186 Expected: PASS.
186 -- [ ] **Step 5: Commit** (staged; run `git commit` only on user approval)
188 +- [x] **Step 5: Commit** (staged; run `git commit` only on user approval)
188 190 ```bash
189 191 git add extensions/ultra/settings.ts extensions/ultra/__tests__/settings.test.ts
204 206 - Consumes: nothing new.
205 207 - Produces: `SessionFactoryDeps.loadExtensions?: boolean`. The factory sets `noExtensions: !loadExtensions` (omitted dep ⇒ `noExtensions: true`). Consumed by Task 5.
207 -- [ ] **Step 1: Write the failing test**
209 +- [x] **Step 1: Write the failing test**
209 211 Add to `extensions/ultra/__tests__/drivers.test.ts` (mirror the existing `makeSessionFactory` test's `FakeLoader` + `createAgentSession` fakes; capture the loader opts):
247 249 (The existing test that asserts `noExtensions: true` with no `loadExtensions` dep stays valid — `!undefined === true`.)
249 -- [ ] **Step 2: Run to verify failure**
251 +- [x] **Step 2: Run to verify failure**
251 253 Run: `npx vitest run extensions/ultra/__tests__/drivers.test.ts`
252 254 Expected: FAIL (`loaderOpts.noExtensions` is `true`, not `false`).
254 -- [ ] **Step 3: Implement**
256 +- [x] **Step 3: Implement**
256 258 In `extensions/ultra/drivers.ts`, add to `SessionFactoryDeps`:
267 269 noExtensions: !deps.loadExtensions,
270 -- [ ] **Step 4: Run to verify pass**
272 +- [x] **Step 4: Run to verify pass**
272 274 Run: `npx vitest run extensions/ultra/__tests__/drivers.test.ts`
273 275 Expected: PASS (both the new test and the existing `noExtensions: true` test).
275 -- [ ] **Step 5: Commit** (staged; gated)
277 +- [x] **Step 5: Commit** (staged; gated)
277 279 ```bash
278 280 git add extensions/ultra/drivers.ts extensions/ultra/__tests__/drivers.test.ts
293 295 - Produces: `ULTRA_OWN_TOOL_NAMES` (exported const). The tools passed to `sessionFactory` become `[...step.tools without any ULTRA_OWN_TOOL_NAMES, STRUCTURED_OUTPUT_TOOL_NAME]`.
295 -- [ ] **Step 1: Write the failing test**
297 +- [x] **Step 1: Write the failing test**
297 299 Add to `extensions/ultra/__tests__/runner.test.ts` (in the tool-using `sessionFactory` describe block; reuse the existing `harness`):
322 324 (Use the same harness/`makeDrivers`/`ctxLike`/`baseOpts` helpers the existing tool-using tests use — match their exact names from the top of the file.)
324 -- [ ] **Step 2: Run to verify failure**
326 +- [x] **Step 2: Run to verify failure**
326 328 Run: `npx vitest run extensions/ultra/__tests__/runner.test.ts`
327 329 Expected: FAIL (`args.tools` is `["read","workflow",structured_output]`).
329 -- [ ] **Step 3: Implement**
331 +- [x] **Step 3: Implement**
331 333 In `extensions/ultra/runner.ts`, near `STRUCTURED_OUTPUT_TOOL_NAME`:
348 350 tools: [...sanitizeSubagentTools(step.tools), STRUCTURED_OUTPUT_TOOL_NAME],
351 -- [ ] **Step 4: Run to verify pass**
353 +- [x] **Step 4: Run to verify pass**
353 355 Run: `npx vitest run extensions/ultra/__tests__/runner.test.ts`
354 356 Expected: PASS (new test green; existing tools assertions unaffected — they list no `workflow`).
356 -- [ ] **Step 5: Commit** (staged; gated)
358 +- [x] **Step 5: Commit** (staged; gated)
358 360 ```bash
359 361 git add extensions/ultra/runner.ts extensions/ultra/__tests__/runner.test.ts
374 376 - Consumes: `cfg.subagentExtensions` (Task 2), `SessionFactoryDeps.loadExtensions` (Task 3).
376 -- [ ] **Step 1: Wire it**
378 +- [x] **Step 1: Wire it**
378 380 In `extensions/ultra/index.ts`, in the `makeSessionFactory({ ... })` call inside `buildStepRunner`, add the dep (alongside `cwd`, `modelRegistry`):
384 386 (No unit test: `index.ts` is thin SDK glue — its own module comment notes the harness asserts registration only. The behaviour is covered by Tasks 2–4 + the Task 1 spike.)
386 -- [ ] **Step 2: Document the setting + portability contract**
388 +- [x] **Step 2: Document the setting + portability contract**
388 390 In `extensions/ultra/README.md` Settings section, add a short paragraph:
398 400 extension provides simply runs without it.
401 -- [ ] **Step 3: Full CI green**
403 +- [x] **Step 3: Full CI green**
403 405 If present, move the gitignored local settings aside first:
410 412 Expected: lint 0 errors, all tests pass (settings/drivers/runner additions included), checks OK. Restore the file afterward if moved.
412 -- [ ] **Step 4: Commit** (staged; gated)
414 +- [x] **Step 4: Commit** (staged; gated)
414 416 ```bash
415 417 git add extensions/ultra/index.ts extensions/ultra/README.md

docs/super/plans/2026-07-11-accepted-mockup-artifacts.md

Modified
13 13 **Phase:** Single-plan implementation
15 +**Status:** Reconciled on 2026-08-10 against current code and history; accepted mockup artifact persistence shipped.
17 19 ## Tasks
23 25 - Modify: `extensions/super/skills/brainstorming/SKILL.md`
24 26 - Test: `extensions/super/__tests__/workflow-skills.test.ts`
26 -- [ ] **Step 1: Write the failing workflow contract test**
28 +- [x] **Step 1: Write the failing workflow contract test**
28 30 Add this test inside `describe("super workflow phase skills", ...)`:
46 -- [ ] **Step 2: Run the test to verify it fails**
48 +- [x] **Step 2: Run the test to verify it fails**
54 56 Expected: FAIL because the brainstorming skill does not yet define accepted mockup artifact persistence.
56 -- [ ] **Step 3: Add the minimal workflow instructions**
58 +- [x] **Step 3: Add the minimal workflow instructions**
58 60 Add this subsection after the Visual Companion result-handling instructions in `extensions/super/skills/brainstorming/SKILL.md`:
88 90 Commit the spec and accepted mockup artifacts together.
91 -- [ ] **Step 4: Run the focused tests**
93 +- [x] **Step 4: Run the focused tests**
99 101 Expected: PASS.
101 -- [ ] **Step 5: Run repository verification**
103 +- [x] **Step 5: Run repository verification**
109 111 Expected: formatting, lint, tests, static checks, and integration checks pass.
111 -- [ ] **Step 6: Commit the implementation**
113 +- [x] **Step 6: Commit the implementation**
113 115 Stage only the plan, skill, and workflow test; preserve unrelated dirty files:

docs/super/plans/2026-07-11-shame-command.md

Modified
13 13 **Phase:** Single-plan implementation
15 +**Status:** Reconciled on 2026-08-10 against history; `/shame` shipped, then the legacy extension was retired by `overkill`/current review tooling.
17 19 ## Task 1: Rename the extension
26 28 - Modify: `CHANGELOG.md`
27 29 - Modify: `package-lock.json`
29 -- [ ] **Step 1: Rename the directory and package**
31 +- [x] **Step 1: Rename the directory and package**
49 51 "Shame code. Usage: /shame [@path ...|#pr|pr-url|git-ref] [--extra <focus>]",
52 -- [ ] **Step 2: Rename test imports and the load test**
54 +- [x] **Step 2: Rename test imports and the load test**
54 56 Use these names in `extensions/shame/__tests__/harness.test.ts`:
67 -- [ ] **Step 3: Update repository metadata**
69 +- [x] **Step 3: Update repository metadata**
69 71 Replace the root README row with:
83 85 Expected: `package-lock.json` contains `extensions/shame` and `@bugabinga/pi-ext-shame`, with no review workspace entry.
85 -- [ ] **Step 4: Run the renamed harness test**
87 +- [x] **Step 4: Run the renamed harness test**
93 95 Expected: all existing parser and extension-load assertions pass, and no import path references `extensions/review`.
95 -- [ ] **Step 5: Commit the rename**
97 +- [x] **Step 5: Commit the rename**
97 99 ```bash
98 100 git add CHANGELOG.md README.md package-lock.json extensions/review extensions/shame
106 108 - Modify: `extensions/shame/index.ts`
107 109 - Modify: `extensions/shame/__tests__/harness.test.ts`
109 -- [ ] **Step 1: Replace parser tests with failing inferred-target tests**
111 +- [x] **Step 1: Replace parser tests with failing inferred-target tests**
111 113 Expose `parseInput` and `resolveTarget` through `__test`.
112 114 Add tests using a temporary Git repository created inside the harness cwd:
130 132 Add async resolver assertions for `@src`, multiple paths, a plain existing path, a local branch, a commit SHA, a missing path, and mixed path/ref tokens.
131 133 Use `pi.exec("git", ["init", "-b", "trunk"])`, configure a local test identity, create one commit, and create branch `feature`.
133 -- [ ] **Step 2: Run tests to verify failure**
135 +- [x] **Step 2: Run tests to verify failure**
141 143 Expected: FAIL because `parseInput`, `pullRequestRef`, and `resolveTarget` do not exist.
143 -- [ ] **Step 3: Implement flag parsing and target resolution**
145 +- [x] **Step 3: Implement flag parsing and target resolution**
145 147 Replace `ParsedReviewArgs` with:
195 197 Keep prompt generation unchanged except `/review` wording becomes `/shame` where user-visible.
197 -- [ ] **Step 4: Run resolver tests**
199 +- [x] **Step 4: Run resolver tests**
205 207 Expected: all inferred-target and existing prompt/load tests pass.
207 -- [ ] **Step 5: Commit inference**
209 +- [x] **Step 5: Commit inference**
209 211 ```bash
210 212 git add extensions/shame/index.ts extensions/shame/__tests__/harness.test.ts
218 220 - Modify: `extensions/shame/index.ts`
219 221 - Modify: `extensions/shame/__tests__/harness.test.ts`
221 -- [ ] **Step 1: Add failing completion tests**
223 +- [x] **Step 1: Add failing completion tests**
223 225 Create `src/`, `src/nested/`, and a local `feature` branch in the harness cwd.
224 226 Fetch the command from the loaded extension and assert:
242 244 Also assert suggestions for empty input include `--extra` and `#123` examples.
244 -- [ ] **Step 2: Run tests to verify failure**
246 +- [x] **Step 2: Run tests to verify failure**
252 254 Expected: FAIL because `/shame` has no `getArgumentCompletions`.
254 -- [ ] **Step 3: Implement completion**
256 +- [x] **Step 3: Implement completion**
256 258 Track the active cwd from `session_start` and initialize it to `process.cwd()`.
257 259 Add `completeArguments(cwd, argumentText)` using `readdirSync(..., { withFileTypes: true })` for the active `@` token and `execFileSync("git", ["for-each-ref", "--format=%(refname:short)", "refs/heads", "refs/remotes"], { cwd, encoding: "utf8" })` for branch names.
270 272 Do not walk the repository recursively; list only the active directory.
272 -- [ ] **Step 4: Run focused tests and formatting**
274 +- [x] **Step 4: Run focused tests and formatting**
282 284 Expected: all commands exit 0 and formatting leaves the focused test green.
284 -- [ ] **Step 5: Commit completion**
286 +- [x] **Step 5: Commit completion**
286 288 ```bash
287 289 git add extensions/shame/index.ts extensions/shame/__tests__/harness.test.ts
295 297 - Verify: all modified files
297 -- [ ] **Step 1: Search for stale names**
299 +- [x] **Step 1: Search for stale names**
305 307 Expected: no stale extension or command references.
307 -- [ ] **Step 2: Run the release gate**
309 +- [x] **Step 2: Run the release gate**
315 317 Expected: lint, all tests, and static extension checks pass.
317 -- [ ] **Step 3: Inspect final state**
319 +- [x] **Step 3: Inspect final state**

docs/super/plans/2026-07-12-mise-task-architecture-phase-1-monorepo-foundation-and-benchmarks.md

Modified
13 13 **Phase:** Phase 1: Monorepo Foundation And Benchmarks
15 +**Status:** Reconciled on 2026-08-10 against current mise tasks and history; phase work shipped.
17 19 ## File Structure
51 53 - Modify: `.miserc.toml`
52 54 - Modify: `mise.toml:1-7`
54 -- [ ] **Step 1: Record the unrelated root config diff before editing**
56 +- [x] **Step 1: Record the unrelated root config diff before editing**
63 65 Expected: `mise.toml` already shows unrelated removal of the Nushell tool and inline-shell settings, and `.miserc.toml` is untracked.
64 66 Do not restore, rewrite, stage, or commit those pre-existing root changes.
66 -- [ ] **Step 2: Run the failing monorepo discovery check**
68 +- [x] **Step 2: Run the failing monorepo discovery check**
74 76 Expected: no task name begins with `//extensions/` because monorepo mode and extension configs do not exist yet.
76 -- [ ] **Step 3: Keep the portable parent ceiling exact**
78 +- [x] **Step 3: Keep the portable parent ceiling exact**
78 80 Ensure `.miserc.toml` contains exactly:
84 86 This file is early-init configuration and must not move into `mise.toml`.
86 -- [ ] **Step 4: Enable explicit monorepo roots**
88 +- [x] **Step 4: Enable explicit monorepo roots**
88 90 Add these root-level keys before `[tools]` in `mise.toml`:
97 99 Keep the existing `[tools]` table and every task unchanged in this step.
98 100 Preserve the pre-existing Nushell/settings removals exactly.
100 -- [ ] **Step 5: Verify config isolation and monorepo parsing**
102 +- [x] **Step 5: Verify config isolation and monorepo parsing**
109 111 Expected from `mise config ls`: only `~/Workspace/dotfiles/pi-ext/mise.toml` is listed as project config, plus no parent `dotfiles/mise.toml`.
110 112 Expected from task listing: root tasks still parse successfully; no extension tasks exist until Task 2.
112 -- [ ] **Step 6: Commit only the isolated ceiling file**
114 +- [x] **Step 6: Commit only the isolated ceiling file**
134 136 - Create: `extensions/web/mise.toml`
135 137 - Modify: `extensions/llmiterate/__bench__/bench.ts:1-4`
137 -- [ ] **Step 1: Confirm qualified benchmark tasks are missing**
139 +- [x] **Step 1: Confirm qualified benchmark tasks are missing**
153 155 //extensions/web:bench
156 -- [ ] **Step 2: Add the goal benchmark task**
158 +- [x] **Step 2: Add the goal benchmark task**
158 160 Create `extensions/goal/mise.toml`:
164 166 run = "node --no-warnings --experimental-strip-types __benches__/goal-state.bench.ts"
167 -- [ ] **Step 3: Make llmiterate’s standalone benchmark Node-resolvable**
169 +- [x] **Step 3: Make llmiterate’s standalone benchmark Node-resolvable**
169 171 Change the imports at the top of `extensions/llmiterate/__bench__/bench.ts` to:
181 183 Do not alter benchmark inputs, iteration controls, or output.
183 -- [ ] **Step 4: Add both llmiterate benchmarks to one local task**
185 +- [x] **Step 4: Add both llmiterate benchmarks to one local task**
185 187 Create `extensions/llmiterate/mise.toml`:
197 199 The explicit `fast` project prevents the root Vitest multi-project config from running the same benchmark twice.
198 200 The default reporter avoids Vitest benchmark mode misreading the root test reporter as a custom reporter module.
200 -- [ ] **Step 5: Add the prompt-autopsy benchmark task**
202 +- [x] **Step 5: Add the prompt-autopsy benchmark task**
202 204 Create `extensions/prompt-autopsy/mise.toml`:
208 210 run = "node --no-warnings --experimental-strip-types __bench__/bench.ts"
211 -- [ ] **Step 6: Add the q benchmark task**
213 +- [x] **Step 6: Add the q benchmark task**
213 215 Create `extensions/q/mise.toml`:
219 221 run = "node --no-warnings --experimental-strip-types --experimental-loader ../../scripts/ts-js-loader.mjs __benches__/extract.bench.ts"
222 -- [ ] **Step 7: Add the terse benchmark task**
224 +- [x] **Step 7: Add the terse benchmark task**
224 226 Create `extensions/terse/mise.toml`:
230 232 run = "node --no-warnings --experimental-strip-types __bench__/bench.ts"
233 -- [ ] **Step 8: Add the web benchmark task**
235 +- [x] **Step 8: Add the web benchmark task**
235 237 Create `extensions/web/mise.toml`:
241 243 run = "node --no-warnings --experimental-strip-types --experimental-loader ../../scripts/ts-js-loader.mjs __bench__/bench.ts"
244 -- [ ] **Step 9: Verify discovery and each command shape**
246 +- [x] **Step 9: Verify discovery and each command shape**
258 260 Expected: all six qualified task names exist, each dry run resolves from its extension config root, and each depends on root `install`.
260 -- [ ] **Step 10: Run the two commands that previously needed resolution fixes**
262 +- [x] **Step 10: Run the two commands that previously needed resolution fixes**
269 271 Expected: both commands exit 0 and print benchmark results.
270 272 The llmiterate output contains both standalone `Benchmark...` lines and the Vitest `gitignore scan performance` table.
272 -- [ ] **Step 11: Commit extension benchmark ownership**
274 +- [x] **Step 11: Commit extension benchmark ownership**
289 291 - Modify: `extensions/goal/package.json`
290 292 - Delete: `scripts/test_goal_expect.mjs`
292 -- [ ] **Step 1: Confirm the old root surface still exists**
294 +- [x] **Step 1: Confirm the old root surface still exists**
300 302 Expected: `bench-q` and `goal-expect` exist, while a root `bench` task does not.
302 -- [ ] **Step 2: Replace root `bench-q` with the sequential aggregate**
304 +- [x] **Step 2: Replace root `bench-q` with the sequential aggregate**
304 306 Replace the complete `[tasks.bench-q]` block in `mise.toml` with:
313 315 The extension-qualified wildcard excludes the root aggregate itself.
314 316 `--jobs 1` is mandatory because concurrent benchmark processes contaminate measurements.
316 -- [ ] **Step 3: Remove the root goal Expect task**
318 +- [x] **Step 3: Remove the root goal Expect task**
318 320 Delete the complete `[tasks.goal-expect]` block from `mise.toml`, including its usage specification and multiline command.
319 321 Do not change `tasks.ci` or any E2E task in this phase.
321 -- [ ] **Step 4: Delete the nondeterministic smoke script**
323 +- [x] **Step 4: Delete the nondeterministic smoke script**
323 325 Delete `scripts/test_goal_expect.mjs`.
324 326 No replacement script is required because goal’s deterministic unit and integration tests remain under Vitest.
326 -- [ ] **Step 5: Remove goal’s stale package script**
328 +- [x] **Step 5: Remove goal’s stale package script**
328 330 In `extensions/goal/package.json`, remove:
336 338 The path is stale (`bench/` versus `__benches__/`), and local mise now owns the benchmark command.
337 339 Keep every dependency and package metadata field unchanged.
339 -- [ ] **Step 6: Verify the clean root task surface**
341 +- [x] **Step 6: Verify the clean root task surface**
350 352 Expected all-task names: all six qualified extension benchmarks still exist.
351 353 Expected dry-run behavior: root `install` precedes one nested `mise run --jobs 1 //extensions/...:bench` command.
353 -- [ ] **Step 7: Run the aggregate benchmark**
355 +- [x] **Step 7: Run the aggregate benchmark**
361 363 Expected: goal, llmiterate, prompt-autopsy, q, terse, and web benchmarks run one after another and the task exits 0.
362 364 No two `[//extensions/...:bench]` task headers overlap in time.
364 -- [ ] **Step 8: Commit only safely isolated files**
366 +- [x] **Step 8: Commit only safely isolated files**
387 389 - Modify: `extensions/terse/README.md`
388 390 - Modify: `extensions/web/README.md`
390 -- [ ] **Step 1: Update the root task table**
392 +- [x] **Step 1: Update the root task table**
392 394 In `AGENTS.md`, remove the `Goal expect` row.
393 395 Keep the existing `E2E browsers` and `E2E review` rows until Phase 2 replaces those tasks.
400 402 Defer all E2E documentation changes until Phase 2 introduces the aggregate.
401 403 Keep the CI description as `Release gate (lint + test + check)` in this phase.
403 -- [ ] **Step 2: Document qualified local task syntax**
405 +- [x] **Step 2: Document qualified local task syntax**
405 407 After the root task table in `AGENTS.md`, add:
410 412 Use `mise tasks --all` to list root and extension-local tasks.
413 -- [ ] **Step 3: Replace q’s obsolete benchmark command**
415 +- [x] **Step 3: Replace q’s obsolete benchmark command**
415 417 In `extensions/q/README.md`, replace:
424 426 - `mise run bench` from this extension, or `mise //extensions/q:bench` from the repository root, benchmarks the local heuristic extractor.
427 -- [ ] **Step 4: Add one benchmark sentence to each remaining owner README**
429 +- [x] **Step 4: Add one benchmark sentence to each remaining owner README**
429 431 Add a `## Bench` section near the command or development documentation in each README.
430 432 Use these exact sentences:
472 474 Preserve each README’s existing semantic line breaks.
474 -- [ ] **Step 5: Verify obsolete documentation is gone**
476 +- [x] **Step 5: Verify obsolete documentation is gone**
482 484 Expected: exit 0 with no output.
483 485 The existing E2E task names remain documented until Phase 2.
485 -- [ ] **Step 6: Verify formatting without mutating the dirty worktree**
487 +- [x] **Step 6: Verify formatting without mutating the dirty worktree**
487 489 Do not run `mise run fmt` in this phase because it writes across the repository and unrelated dirty files must remain byte-for-byte untouched.
488 490 The final `mise run ci` step runs the non-mutating lint checks and reports any formatting failures.
496 498 Expected: exit 0 with no output.
498 -- [ ] **Step 7: Commit documentation only**
500 +- [x] **Step 7: Commit documentation only**
517 519 - Verify: all six extension `mise.toml` files
518 520 - Verify: repository test and static-check paths
520 -- [ ] **Step 1: Validate mise task definitions**
522 +- [x] **Step 1: Validate mise task definitions**
531 533 The root list contains `bench` but not `bench-q` or `goal-expect`.
532 534 The all-task list contains exactly six `//extensions/<name>:bench` entries for goal, llmiterate, prompt-autopsy, q, terse, and web.
534 -- [ ] **Step 2: Verify benchmark execution and sequencing**
536 +- [x] **Step 2: Verify benchmark execution and sequencing**
542 544 Expected: all six extension benchmark groups exit 0 and execute sequentially.
544 -- [ ] **Step 3: Run the unchanged Phase 1 release gate**
546 +- [x] **Step 3: Run the unchanged Phase 1 release gate**
552 554 Expected: lint, Vitest, and static checks all pass.
553 555 E2E does not run in Phase 1.
555 -- [ ] **Step 4: Inspect all work and preserve unrelated changes**
557 +- [x] **Step 4: Inspect all work and preserve unrelated changes**
567 569 The `mise.toml` diff contains both the owner’s pre-existing Nushell/settings removal and this phase’s monorepo/task changes.
568 570 Do not claim or commit the former.
570 -- [ ] **Step 5: Commit the root config only if the relevant patch can be isolated**
572 +- [x] **Step 5: Commit the root config only if the relevant patch can be isolated**
572 574 Use interactive patch staging for `mise.toml` and select only:
588 590 Expected staged diff: no Nushell tool or inline-shell setting changes.
589 591 If Git cannot split the top hunk safely, leave `mise.toml` uncommitted and report the exact blocker instead of staging unrelated work.
591 -- [ ] **Step 6: Confirm the phase boundary**
593 +- [x] **Step 6: Confirm the phase boundary**
605 607 - CI still resolves lint, test, and check only.
606 608 - No E2E task migration or browser configuration changed.
608 -- [ ] **Step 7: Report completion evidence**
610 +- [x] **Step 7: Report completion evidence**
610 612 Report:

docs/super/plans/2026-07-12-mise-task-architecture-phase-3-mockup-e2e.md

Modified
13 13 **Phase:** Phase 3: Mockup Browser E2E Coverage
15 +**Status:** Reconciled on 2026-08-10 against current The System E2E tasks and history; phase work shipped.
17 19 ## File Structure
45 47 - Modify: `extensions/the-system/package.json`
46 48 - Modify: `package-lock.json`
48 -- [ ] **Step 1: Record the baseline**
50 +- [x] **Step 1: Record the baseline**
57 59 Expected: unrelated dirty work is visible and preserved.
58 60 `//extensions/the-system:e2e` does not exist.
60 -- [ ] **Step 2: Create the local Playwright overlay**
62 +- [x] **Step 2: Create the local Playwright overlay**
62 64 Create `extensions/the-system/playwright.config.ts`:
76 78 The shared base supplies Chromium, Firefox, and headless mode.
77 79 The extension config owns only suite-local paths and timeouts.
79 -- [ ] **Step 3: Declare the local Playwright development dependency**
81 +- [x] **Step 3: Declare the local Playwright development dependency**
81 83 Add this entry to `extensions/the-system/package.json` under `devDependencies`:
87 89 Keep every existing dependency and script unchanged.
89 -- [ ] **Step 4: Regenerate the npm lockfile**
91 +- [x] **Step 4: Regenerate the npm lockfile**
97 99 Expected: the the-system workspace entry in `package-lock.json` records `@playwright/test`.
98 100 No unrelated dependency versions change.
100 -- [ ] **Step 5: Write the browser smoke test**
102 +- [x] **Step 5: Write the browser smoke test**
102 104 Create `extensions/the-system/__e2e__/mockup.spec.ts`:
186 188 This test covers real page rendering, shadow-fragment revival, selection, notes, annotation entry, authenticated submission, and resolution of the server’s blocking result promise.
187 189 Do not add sleeps or call the HTTP API directly.
189 -- [ ] **Step 6: Verify Playwright discovers both browser projects**
191 +- [x] **Step 6: Verify Playwright discovers both browser projects**
197 199 Expected: one `[chromium]` and one `[firefox]` mockup test are listed.
199 -- [ ] **Step 7: Run the new suite directly**
201 +- [x] **Step 7: Run the new suite directly**
207 209 Expected: the round trip passes in Chromium and Firefox.
208 210 No desktop browser opens because the test calls the supported `openBrowser: false` path.
210 -- [ ] **Step 8: Fix type errors exposed by the E2E import**
212 +- [x] **Step 8: Fix type errors exposed by the E2E import**
212 214 Run `mise run check`.
213 215 Expected baseline: FAIL in `mockup.ts` because the previously excluded module has reversed `renderResult` arguments and a widened action set.
217 219 Run `mise run check` again.
218 220 Expected: PASS.
220 -- [ ] **Step 9: Commit the browser contract**
222 +- [x] **Step 9: Commit the browser contract**
237 239 - Create: `extensions/the-system/mise.toml`
239 -- [ ] **Step 1: Confirm the local task is still absent**
241 +- [x] **Step 1: Confirm the local task is still absent**
247 249 Expected: `//extensions/the-system:e2e` is absent.
249 -- [ ] **Step 2: Create the extension-local task**
251 +- [x] **Step 2: Create the extension-local task**
251 253 Create `extensions/the-system/mise.toml`:
257 259 run = "npm exec -- playwright test --config playwright.config.ts"
260 -- [ ] **Step 3: Verify discovery and qualified execution**
262 +- [x] **Step 3: Verify discovery and qualified execution**
270 272 Expected: the qualified task exists and passes once in Chromium and once in Firefox.
272 -- [ ] **Step 4: Commit local task ownership**
274 +- [x] **Step 4: Commit local task ownership**
288 290 - Modify: `extensions/the-system/README.md`
289 291 - Verify: root aggregate and existing CI
291 -- [ ] **Step 1: Document mockup E2E usage**
293 +- [x] **Step 1: Document mockup E2E usage**
293 295 Add this section near the mockup behavior documentation in `extensions/the-system/README.md`:
299 301 After that bootstrap, run `mise run e2e` here, or `mise //extensions/the-system:e2e` from the repository root, to test the mockup browser feedback round trip in Chromium and Firefox.
302 -- [ ] **Step 2: Verify documentation formatting**
304 +- [x] **Step 2: Verify documentation formatting**
311 313 If formatting differs, run targeted `mise exec -- dprint fmt extensions/the-system/README.md` and check again.
312 314 Do not format unrelated dirty files.
314 -- [ ] **Step 3: Commit documentation**
316 +- [x] **Step 3: Commit documentation**
324 326 Expected: only the-system README is committed.
326 -- [ ] **Step 4: Verify aggregate discovery**
328 +- [x] **Step 4: Verify aggregate discovery**
339 341 - Root `e2e` still installs Chromium and Firefox once.
340 342 - Root dispatch remains sequential.
342 -- [ ] **Step 5: Run all three extension suites**
344 +- [x] **Step 5: Run all three extension suites**
352 354 - Diff-review passes in Chromium and Firefox.
353 355 - The-system mockup round trip passes in Chromium and Firefox.
355 -- [ ] **Step 6: Run the unchanged release gate**
357 +- [x] **Step 6: Run the unchanged release gate**
363 365 Expected: lint, Vitest, typecheck, and static checks pass.
364 366 E2E remains outside CI until Phase 4.
366 -- [ ] **Step 7: Inspect final scope**
368 +- [x] **Step 7: Inspect final scope**
376 378 No tune E2E or CI-order change exists.
377 379 No TypeScript standardization from Phase 5 exists.
379 -- [ ] **Step 8: Report completion evidence**
381 +- [x] **Step 8: Report completion evidence**
381 383 Report:

docs/super/plans/2026-07-12-mise-task-architecture-phase-4-tune-e2e-ci.md

Modified
13 13 **Phase:** Phase 4: Tune Browser E2E And CI Promotion
15 +**Status:** Reconciled on 2026-08-10 against current Tune E2E tasks and history; phase work shipped.
17 19 ## Design Note
59 61 - Modify: `extensions/tune/package.json`
60 62 - Modify: `package-lock.json`
62 -- [ ] **Step 1: Record the baseline**
64 +- [x] **Step 1: Record the baseline**
71 73 Expected: unrelated dirty work remains visible and preserved.
72 74 `//extensions/tune:e2e` does not exist.
74 -- [ ] **Step 2: Create tune’s local Playwright overlay**
76 +- [x] **Step 2: Create tune’s local Playwright overlay**
76 78 Create `extensions/tune/playwright.config.ts`:
90 -- [ ] **Step 3: Declare Playwright locally**
92 +- [x] **Step 3: Declare Playwright locally**
92 94 Add to tune’s `devDependencies`:
99 101 Run `mise run lock`.
100 102 Expected: only tune’s workspace dependency metadata changes.
102 -- [ ] **Step 4: Write the failing dashboard E2E contract**
104 +- [x] **Step 4: Write the failing dashboard E2E contract**
104 106 Create `extensions/tune/__e2e__/dashboard.spec.ts`:
191 193 Expected: FAIL because `dashboard.ts` does not exist.
193 -- [ ] **Step 5: Implement the minimal dashboard lifecycle module**
195 +- [x] **Step 5: Implement the minimal dashboard lifecycle module**
195 197 Create `extensions/tune/dashboard.ts`:
298 300 No authentication is added because the existing dashboard is loopback-only and read-only.
299 301 No filesystem path is accepted from HTTP requests.
301 -- [ ] **Step 6: Verify the E2E contract turns green**
303 +- [x] **Step 6: Verify the E2E contract turns green**
310 312 Expected: one dashboard test passes in Chromium and Firefox, and static checks pass with Playwright declared locally.
312 -- [ ] **Step 7: Verify static checks and commit the tested dashboard module**
314 +- [x] **Step 7: Verify static checks and commit the tested dashboard module**
328 330 - Modify: `extensions/tune/index.ts:10-17,3024-3180`
330 -- [ ] **Step 1: Replace dashboard server imports**
332 +- [x] **Step 1: Replace dashboard server imports**
332 334 Remove this import from `extensions/tune/index.ts`:
341 343 import { startTuneDashboard, type TuneDashboard } from "./dashboard.ts";
344 -- [ ] **Step 2: Collapse dashboard state to one owner**
346 +- [x] **Step 2: Collapse dashboard state to one owner**
346 348 Replace:
359 361 let dashboardServer: TuneDashboard | null = null;
362 -- [ ] **Step 3: Delegate broadcast and shutdown**
364 +- [x] **Step 3: Delegate broadcast and shutdown**
364 366 Replace `broadcastDashboardUpdate()` with:
381 -- [ ] **Step 4: Remove temporary HTML export and inline server creation**
383 +- [x] **Step 4: Remove temporary HTML export and inline server creation**
383 385 Inside `exportDashboard()`, keep template lookup, JSONL reading, title extraction, and HTML injection.
384 386 Replace everything from creation of `exportDir` through assignment of `dashboardServerPort` with:
406 408 Do not change command behavior, template rendering, or browser opener policy.
408 -- [ ] **Step 5: Run focused deterministic tests**
410 +- [x] **Step 5: Run focused deterministic tests**
417 419 Expected: existing dashboard/template tests and both browser projects pass.
419 -- [ ] **Step 6: Commit production integration**
421 +- [x] **Step 6: Commit production integration**
435 437 - Create: `extensions/tune/mise.toml`
437 -- [ ] **Step 1: Create tune’s local task**
439 +- [x] **Step 1: Create tune’s local task**
439 441 Create `extensions/tune/mise.toml`:
445 447 run = "npm exec -- playwright test --config playwright.config.ts"
448 -- [ ] **Step 2: Verify qualified ownership**
450 +- [x] **Step 2: Verify qualified ownership**
458 460 Expected: tune’s qualified task is discovered and passes in Chromium and Firefox.
460 -- [ ] **Step 3: Commit local ownership**
462 +- [x] **Step 3: Commit local ownership**
477 479 - Create: `.ci/ci.kdl`
478 480 - Delete: `.github/workflows/check.yml`
480 -- [ ] **Step 1: Verify the current CI order excludes E2E**
482 +- [x] **Step 1: Verify the current CI order excludes E2E**
488 490 Expected: lint, test, and check appear; E2E does not.
490 -- [ ] **Step 2: Keep browser system dependencies outside the cross-platform task**
492 +- [x] **Step 2: Keep browser system dependencies outside the cross-platform task**
492 494 In root `tasks.e2e`, use the same browser-engine install command everywhere:
498 500 Local `mise run e2e` downloads browser engines without mutating host system packages.
499 501 Luci’s pinned Playwright image supplies its Linux system dependencies.
501 -- [ ] **Step 3: Set the final release-gate order**
503 +- [x] **Step 3: Set the final release-gate order**
503 505 Replace root `tasks.ci.run` with:
514 516 Check runs first and fails fastest on type or package-structure errors.
515 517 E2E runs last because it is the most expensive gate.
517 -- [ ] **Step 4: Verify task resolution locally**
519 +- [x] **Step 4: Verify task resolution locally**
530 532 - CI order is check, lint, test, e2e.
531 533 - Root E2E discovers diff-review, UI, the-system, and tune.
533 -- [ ] **Step 5: Migrate repository CI to Luci**
535 +- [x] **Step 5: Migrate repository CI to Luci**
535 537 Delete `.github/workflows/check.yml`.
536 538 Create `.ci/ci.kdl` with one push-triggered `ci` job using `mcr.microsoft.com/playwright:v1.61.0-noble`.
538 540 The Firefox sandbox override is required because Luci already drops every container capability, making Firefox’s nested chroot sandbox incompatible.
539 541 Validate the KDL with Luci’s real parser and run the exact job command in a clean ephemeral Podman worktree.
541 -- [ ] **Step 6: Commit release-gate promotion**
543 +- [x] **Step 6: Commit release-gate promotion**
557 559 - Modify: `AGENTS.md`
558 560 - Modify: `extensions/tune/README.md`
560 -- [ ] **Step 1: Update root CI documentation**
562 +- [x] **Step 1: Update root CI documentation**
562 564 Change the `CI` task description in `AGENTS.md` to:
568 570 The existing root E2E row remains unchanged.
570 -- [ ] **Step 2: Document tune E2E usage**
572 +- [x] **Step 2: Document tune E2E usage**
572 574 Add near tune’s dashboard behavior documentation:
578 580 After that bootstrap, run `mise run e2e` here, or `mise //extensions/tune:e2e` from the repository root, to test dashboard loading, theme interaction, and live updates in Chromium and Firefox.
581 -- [ ] **Step 3: Format only changed documentation**
583 +- [x] **Step 3: Format only changed documentation**
590 592 Expected: both files are formatted without touching unrelated dirty work.
592 -- [ ] **Step 4: Commit documentation**
594 +- [x] **Step 4: Commit documentation**
602 604 Expected: only final task documentation is committed.
604 -- [ ] **Step 5: Run all browser suites**
606 +- [x] **Step 5: Run all browser suites**
615 617 - The-system mockup passes in Chromium and Firefox.
616 618 - Tune dashboard passes in Chromium and Firefox.
618 -- [ ] **Step 6: Run the complete release gate**
620 +- [x] **Step 6: Run the complete release gate**
626 628 Expected: check, lint, all Vitest tests, and all browser E2E suites pass in documented order.
628 -- [ ] **Step 7: Inspect final phase scope**
630 +- [x] **Step 7: Inspect final phase scope**
638 640 No bundling or emitted JavaScript exists.
639 641 Phase 5 TypeScript standardization remains unimplemented.
641 -- [ ] **Step 8: Report completion evidence**
643 +- [x] **Step 8: Report completion evidence**
643 645 Report:

docs/super/plans/2026-07-12-os-notifier.md

Modified
13 13 **Phase:** Single-plan implementation
15 +**Status:** Reconciled on 2026-08-10 against `extensions/os-notifier`; implementation shipped.
17 19 ## Task 1: Rename the Extension
23 25 - Modify: `README.md`
24 26 - Modify: `package-lock.json`
26 -- [ ] **Step 1: Rename the directory and package metadata**
28 +- [x] **Step 1: Rename the directory and package metadata**
34 36 Change the package name to `@bugabinga/pi-ext-os-notifier`, description to `Native-first OS notifications for Pi.`, and root README table entry/link to `os-notifier`.
36 -- [ ] **Step 2: Regenerate workspace lockfile references**
38 +- [x] **Step 2: Regenerate workspace lockfile references**
44 46 Expected: `package-lock.json` contains `extensions/os-notifier` and no `terminal-notifier` references.
46 -- [ ] **Step 3: Verify rename completeness**
48 +- [x] **Step 3: Verify rename completeness**
54 56 Expected: only historical changelog entries remain; package, source, tests, and README use `os-notifier`.
56 -- [ ] **Step 4: Commit the rename**
58 +- [x] **Step 4: Commit the rename**
58 60 ```bash
59 61 git add README.md package-lock.json extensions/terminal-notifier extensions/os-notifier
67 69 - Modify: `extensions/os-notifier/__tests__/harness.test.ts`
68 70 - Modify: `extensions/os-notifier/index.ts`
70 -- [ ] **Step 1: Replace old backend tests with failing native command tests**
72 +- [x] **Step 1: Replace old backend tests with failing native command tests**
72 74 Add table tests asserting:
89 91 Assert command arguments carry quoted/control-character input as data rather than interpolating it into a shell command.
91 -- [ ] **Step 2: Add failing eligibility state tests**
93 +- [x] **Step 2: Add failing eligibility state tests**
93 95 Export a small `TurnEligibility` class and test:
110 112 Add a queued-follow-up test proving interactive input arriving during an active lifecycle makes that lifecycle eligible and does not leak into the next run.
112 -- [ ] **Step 3: Add failing metadata tests**
114 +- [x] **Step 3: Add failing metadata tests**
114 116 Retain existing rich-content assertions and add bounded error-detail and control-character sanitization assertions.
115 117 Verify normal, aborted, and error outcomes map to info, warning, and error.
117 -- [ ] **Step 4: Run extension tests and confirm failure**
119 +- [x] **Step 4: Run extension tests and confirm failure**
125 127 Expected: FAIL because native command and eligibility exports do not exist yet.
127 -- [ ] **Step 5: Implement pure formatting, command, and eligibility helpers**
129 +- [x] **Step 5: Implement pure formatting, command, and eligibility helpers**
129 131 In `index.ts`:
136 138 - add minimal candidate/prepared/active eligibility bookkeeping driven by `input`, `before_agent_start`, `agent_start`, and `agent_settled`; handled input cannot leak, pre-prompt compaction ordering remains correct, and active steering cannot reclassify extension-driven work
137 139 - remove `notify:send`, `notify:ui`, startup probes, backend caching, and warning notifications
139 -- [ ] **Step 6: Run extension tests**
141 +- [x] **Step 6: Run extension tests**
147 149 Expected: PASS.
149 -- [ ] **Step 7: Commit behavior**
151 +- [x] **Step 7: Commit behavior**
151 153 ```bash
152 154 git add extensions/os-notifier/index.ts extensions/os-notifier/__tests__/harness.test.ts
161 163 - Modify: `extensions/os-notifier/README.md`
162 164 - Modify: `extensions/os-notifier/CHANGELOG.md`
164 -- [ ] **Step 1: Add a failing delivery-path test**
166 +- [x] **Step 1: Add a failing delivery-path test**
166 168 Create a controlled executable in a test temporary directory, prepend it to `PATH`, and exercise the exported delivery function.
167 169 Assert exit zero writes no OSC.
168 170 Replace it with a nonzero executable and assert exactly one OSC sequence is written.
169 171 Use Node file APIs and a platform-appropriate executable fixture; do not invoke shell discovery helpers.
171 -- [ ] **Step 2: Run the focused test and confirm failure**
173 +- [x] **Step 2: Run the focused test and confirm failure**
179 181 Expected: FAIL until delivery exposes completion/failure behavior suitable for deterministic testing.
181 -- [ ] **Step 3: Implement one-shot native delivery with OSC fallback**
183 +- [x] **Step 3: Implement one-shot native delivery with OSC fallback**
183 185 Use `execFile(command, args, callback)` without a shell and with a five-second timeout.
184 186 On `error`, timeout, or nonzero command completion, write exactly one selected OSC fallback.
186 188 Ignore OSC write errors.
187 189 Do not block or throw into Pi lifecycle handlers.
189 -- [ ] **Step 4: Update documentation**
191 +- [x] **Step 4: Update documentation**
191 193 Document:
200 202 Add an unreleased changelog entry for the rename and redesign.
202 -- [ ] **Step 5: Run focused and repository checks**
204 +- [x] **Step 5: Run focused and repository checks**
213 215 Expected: every command exits zero.
215 -- [ ] **Step 6: Verify repository invariants**
217 +- [x] **Step 6: Verify repository invariants**
225 227 Expected: the directory assertions pass; only historical changelog references may match.
227 -- [ ] **Step 7: Commit final integration**
229 +- [x] **Step 7: Commit final integration**
229 231 ```bash
230 232 git add extensions/os-notifier/README.md extensions/os-notifier/CHANGELOG.md extensions/os-notifier/__tests__/harness.test.ts extensions/os-notifier/index.ts

docs/super/plans/2026-07-13-modernize-prompt.md

Modified
13 13 **Phase:** Single-plan implementation
15 +**Status:** Reconciled on 2026-08-10 against `.pi/prompts/modernize.md` and `.pi/skills/modernize`; implementation shipped.
17 19 ## Task 1: Deterministic audit collector
21 23 - Create: `.pi/skills/modernize/scripts/audit.mjs`
22 24 - Create: `.pi/skills/modernize/scripts/audit.test.mjs`
24 -- [ ] **Step 1: Write failing Node tests**
26 +- [x] **Step 1: Write failing Node tests**
26 28 Cover release-section parsing, migration-section extraction, keyword extraction, ordinary-note exclusion, stale installed-version rejection, semantic version ordering, malformed changelog rejection, package-lock Pi version collection, and Git file-list parsing.
28 -- [ ] **Step 2: Run tests to verify RED**
30 +- [x] **Step 2: Run tests to verify RED**
36 38 Expected: failure because `audit.mjs` does not exist.
38 -- [ ] **Step 3: Implement the collector**
40 +- [x] **Step 3: Implement the collector**
40 42 Implement exports for pure parsing/version functions plus a CLI that:
50 52 - emits JSON only;
51 53 - writes no files.
53 -- [ ] **Step 4: Run tests to verify GREEN**
55 +- [x] **Step 4: Run tests to verify GREEN**
55 57 Run the same `node --test` command.
56 58 Expected: all collector tests pass.
58 -- [ ] **Step 5: Commit**
60 +- [x] **Step 5: Commit**
60 62 ```bash
61 63 git add .pi/skills/modernize/scripts/audit.mjs .pi/skills/modernize/scripts/audit.test.mjs
69 71 - Create: `.pi/skills/modernize/SKILL.md`
70 72 - Create: `.pi/prompts/modernize.md`
72 -- [ ] **Step 1: Create the skill**
74 +- [x] **Step 1: Create the skill**
74 76 Define a read-only workflow that runs `node .pi/skills/modernize/scripts/audit.mjs`, stops on preflight failure, verifies every candidate against latest Pi docs/source, scans every returned repository file, inspects callers, and reports evidence-backed findings only.
76 -- [ ] **Step 2: Create the prompt**
78 +- [x] **Step 2: Create the prompt**
78 80 Register `/modernize [focus]`, require the `modernize` skill, preserve whole-repository scope, and require funny non-boxed ASCII art under 20 lines only for `MODERNIZE CLEAN`.
80 -- [ ] **Step 3: Validate discovery and formatting**
82 +- [x] **Step 3: Validate discovery and formatting**
90 92 Inspect startup diagnostics for prompt/skill warnings.
92 -- [ ] **Step 4: Commit**
94 +- [x] **Step 4: Commit**
94 96 ```bash
95 97 git add .pi/prompts/modernize.md .pi/skills/modernize/SKILL.md
103 105 - No repository files expected
104 106 - Temporary output under `/tmp/pi-modernize-*`
106 -- [ ] **Step 1: Run collector against real sources**
108 +- [x] **Step 1: Run collector against real sources**
108 110 ```bash
109 111 node .pi/skills/modernize/scripts/audit.mjs > /tmp/pi-modernize-audit.json
112 114 Assert local/latest equality, both changelog sources, candidate count, resolved package versions, and repository file count with `jq`.
114 -- [ ] **Step 2: Run real Pi prompt**
116 +- [x] **Step 2: Run real Pi prompt**
116 118 From the repository root, run a fresh print-mode Pi invocation with `/modernize` and capture output outside the repository.
118 120 Expected: `MODERNIZE FINDINGS` with evidence-backed `path:line` entries, or `MODERNIZE CLEAN` plus ASCII art.
120 -- [ ] **Step 3: Independently verify output**
122 +- [x] **Step 3: Independently verify output**
122 124 Check each reported path exists and each cited migration appears in collector evidence/current Pi docs.
123 125 Confirm the audit made no repository changes beyond intended prompt/skill files.
125 -- [ ] **Step 4: Run final gates**
127 +- [x] **Step 4: Run final gates**
127 129 ```bash
128 130 mise run check
130 132 mise run test
133 -- [ ] **Step 5: Clean temporary artifacts**
135 +- [x] **Step 5: Clean temporary artifacts**
135 137 Delete only `/tmp/pi-modernize-*` files created by the experiment.
137 -- [ ] **Step 6: Commit any verification-only test correction**
139 +- [x] **Step 6: Commit any verification-only test correction**
139 141 Commit only if experimental verification exposes and fixes a prompt, skill, script, or permanent-test defect.

docs/super/plans/2026-07-13-ultra-actionable-failures.md

Modified
13 13 **Phase:** Single-plan implementation
15 +**Status:** Reconciled on 2026-08-10 against current code; checkboxes reflect present repo state, not original execution order.
17 19 ## Task 1: Typed runner failures
21 23 - Modify: `extensions/ultra/runner.ts`
22 24 - Modify: `extensions/ultra/__tests__/runner.test.ts`
24 -- [ ] **Step 1: Add failing tests**
26 +- [x] **Step 1: Add failing tests**
26 28 Cover auth, transport, invalid JSON, schema, missing structured output, session creation/prompt exceptions, manual/external abort, attempt counts, model/thinking metadata, and 2,000-character transcript-tail capping.
28 -- [ ] **Step 2: Run focused tests to verify RED**
30 +- [x] **Step 2: Run focused tests to verify RED**
30 32 ```bash
31 33 mise //extensions/ultra:test -- runner
34 -- [ ] **Step 3: Implement `StepFailure` and discriminated results**
36 +- [x] **Step 3: Implement `StepFailure` and discriminated results**
36 38 Remove top-level `reason`, classify every expected terminal runner failure, catch tool-session exceptions, track manual abort, and retain only a bounded transcript tail.
38 -- [ ] **Step 4: Run focused tests to verify GREEN**
40 +- [x] **Step 4: Run focused tests to verify GREEN**
40 42 ```bash
41 43 mise //extensions/ultra:test -- runner
44 -- [ ] **Step 5: Commit**
46 +- [x] **Step 5: Commit**
46 48 ```bash
47 49 git add extensions/ultra/runner.ts extensions/ultra/__tests__/runner.test.ts
58 60 - Modify: `extensions/ultra/__tests__/interp.test.ts`
59 61 - Modify: other Ultra tests constructing failed `RunStepResult` values
61 -- [ ] **Step 1: Add failing interpolation tests**
63 +- [x] **Step 1: Add failing interpolation tests**
63 65 Cover `{PHASE.failures}` in templates, selectors, `where`, unknown phases, and recovery fan-out.
65 -- [ ] **Step 2: Add failing engine tests**
67 +- [x] **Step 2: Add failing engine tests**
67 69 Cover positional failure records, `phaseFailures`, item/index/agent enrichment, launched and unlaunched aborts, skipped phases, recovery `when`/`over`, and return selection.
69 -- [ ] **Step 3: Run focused tests to verify RED**
71 +- [x] **Step 3: Run focused tests to verify RED**
71 73 ```bash
72 74 mise //extensions/ultra:test -- interp engine
75 -- [ ] **Step 4: Implement failure context**
77 +- [x] **Step 4: Implement failure context**
77 79 Add the failures namespace to interpolation, derive `phaseFailures` during normalization, and include it in the final workflow result.
79 -- [ ] **Step 5: Update failed-result fixtures**
81 +- [x] **Step 5: Update failed-result fixtures**
81 83 Replace old `reason` fixtures with typed failures without adding compatibility paths.
83 -- [ ] **Step 6: Run focused tests to verify GREEN**
85 +- [x] **Step 6: Run focused tests to verify GREEN**
85 87 ```bash
86 88 mise //extensions/ultra:test -- interp engine
89 -- [ ] **Step 7: Commit**
91 +- [x] **Step 7: Commit**
91 93 ```bash
92 94 git add extensions/ultra
100 102 - Modify: `extensions/ultra/wire.ts`
101 103 - Modify: `extensions/ultra/index.ts`
102 104 - Modify: `extensions/ultra/README.md`
103 -- Modify: `extensions/ultra/skills/authoring-workflows/SKILL.md`
104 -- Modify: `extensions/ultra/skills/authoring-workflows/references/spec-format.md`
105 +- Modify: `extensions/ultra/prompts/authoring-workflows.md`
106 +- Modify: `extensions/ultra/prompts/references/spec-format.md`
105 107 - Modify: `extensions/ultra/__tests__/wire.test.ts`
106 108 - Modify: `extensions/ultra/__tests__/ui.test.ts`
107 109 - Modify: `extensions/ultra/__tests__/harness.test.ts`
109 -- [ ] **Step 1: Add failing result-format tests**
111 +- [x] **Step 1: Add failing result-format tests**
111 113 Require collapsed short failure lines, expanded typed diagnostics, and tool JSON containing `phaseFailures`.
113 -- [ ] **Step 2: Implement formatting and fallback result shapes**
115 +- [x] **Step 2: Implement formatting and fallback result shapes**
115 117 Render structured failures without exposing full transcripts in collapsed mode and update background/error fallback objects.
117 -- [ ] **Step 3: Document explicit linear recovery**
119 +- [x] **Step 3: Document explicit linear recovery**
119 121 Document failure fields, `{PHASE.failures}`, `when`/`over` recovery, bounded transcript tails, and the absence of automatic loops/timeouts.
121 -- [ ] **Step 4: Run Ultra tests**
123 +- [x] **Step 4: Run Ultra tests**
123 125 ```bash
124 126 mise //extensions/ultra:test
127 -- [ ] **Step 5: Commit**
129 +- [x] **Step 5: Commit**
129 131 ```bash
130 132 git add extensions/ultra
138 140 - No new production files expected
140 -- [ ] **Step 1: Run repository gates**
142 +- [x] **Step 1: Run repository gates**
142 144 ```bash
143 145 mise run check
145 147 mise run test
148 -- [ ] **Step 2: Run a real recovery workflow**
150 +- [x] **Step 2: Run a real recovery workflow**
150 152 Use a temporary project and inline workflow where one phase deterministically fails structured output and a later phase consumes `{PHASE.failures}`.
152 154 Assert the recovery agent receives code, retryability, attempts, item, model, and transcript tail, and the outer result contains identical diagnostics.
154 -- [ ] **Step 3: Verify infinite runtime remains unchanged**
156 +- [x] **Step 3: Verify infinite runtime remains unchanged**
156 158 Confirm no timeout setting, timer race, or timeout failure code exists in Ultra runtime files.
158 -- [ ] **Step 4: Clean temporary artifacts**
160 +- [x] **Step 4: Clean temporary artifacts**
160 162 Delete only temporary verification files created for this plan.
162 -- [ ] **Step 5: Commit only verification-driven corrections**
164 +- [x] **Step 5: Commit only verification-driven corrections**
164 166 Do not create an empty verification commit.

docs/super/plans/2026-07-13-ultra-infinite-step-runtime.md

Modified
13 13 **Phase:** Single-plan implementation
15 +**Status:** Reconciled on 2026-08-10 against current code; checkboxes reflect present repo state, not original execution order.
17 19 ## Task 1: Remove Timeout Configuration
24 26 - Modify: `extensions/ultra/spec.ts`
25 27 - Modify: `extensions/ultra/index.ts`
27 -- [ ] **Step 1: Write failing boundary tests**
29 +- [x] **Step 1: Write failing boundary tests**
29 31 Remove `defaultTimeoutMs` from every expected settings object and input fixture in `settings.test.ts`.
30 32 Add this parser test in `spec.test.ts`:
40 -- [ ] **Step 2: Run tests and verify RED**
42 +- [x] **Step 2: Run tests and verify RED**
48 50 Expected: failures because settings still expose `defaultTimeoutMs` and workflow steps still accept `timeoutMs`.
50 -- [ ] **Step 3: Delete timeout configuration**
52 +- [x] **Step 3: Delete timeout configuration**
52 54 Delete `defaultTimeoutMs` from `UltraSettings`, `ULTRA_DEFAULTS`, `pickUltra`, and `mergeUltraSettings` in `settings.ts`.
53 55 Delete `timeoutMs` from `StepSchema` and make that object reject unknown fields:
68 70 Delete `defaultTimeoutMs: cfg.defaultTimeoutMs` from `buildStepRunner()` in `index.ts`.
70 -- [ ] **Step 4: Run tests and verify GREEN**
72 +- [x] **Step 4: Run tests and verify GREEN**
72 74 Run the Task 1 test command again.
73 75 Expected: both files pass.
79 81 - Modify: `extensions/ultra/__tests__/runner.test.ts`
80 82 - Modify: `extensions/ultra/runner.ts`
82 -- [ ] **Step 1: Write failing runner tests**
84 +- [x] **Step 1: Write failing runner tests**
84 86 Delete `defaultTimeoutMs` from `baseOpts()` and both `makeStepRunner()` fixtures.
85 87 Replace each timeout test with a deferred completion test that waits past a short test-only delay, verifies the run remains pending, then resolves it successfully.
141 143 await expect(pending).resolves.toEqual({ ok: true, value: { verdict: "ok" } });
144 -- [ ] **Step 2: Run runner tests and verify RED**
146 +- [x] **Step 2: Run runner tests and verify RED**
152 154 Expected: deferred runs settle as `timeout` because the old runtime receives no default timeout and schedules an immediate timer.
154 -- [ ] **Step 3: Implement abort-only execution**
156 +- [x] **Step 3: Implement abort-only execution**
156 158 Delete `defaultTimeoutMs` from `BaseStepOptions`.
157 159 Replace `GuardOutcome` and `raceGuards()` with an abort-only outcome and helper:
193 195 Keep `live.abort()` when a tool session returns the aborted outcome.
194 196 Update timeout-specific runner comments.
196 -- [ ] **Step 4: Run runner tests and verify GREEN**
198 +- [x] **Step 4: Run runner tests and verify GREEN**
198 200 Run the Task 2 test command again.
199 201 Expected: all runner tests pass.
207 209 - Modify: `extensions/ultra/__tests__/ui.test.ts`
208 210 - Modify: `extensions/ultra/__tests__/wire.test.ts`
209 211 - Modify: `extensions/ultra/README.md`
210 -- Modify: `extensions/ultra/skills/authoring-workflows/references/spec-format.md`
212 +- Modify: `extensions/ultra/prompts/references/spec-format.md`
212 -- [ ] **Step 1: Remove timeout-only fixtures and tokens**
214 +- [x] **Step 1: Remove timeout-only fixtures and tokens**
214 216 Delete `"timeout"` from the progress reducer's dropped-status set.
215 217 Change timeout fixture statuses and reasons in progress, UI, and wire tests to `"dropped"` or a provider failure reason while retaining their assertions about dropped rendering and result formatting.
216 218 Delete the `ultra.defaultTimeoutMs` settings row from `README.md`.
217 219 Delete the `timeoutMs` step row from `spec-format.md`.
219 -- [ ] **Step 2: Prove no timeout machinery remains**
221 +- [x] **Step 2: Prove no timeout machinery remains**
227 229 Expected: no output and exit code 1.
229 -- [ ] **Step 3: Run Ultra checks**
231 +- [x] **Step 3: Run Ultra checks**
239 241 Expected: all tests, formatting, lint, typecheck, skill checks, and static extension checks pass.
241 -- [ ] **Step 4: Commit the implementation**
243 +- [x] **Step 4: Commit the implementation**
243 245 ```text
244 246 git add extensions/ultra

docs/super/plans/2026-07-13-ultra-planned-work-visibility.md

Modified
13 13 **Phase:** Single-plan implementation
15 +**Status:** Reconciled on 2026-08-10 against current code; checkboxes reflect present repo state, not original execution order.
17 19 ## Task 1: Add Planned Progress State
21 23 - Modify: `extensions/ultra/__tests__/progress.test.ts`
22 24 - Modify: `extensions/ultra/progress.ts`
24 -- [ ] **Step 1: Write failing reducer tests**
26 +- [x] **Step 1: Write failing reducer tests**
26 28 Add tests proving:
64 -- [ ] **Step 2: Run progress tests and verify RED**
66 +- [x] **Step 2: Run progress tests and verify RED**
72 74 Expected: TypeScript/runtime failures because plan events, planned phase records, queued status, and new counts do not exist.
74 -- [ ] **Step 3: Implement the progress model**
76 +- [x] **Step 3: Implement the progress model**
76 78 Split the event contract into this union:
129 131 Update `mapSessionEvent()` to return `AgentProgressEvent | null`.
130 132 Guard transcript and row helpers so they accept only agent events.
132 -- [ ] **Step 4: Run progress tests and verify GREEN**
134 +- [x] **Step 4: Run progress tests and verify GREEN**
134 136 Run the Task 1 test command again.
135 137 Expected: all progress tests pass.
141 143 - Modify: `extensions/ultra/__tests__/engine.test.ts`
142 144 - Modify: `extensions/ultra/engine.ts`
144 -- [ ] **Step 1: Write failing engine tests**
146 +- [x] **Step 1: Write failing engine tests**
146 148 Add one test with unconditional single, literal fan-out, dynamic fan-out, and conditional phases.
147 149 Capture `onProgress` and assert the first event is:
166 168 - empty fan-out emits resolved/done with no agent ids;
167 169 - cancellation emits dropped ends for every resolved but unlaunched agent.
169 -- [ ] **Step 2: Run engine tests and verify RED**
171 +- [x] **Step 2: Run engine tests and verify RED**
177 179 Expected: failures because the engine emits only agent events.
179 -- [ ] **Step 3: Implement planning emissions**
181 +- [x] **Step 3: Implement planning emissions**
181 183 Add a pure initial planner:
214 216 Update `makeForwarder()` to wrap controls only when `event.kind` is an agent kind and controls exist.
215 217 Do not alter result counts, interpolation, or journal behavior.
217 -- [ ] **Step 4: Run engine tests and verify GREEN**
219 +- [x] **Step 4: Run engine tests and verify GREEN**
219 221 Run the Task 2 test command again.
220 222 Expected: all engine tests pass.
226 228 - Modify: `extensions/ultra/__tests__/ui.test.ts`
227 229 - Modify: `extensions/ultra/ui.ts`
229 -- [ ] **Step 1: Write failing tool and overlay tests**
231 +- [x] **Step 1: Write failing tool and overlay tests**
231 233 Add tests for the accepted visual vocabulary:
242 244 Also assert textual labels remain present.
243 245 Verify expanded rows follow specification phase order, pending/skipped placeholders are visible, collapsed output contains counts but no ids/actions, and overlay focus navigation skips phase placeholders.
245 -- [ ] **Step 2: Run UI tests and verify RED**
247 +- [x] **Step 2: Run UI tests and verify RED**
253 255 Expected: failures because only running/done/dropped agent rows render.
255 -- [ ] **Step 3: Implement ordered display rows and icons**
257 +- [x] **Step 3: Implement ordered display rows and icons**
257 259 Use verified glyph constants:
296 298 Harden `asReducerState()` so old `phases: string[]` details fall back to an empty board.
298 -- [ ] **Step 4: Run UI tests and verify GREEN**
300 +- [x] **Step 4: Run UI tests and verify GREEN**
300 302 Run the Task 3 test command again.
301 303 Expected: all UI tests pass.
309 311 - Modify: `extensions/ultra/wire.ts`
310 312 - Modify: `extensions/ultra/README.md`
312 -- [ ] **Step 1: Write failing sink and harness tests**
314 +- [x] **Step 1: Write failing sink and harness tests**
314 316 Update sink tests to send a plan event first and assert the first `onUpdate.details` already contains every phase and known queued agent.
315 317 Update harness expectations so the expanded workflow tool result contains queued or planning rows before completion.
317 -- [ ] **Step 2: Run wire and harness tests and verify RED**
319 +- [x] **Step 2: Run wire and harness tests and verify RED**
325 327 Expected: failures because the sink assumes every event has controls and the old summary lacks planned counts.
327 -- [ ] **Step 3: Update sink serialization and docs**
329 +- [x] **Step 3: Update sink serialization and docs**
329 331 In `makeToolProgressSink()`, strip controls only from agent events:
336 338 Update `summarize()` with done, active, queued, later, and dropped counts.
337 339 Document planned ledger states and icon labels in `README.md`.
339 -- [ ] **Step 4: Run wire and harness tests and verify GREEN**
341 +- [x] **Step 4: Run wire and harness tests and verify GREEN**
341 343 Run the Task 4 test command again.
342 344 Expected: both files pass.
348 350 - Verify: `extensions/ultra/**`
350 -- [ ] **Step 1: Run focused verification**
352 +- [x] **Step 1: Run focused verification**
352 354 ```text
353 355 mise run test -- extensions/ultra
358 360 Expected: all Ultra tests, formatting, lint, typecheck, skill checks, and static extension checks pass.
360 -- [ ] **Step 2: Inspect scope**
362 +- [x] **Step 2: Inspect scope**
362 364 ```text
363 365 git diff --check -- extensions/ultra
367 369 Expected: no whitespace errors and no files outside `extensions/ultra` in the implementation diff.
369 -- [ ] **Step 3: Commit implementation**
371 +- [x] **Step 3: Commit implementation**
371 373 ```text
372 374 git add extensions/ultra

docs/super/plans/2026-07-15-overkill-phase-1-contracts-run-state.md

Modified
9 9 **Architecture:** Keep contract logic in pure Node-only modules under `extensions/overkill/lib/`, with a thin `index.ts` Pi adapter.
11 +**Status:** Reconciled on 2026-08-10 against `extensions/overkill`; contracts and run-state work shipped.
11 13 > The adapter must not read held-out item bodies after structural suite preflight, and no Phase 1 status, cache, manifest, or custom entry may contain them.
13 15 ## 1. Package and real runtime loading

docs/super/plans/2026-07-15-overkill-phase-2-isolated-baseline-rollouts.md

Modified
7 7 **Goal:** Evaluate the unchanged loaded skill sequentially on the trusted validation suite through Pi's normal `/skill:<name>` expansion path, with a frozen invoking model, a private resumable score cache, bounded checker evidence, and no source or suite mutation.
9 9 **Architecture:** Keep rollout orchestration in `extensions/overkill/lib/rollouts.ts` behind injected SDK and checker seams.
11 +**Status:** Reconciled on 2026-08-10 against `extensions/overkill`; isolated baseline rollout work shipped.
10 12 Production supplies a `DefaultResourceLoader`, `SessionManager.inMemory()`, and `createAgentSession()` seam.
11 13 Tests supply deterministic target-session factories and checker executors, so no test contacts a model provider.

docs/super/plans/2026-07-15-overkill-phase-3-optimizer-patches-strict-gate.md

Modified
7 7 **Goal:** Complete the explicit-suite engine with isolated frozen-model optimizer sessions, bounded atomic body patches, a strict validation gate, one report-only final test for accepted work, and private staging only.
9 9 **Architecture:** Add pure patch and training orchestration modules under `extensions/overkill/lib/`.
11 +**Status:** Reconciled on 2026-08-10 against `extensions/overkill`; optimizer patch gate work shipped.
10 12 The orchestrator reuses Phase 2 target rollouts, checker evidence, cache, cancellation, disposal, source/suite revalidation, and branch-linked persistence through explicit injected seams.
11 13 Production creates a fresh in-memory optimizer session with only a terminating TypeBox `structured_output` tool.
12 14 Tests inject deterministic optimizer sessions and target factories, so no test invokes a provider.

docs/super/plans/2026-07-15-overkill-phase-4-modes-review-cancellation.md

Modified
7 7 **Goal:** Make the completed explicit-suite engine observable and safely interruptible in TUI, RPC, JSON, and print modes.
9 9 **Architecture:** Keep mode-neutral formatting, bounded review-diff, call estimation, and run-progress derivation in a pure `lib/modes.ts` module.
11 +**Status:** Reconciled on 2026-08-10 against `extensions/overkill`; modes, review, and cancellation work shipped.
10 12 Keep the extension adapter responsible for Pi UI protocol calls, fd-1 print writes, temporary terminal/SIGINT listeners, append-only run entries, and run ownership.
11 13 A single active run owns one `AbortController`; every cancellation source calls the same idempotent request function.

docs/super/plans/2026-07-15-overkill-phase-5-aftermath-harvest-mining.md

Modified
7 7 **Goal:** Add the pre-replay `/overkill aftermath` workflow that deterministically snapshots persisted active branches, obtains one explicitly confirmed loaded skill, freezes bounded unredacted task records, and assigns stable nonempty splits.
9 9 **Architecture:** Put session-to-digest extraction, canonical bounds, skill evidence, and confirmation arithmetic in pure `lib/aftermath-harvest.ts`.
11 +**Status:** Reconciled on 2026-08-10 against `extensions/overkill`; Aftermath harvest and mining work shipped.
10 12 Put proposal validation, canonical task IDs, split assignment, and chunk/checkpoint scheduling in pure `lib/aftermath-mining.ts`.
11 13 Use `lib/aftermath-state.ts` for narrow immutable private artifact schemas built on the existing atomic run directory helpers.
12 14 Keep Pi session opening, UI selection/confirmation, fresh structured-output miner construction, branch-link entries, and mode-specific notifications in `index.ts`.

docs/super/plans/2026-07-15-overkill-phase-6-aftermath-scoring-integration.md

Modified
7 7 **Goal:** Complete Aftermath by scoring immutable mined tasks and routing them through the existing core rollout, optimizer, strict-gate, final-test, staging, persistence, cancellation, review, resume, and mode contracts.
9 9 **Architecture:** Add pure deterministic response scoring and task-to-core adaptation in `lib/aftermath-scoring.ts`.
11 +**Status:** Reconciled on 2026-08-10 against `extensions/overkill`; Aftermath scoring integration work shipped.
10 12 Add a narrowly shared fresh terminating structured-output-session primitive in `lib/optimizer.ts` and use it for isolated rubric judges.
11 13 Extend narrow Aftermath persistence schemas for judge cache and replay state in `lib/aftermath-state.ts`.
12 14 Refactor only the core execution seam in `index.ts` so suite and Aftermath supply different task/scorer adapters to one target rollout and durable training path.

docs/super/plans/2026-07-15-the-system-phase-6-rich-markdown-bundle-kernel.md

Modified
15 15 **Phase:** Phase 6: Rich Markdown bundle kernel migration
17 +**Status:** Reconciled on 2026-08-10 against `extensions/the-system`; rich Markdown bundle work shipped.
19 21 ## Preconditions And Boundaries
69 71 - Modify: `extensions/the-system/package.json`
70 72 - Modify: `package-lock.json`
72 -- [ ] **Step 1: Verify the lockfile precondition**
74 +- [x] **Step 1: Verify the lockfile precondition**
83 85 If it does, stop and report the lockfile blocker.
85 -- [ ] **Step 2: Declare the parser dependencies**
87 +- [x] **Step 2: Declare the parser dependencies**
87 89 Add this runtime dependency block to `extensions/the-system/package.json` before `peerDependencies`, and add `"@types/mdast": "^4.0.4"` to `devDependencies`:
108 110 Expected: the lock records these dependencies under `extensions/the-system` and changes no unrelated package definitions.
110 -- [ ] **Step 3: Write failing parser-profile tests**
112 +- [x] **Step 3: Write failing parser-profile tests**
112 114 Create `extensions/the-system/__tests__/markdown.test.ts` with this starting content:
194 -- [ ] **Step 4: Run the parser tests to verify RED**
196 +- [x] **Step 4: Run the parser tests to verify RED**
202 204 Expected: FAIL because `markdown.ts` does not exist.
204 -- [ ] **Step 5: Implement the shared parser**
206 +- [x] **Step 5: Implement the shared parser**
206 208 Create `extensions/the-system/markdown.ts` around this public contract:
336 338 Do not render, sanitize, or rewrite links in this file.
338 -- [ ] **Step 6: Run focused and type checks**
340 +- [x] **Step 6: Run focused and type checks**
347 349 Expected: parser tests PASS and typecheck/static checks PASS.
349 -- [ ] **Step 7: Commit the parser slice**
351 +- [x] **Step 7: Commit the parser slice**
351 353 ```bash
352 354 git add extensions/the-system/markdown.ts \
369 371 Do not add an alias from HTML paths to bundle paths.
371 -- [ ] **Step 1: Add failing bundle and metadata tests**
373 +- [x] **Step 1: Add failing bundle and metadata tests**
373 375 Add fixtures shaped like:
430 432 - flat HTML, wrong type directories, uppercase/bad slugs, nested `other/index.md`, and mismatched IDs fail;
431 433 - graph indexing and candidate replacement retain stable duplicate, dangling, forbidden-edge, and crossed-roadmap diagnostics using `markdown` sources.
433 -- [ ] **Step 2: Add failing filesystem discovery tests**
435 +- [x] **Step 2: Add failing filesystem discovery tests**
435 437 Use the existing temp-tree helpers to prove `discoverDocumentBundles(root)`:
461 -- [ ] **Step 3: Run the document tests to verify RED**
463 +- [x] **Step 3: Run the document tests to verify RED**
463 465 ```bash
464 466 mise run test -- extensions/the-system/__tests__/documents.test.ts
467 469 Expected: FAIL because bundle APIs do not exist.
469 -- [ ] **Step 4: Add the bundle API to `documents.ts`**
471 +- [x] **Step 4: Add the bundle API to `documents.ts`**
471 473 Add these contracts:
787 789 Do not follow symlinks.
789 -- [ ] **Step 5: Route indexing and candidates through bundle sources**
791 +- [x] **Step 5: Route indexing and candidates through bundle sources**
791 793 Implement the bundle graph route as follows while the old HTML functions remain only for the not-yet-migrated runtime caller:
937 939 Preserve the existing baseline-diagnostic suppression behavior in candidate validation.
939 -- [ ] **Step 6: Run kernel checks**
941 +- [x] **Step 6: Run kernel checks**
941 943 ```bash
942 944 mise run test -- extensions/the-system/__tests__/markdown.test.ts \
947 949 Expected: new parser/bundle tests PASS; old runtime/doctor callers still compile because their HTML exports have not yet been removed.
949 -- [ ] **Step 7: Commit the bundle kernel**
951 +- [x] **Step 7: Commit the bundle kernel**
951 953 ```bash
952 954 git add extensions/the-system/documents.ts \
964 966 - Modify: `extensions/the-system/__tests__/init.test.ts`
965 967 - Modify: `extensions/the-system/__tests__/doctor.test.ts`
967 -- [ ] **Step 1: Write failing schema-v2 initialization tests**
969 +- [x] **Step 1: Write failing schema-v2 initialization tests**
969 971 Replace machine-asset expectations with:
1005 1007 Assert a symlink at `.system/system.css` fails with `init.unsafe-path` instead of being removed.
1007 -- [ ] **Step 2: Write failing doctor bundle tests**
1009 +- [x] **Step 2: Write failing doctor bundle tests**
1009 1011 Rewrite doctor fixtures around bundle `index.md` files and schema-v2 config.
1019 1021 - a complete bundle system is green;
1020 1022 - CLI output and no-mutation snapshots remain stable.
1022 -- [ ] **Step 3: Run initialization and doctor tests to verify RED**
1024 +- [x] **Step 3: Run initialization and doctor tests to verify RED**
1024 1026 ```bash
1025 1027 mise run test -- extensions/the-system/__tests__/init.test.ts \
1029 1031 Expected: FAIL on style/config and flat-HTML assumptions.
1031 -- [ ] **Step 4: Make config schema v2 exact**
1033 +- [x] **Step 4: Make config schema v2 exact**
1033 1035 In `documents.ts`, set `SCHEMA_VERSION` to `2` and make current config exactly:
1093 1095 Runtime and normal document operations continue using strict `parseSystemConfig` and therefore never accept `styleVersion` as current config.
1095 -- [ ] **Step 5: Make initialization config-only**
1097 +- [x] **Step 5: Make initialization config-only**
1097 1099 Replace `MachineAssets` with:
1120 1122 for (const item of result.removed) console.log(`REMOVED ${item}`);
1123 -- [ ] **Step 6: Route doctor through shared bundle discovery**
1125 +- [x] **Step 6: Route doctor through shared bundle discovery**
1125 1127 Delete doctor-local HTML collection, mockup-owner matching, style-version checks, and CSS-required state.
1145 1147 A non-regular CSS path remains an unsafe filesystem diagnostic.
1147 -- [ ] **Step 7: Run focused and regression tests**
1149 +- [x] **Step 7: Run focused and regression tests**
1149 1151 ```bash
1150 1152 mise run test -- extensions/the-system/__tests__/init.test.ts \
1157 1159 Expected: all listed suites PASS; runtime remains on the temporary HTML route but uses current initialization/config successfully.
1159 -- [ ] **Step 8: Hold the migration for the runtime cutover**
1161 +- [x] **Step 8: Hold the migration for the runtime cutover**
1161 1163 Do not commit Task 3 separately.
1176 1178 - Modify: `extensions/the-system/__tests__/documents.test.ts`
1177 1179 - Delete: `extensions/the-system/assets/system.css`
1179 -- [ ] **Step 1: Rewrite runtime fixtures as bundles**
1181 +- [x] **Step 1: Rewrite runtime fixtures as bundles**
1181 1183 Replace the flat-HTML fixture helpers with:
1206 1208 Use a YAML serializer helper or literal fixture strings for nested values; do not rely on JSON array syntax if the YAML parser configuration rejects it.
1208 -- [ ] **Step 2: Write failing bundle-governance tests**
1210 +- [x] **Step 2: Write failing bundle-governance tests**
1248 -- [ ] **Step 3: Run runtime tests to verify RED**
1250 +- [x] **Step 3: Run runtime tests to verify RED**
1250 1252 ```bash
1251 1253 mise run test -- extensions/the-system/__tests__/system.test.ts
1254 1256 Expected: FAIL on every flat-HTML assumption.
1256 -- [ ] **Step 4: Replace runtime path classification**
1258 +- [x] **Step 4: Replace runtime path classification**
1258 1260 Delete `MOCKUP_NAME`, direct/nested HTML classifiers, mockup HTML validation, and runtime-local source collection.
1289 1291 Keep the existing root containment and symlink-ancestor checks.
1291 -- [ ] **Step 5: Route validation and ownership through one bundle resolver**
1293 +- [x] **Step 5: Route validation and ownership through one bundle resolver**
1293 1295 Add this resolver beside the existing candidate-edit helpers:
1374 -- [ ] **Step 6: Replace the governed-document branch in `preflightFileMutation`**
1376 +- [x] **Step 6: Replace the governed-document branch in `preflightFileMutation`**
1376 1378 Keep the existing root discovery, root containment, core handling, symlink-ancestor rejection, `candidateContent`, diagnostic formatting, and approval text.
1459 1461 Asset bytes are never parsed or sanitized.
1461 -- [ ] **Step 7: Expand shell recognition minimally**
1463 +- [x] **Step 7: Expand shell recognition minimally**
1463 1465 Replace the old `.html` matcher with a matcher that recognizes:
1472 1474 Keep the explicit advisory message and do not claim shell sandboxing.
1474 -- [ ] **Step 8: Delete the HTML kernel and stylesheet**
1476 +- [x] **Step 8: Delete the HTML kernel and stylesheet**
1476 1478 After every caller uses bundle APIs, delete from `documents.ts`:
1488 1490 Remove every old HTML/CSS test rather than preserving compatibility assertions.
1490 -- [ ] **Step 9: Run all Phase 6 code tests**
1492 +- [x] **Step 9: Run all Phase 6 code tests**
1492 1494 ```bash
1493 1495 mise run test -- extensions/the-system/__tests__/markdown.test.ts \
1501 1503 Expected: all PASS and no live code imports removed HTML/CSS symbols.
1503 -- [ ] **Step 10: Commit the atomic governance cutover**
1505 +- [x] **Step 10: Commit the atomic governance cutover**
1505 1507 Stage Task 3 and Task 4 together:
1530 1532 - Modify: `extensions/the-system/README.md`
1531 1533 - Modify: `extensions/the-system/CHANGELOG.md`
1533 -- [ ] **Step 1: Write failing skill-contract tests**
1535 +- [x] **Step 1: Write failing skill-contract tests**
1535 1537 Replace HTML assertions with exact required phrases covering:
1569 1571 Keep brainstorming persistence assertions unchanged because Phase 8 owns that migration.
1571 -- [ ] **Step 2: Run workflow tests to verify RED**
1573 +- [x] **Step 2: Run workflow tests to verify RED**
1573 1575 ```bash
1574 1576 mise run test -- extensions/the-system/__tests__/workflow-skills.test.ts
1577 1579 Expected: FAIL on old HTML and CSS instructions.
1579 -- [ ] **Step 3: Rewrite `system-documents`**
1581 +- [x] **Step 3: Rewrite `system-documents`**
1581 1583 Keep it the single authority.
1595 1597 Remove HTML shell, `system-meta`, shared CSS, and active-resource prohibition sections completely.
1597 -- [ ] **Step 4: Rewrite the initialization topology draft**
1599 +- [x] **Step 4: Rewrite the initialization topology draft**
1599 1601 In `the-system-init`, make the proposed `SYSTEM.md` draft state:
1609 1611 Make upgrade output explain removal of obsolete machine-owned `system.css` before asking approval.
1611 -- [ ] **Step 5: Update current README and changelog**
1613 +- [x] **Step 5: Update current README and changelog**
1613 1615 Document only Phase 6 surfaces:
1622 1624 Do not document unavailable `/system-view`, `/system-book`, or `/system-spec` commands.
1624 -- [ ] **Step 6: Format only planned files, then run skill and package checks**
1626 +- [x] **Step 6: Format only planned files, then run skill and package checks**
1626 1628 ```bash
1627 1629 mise x -- biome check --write \
1651 1653 Expected: all PASS unless unrelated concurrent work blocks repository-wide lint; report such a blocker with its exact path and do not alter it.
1653 -- [ ] **Step 7: Commit authority and documentation updates**
1655 +- [x] **Step 7: Commit authority and documentation updates**
1655 1657 ```bash
1656 1658 git add extensions/the-system/skills/system-documents/SKILL.md \
1668 1670 - No planned source changes.
1669 1671 - Modify only a Phase 6 file if verification exposes a defect in that file.
1671 -- [ ] **Step 1: Verify no authored-HTML legacy remains**
1673 +- [x] **Step 1: Verify no authored-HTML legacy remains**
1687 1689 Historical `docs/super/**` is intentionally outside this scan.
1689 -- [ ] **Step 2: Run every The System unit/integration test**
1691 +- [x] **Step 2: Run every The System unit/integration test**
1691 1693 ```bash
1692 1694 mise run test -- extensions/the-system/__tests__
1695 1697 Expected: all The System suites PASS.
1697 -- [ ] **Step 3: Run retained browser regression tests**
1699 +- [x] **Step 3: Run retained browser regression tests**
1699 1701 ```bash
1700 1702 mise //extensions/the-system:e2e
1705 1707 Phase 6 adds no renderer browser surface.
1707 -- [ ] **Step 4: Verify scoped formatting, then run repository gates**
1709 +- [x] **Step 4: Verify scoped formatting, then run repository gates**
1709 1711 ```bash
1710 1712 mise x -- biome ci \
1737 1739 If unrelated concurrent work blocks a repository-wide gate, preserve it, report the exact path/error, and retain the successful focused evidence.
1739 -- [ ] **Step 5: Audit source and staged scope**
1741 +- [x] **Step 5: Audit source and staged scope**
1741 1743 ```bash
1742 1744 git status --short
1748 1750 Expected: only planned Phase 6 files appear in the four implementation commits; unrelated dirty work remains unstaged.
1750 -- [ ] **Step 6: Record completion evidence**
1752 +- [x] **Step 6: Record completion evidence**
1752 1754 Do not create an empty verification commit.

docs/super/plans/2026-07-16-tune-cross-platform-runner.md

Modified
13 13 **Phase:** Single-plan implementation
15 +**Status:** Reconciled on 2026-08-10 against `extensions/tune`; cross-platform runner work shipped.
17 19 ## Task 1: Establish Regression Harness and No-Bash RED
21 23 - Modify: `extensions/tune/__tests__/harness.test.ts`
22 24 - Modify: `scripts/test_extensions_static_check.mjs`
24 -- [ ] **Step 1: Add a deterministic active-session helper**
26 +- [x] **Step 1: Add a deterministic active-session helper**
26 28 Activate Tune without invoking `/tune`, because `/tune` sends an asynchronous user message.
27 29 Create the persisted config, acquire the real session lock, and reconstruct through `session_tree`:
55 57 All public benchmark and VCS assertions must call the registered tools through `t.run`.
56 58 Direct definition execution is allowed only where the harness DSL cannot expose `onUpdate` or an external `AbortSignal`.
58 -- [ ] **Step 2: Add the static no-Bash contract**
60 +- [x] **Step 2: Add the static no-Bash contract**
60 62 Add before production changes:
65 67 assert(!tuneIndex.includes("exec(\"bash\""));
68 -- [ ] **Step 3: Verify RED**
70 +- [x] **Step 3: Verify RED**
83 85 - Modify: `extensions/tune/__tests__/harness.test.ts`
84 86 - Modify: `extensions/tune/index.ts:715-747`
86 -- [ ] **Step 1: Add exact-call and failure-order tests**
88 +- [x] **Step 1: Add exact-call and failure-order tests**
88 90 Add mocked unit cases for direct arguments and failure ordering:
124 126 Add the equivalent nonzero `git clean` case and require `git clean failed:` with bounded stderr.
126 -- [ ] **Step 2: Add a real Git repository test through `log_experiment`**
128 +- [x] **Step 2: Add a real Git repository test through `log_experiment`**
128 130 In `harness.test.ts`, initialize a real temporary Git repository, configure local author identity, commit `tracked.txt`, then modify it and add `untracked.txt` plus `.pi/tune/ideas.md`.
129 131 Activate Tune with Task 1's helper and call:
146 148 Assert the tracked file is restored, the untracked file is deleted, and both `ideas.md` and the appended discard entry in `session.jsonl` survive.
147 149 This test detects incorrect Git pathspec semantics that mocked argument tests cannot.
149 -- [ ] **Step 3: Verify RED**
151 +- [x] **Step 3: Verify RED**
157 159 Expected: mocked calls observe `bash -c`; the real repository test does not exercise direct Git calls.
159 -- [ ] **Step 4: Implement direct Git discard**
161 +- [x] **Step 4: Implement direct Git discard**
161 163 Execute and check these calls sequentially:
193 195 Keep jj and the existing success text unchanged.
195 -- [ ] **Step 5: Verify GREEN and commit**
197 +- [x] **Step 5: Verify GREEN and commit**
197 199 ```text
198 200 mise run test -- extensions/tune/__tests__/unit.test.ts extensions/tune/__tests__/harness.test.ts
211 213 - Modify: `extensions/tune/__tests__/remaining.test.ts`
212 214 - Modify: `extensions/tune/index.ts:145-157,289-299,596-606,1980-2320`
214 -- [ ] **Step 1: Add fixed-schema and real-tool behavior tests**
216 +- [x] **Step 1: Add fixed-schema and real-tool behavior tests**
216 218 Assert `run_experiment` has no `command` property.
217 219 Through `t.run(when(...calls("run_experiment", params)))`, cover:
246 248 expect(result.text).toContain("stderr");
249 -- [ ] **Step 2: Add partial-update and abort tests on the registered definition**
251 +- [x] **Step 2: Add partial-update and abort tests on the registered definition**
251 253 Call the same registered definition with `createContext()` only because harness records do not expose `onUpdate` or external cancellation.
252 254 A benchmark prints immediately and exits after 1.2 seconds; assert at least one update includes its output.
253 255 For abort, use an `AbortController`, abort after spawn, and assert rejection with `aborted`.
255 -- [ ] **Step 3: Add descendant termination tests through the real tool**
257 +- [x] **Step 3: Add descendant termination tests through the real tool**
257 259 Write a benchmark that spawns a child scheduled to create a marker after 300 ms, then remains alive.
258 260 Run once with `timeout_seconds: 0.05` through `t.run`, and once through registered-definition execution with an abort signal.
259 261 Wait 500 ms after each run and assert the marker never exists.
260 262 This proves termination kills descendants, not only the benchmark parent.
262 -- [ ] **Step 4: Verify RED**
264 +- [x] **Step 4: Verify RED**
270 272 Expected: schema and `{}` tool calls fail against the command-string runner.
272 -- [ ] **Step 5: Remove command strings and launch the fixed MJS file**
274 +- [x] **Step 5: Remove command strings and launch the fixed MJS file**
274 276 Delete `isBenchmarkCommand`, its `__test` export, and its unit/remaining tests.
275 277 Remove `command` from `RunParams`.
289 291 Keep output accumulation, updates, spill files, timing, parsing, checks, and result construction otherwise unchanged.
290 292 Update tool guidance and rendering to show the fixed benchmark and `run_experiment({})`.
292 -- [ ] **Step 6: Implement deterministic single-flight termination**
294 +- [x] **Step 6: Implement deterministic single-flight termination**
294 296 Change `killTree` to return `Promise<void>` and accept optional platform/taskkill/direct-signal dependencies for controlled tests while production uses real defaults.
295 297 On POSIX, retain negative-PID signalling with direct-PID fallback.
317 319 Both paths clear timers/listeners, await termination, close the spill stream, then settle once.
318 320 The close path rejects on abort and otherwise resolves the benchmark result.
320 -- [ ] **Step 7: Add Windows taskkill availability and controlled tests**
322 +- [x] **Step 7: Add Windows taskkill availability and controlled tests**
322 324 Resolve `taskkill.exe` once from `SystemRoot\\System32`.
323 325 On `session_start`, report one info notification when it is absent; direct child signalling remains fallback.
327 329 Emit two `session_start` events with an injected missing path and assert only one info notification.
328 330 Skip only the native-Windows real-tool fixture on other platforms; helper ordering tests run everywhere.
330 -- [ ] **Step 8: Verify GREEN and commit**
332 +- [x] **Step 8: Verify GREEN and commit**
332 334 ```text
333 335 mise run test -- extensions/tune/__tests__/*.test.ts
346 348 - Modify: `extensions/tune/hooks.ts:100-110`
347 349 - Modify: `extensions/tune/index.ts:2220-2230`
349 -- [ ] **Step 1: Add PATH-shadow regression tests**
351 +- [x] **Step 1: Add PATH-shadow regression tests**
351 353 Prepend a controlled fake `node` executable that writes a marker and exits nonzero.
352 354 Run a real hook MJS and a passing benchmark plus checks MJS.
355 357 Restore `PATH` in `finally`.
356 358 This fails against current `spawn("node")` and `pi.exec("node", ...)` calls.
358 -- [ ] **Step 2: Verify RED**
360 +- [x] **Step 2: Verify RED**
360 362 ```text
361 363 mise run test -- extensions/tune/__tests__/unit.test.ts extensions/tune/__tests__/harness.test.ts
364 366 Expected: hook or checks reaches the fake PATH executable.
366 -- [ ] **Step 3: Replace PATH-based Node calls**
368 +- [x] **Step 3: Replace PATH-based Node calls**
384 -- [ ] **Step 4: Verify GREEN and commit**
386 +- [x] **Step 4: Verify GREEN and commit**
386 388 ```text
387 389 mise run test -- extensions/tune/__tests__/unit.test.ts extensions/tune/__tests__/harness.test.ts
399 401 - Modify: `extensions/tune/CHANGELOG.md`
400 402 - Modify: `CHANGELOG.md`
402 -- [ ] **Step 1: Update documentation**
404 +- [x] **Step 1: Update documentation**
404 406 Document `run_experiment` without a command argument.
405 407 State that benchmark, checks, and hooks run with Pi's Node executable.
407 409 Remove accepted-command and wrapper examples.
408 410 Record the breaking tool parameter removal and direct Git discard.
410 -- [ ] **Step 2: Run repository checks**
412 +- [x] **Step 2: Run repository checks**
412 414 ```text
413 415 mise run fmt
419 421 Expected: every command exits zero, including the no-Bash static contract added before implementation.
421 -- [ ] **Step 3: Commit documentation and static guard**
423 +- [x] **Step 3: Commit documentation and static guard**
423 425 ```text
424 426 git add scripts/test_extensions_static_check.mjs extensions/tune/README.md extensions/tune/CHANGELOG.md CHANGELOG.md
432 434 - Verify only
434 -- [ ] **Step 1: Run Tune browser E2E**
436 +- [x] **Step 1: Run Tune browser E2E**
436 438 ```text
437 439 mise //extensions/tune:e2e
440 442 Expected: Chromium and Firefox dashboard tests pass.
442 -- [ ] **Step 2: Run full CI**
444 +- [x] **Step 2: Run full CI**
444 446 ```text
445 447 mise run ci
448 450 Expected: check, lint, test, and E2E exit zero.
450 -- [ ] **Step 3: Inspect final state**
452 +- [x] **Step 3: Inspect final state**
452 454 ```text
453 455 git status --short --branch

docs/super/plans/2026-07-17-leaks-detector-reliability-phase-1-detector-precision.md

Modified
13 13 **Phase:** Phase 1: Detector Precision
15 +**Status:** Reconciled on 2026-08-10 against `extensions/leaks`; detector precision work shipped.
17 19 ## Task 1: Wire Dedicated Property Tests
19 21 **Files:** `package.json`, `package-lock.json`, `mise.toml`, `extensions/leaks/vitest.fuzz.config.ts`, `extensions/leaks/__fuzz__/detectors.fuzz.test.ts`
21 -- [ ] Add these root dev dependencies:
23 +- [x] Add these root dev dependencies:
23 25 ```json
24 26 "@fast-check/vitest": "^0.4.1",
25 27 "fast-check": "^4.9.0"
28 -- [ ] Create `extensions/leaks/vitest.fuzz.config.ts`:
30 +- [x] Create `extensions/leaks/vitest.fuzz.config.ts`:
30 32 ```ts
31 33 import { defineConfig } from "vitest/config";
43 -- [ ] Add a smoke property using `test.prop({ text: fc.string() })` that calls `redactText` twice on fresh engines and expects equal changed/count/labels output.
45 +- [x] Add a smoke property using `test.prop({ text: fc.string() })` that calls `redactText` twice on fresh engines and expects equal changed/count/labels output.
45 -- [ ] Add a Mise `fuzz` task that runs Vitest through Node and enforces a hard 120-second process deadline with Node `spawnSync(..., { timeout: 120_000 })`; exit 124 on timeout.
47 +- [x] Add a Mise `fuzz` task that runs Vitest through Node and enforces a hard 120-second process deadline with Node `spawnSync(..., { timeout: 120_000 })`; exit 124 on timeout.
47 -- [ ] Define replay inputs `FC_SEED` and `FC_PATH` in the fuzz setup and pass them as `seed` and `path` to fast-check when set.
49 +- [x] Define replay inputs `FC_SEED` and `FC_PATH` in the fuzz setup and pass them as `seed` and `path` to fast-check when set.
49 -- [ ] Run `mise run lock && mise run fuzz`; expect PASS.
51 +- [x] Run `mise run lock && mise run fuzz`; expect PASS.
51 -- [ ] Commit `test(leaks): add dedicated property suite`.
53 +- [x] Commit `test(leaks): add dedicated property suite`.
53 55 ## Task 2: Establish The Precision Contract First
55 57 **Files:** `extensions/leaks/SPEC.md`
57 -- [ ] Replace “JWT decoding is out of scope” with exact JWT requirements: three strict Base64URL segments, decoded non-array JSON objects, nonempty string `alg`, nonempty strict signature.
59 +- [x] Replace “JWT decoding is out of scope” with exact JWT requirements: three strict Base64URL segments, decoded non-array JSON objects, nonempty string `alg`, nonempty strict signature.
59 -- [ ] Replace substring-sensitive names with separator-aware complete tokens.
61 +- [x] Replace substring-sensitive names with separator-aware complete tokens.
61 -- [ ] State that ambiguous assignments and context-only env names remain visible unless the value has a provider-specific shape or parsed secret component.
63 +- [x] State that ambiguous assignments and context-only env names remain visible unless the value has a provider-specific shape or parsed secret component.
63 -- [ ] Replace PuTTY-to-EOF behavior with exact `Private-Lines` consumption.
65 +- [x] Replace PuTTY-to-EOF behavior with exact `Private-Lines` consumption.
65 -- [ ] State Phase 1 still uses volatile HMAC12 mappings; durable V1 mappings remain Phase 2.
67 +- [x] State Phase 1 still uses volatile HMAC12 mappings; durable V1 mappings remain Phase 2.
67 -- [ ] Run `git diff --check -- extensions/leaks/SPEC.md`; expect no errors.
69 +- [x] Run `git diff --check -- extensions/leaks/SPEC.md`; expect no errors.
69 -- [ ] Commit `docs(leaks): specify precision-first detectors`.
71 +- [x] Commit `docs(leaks): specify precision-first detectors`.
71 73 ## Task 3: Parse Structured Candidates With Paired TDD
73 75 **Files:** `extensions/leaks/src/structures.ts`, `extensions/leaks/src/safety.ts`, `extensions/leaks/__tests__/structures.test.ts`, `extensions/leaks/__tests__/false-positives.test.ts`
75 -- [ ] Add JWT red/green cases:
77 +- [x] Add JWT red/green cases:
77 79 ```ts
78 80 expect(findJwtSpans("agendaFlick.visibleArea.yPosition")).toEqual([]);
91 -- [ ] Implement strict Base64URL validation before `Buffer.from`:
93 +- [x] Implement strict Base64URL validation before `Buffer.from`:
93 95 ```ts
94 96 function decodeJsonObject(segment: string) {
106 108 Catch parse/decode errors and return no span.
107 109 Require `typeof header.alg === "string" && header.alg.length > 0`.
109 -- [ ] Add query/cookie red/green cases:
111 +- [x] Add query/cookie red/green cases:
112 114 expect(findSensitiveQuerySpans("?monkey=ordinary-value")).toEqual([]);
120 -- [ ] Export one `isSensitiveName` helper from `safety.ts` that normalizes `-` to `_`, splits complete tokens, accepts explicit compound names such as `API_KEY` and `CLIENT_SECRET`, and never uses `includes`.
122 +- [x] Export one `isSensitiveName` helper from `safety.ts` that normalizes `-` to `_`, splits complete tokens, accepts explicit compound names such as `API_KEY` and `CLIENT_SECRET`, and never uses `includes`.
122 -- [ ] Scan URL candidates with a bounded regex, parse each with `new URL(candidate)`, and locate raw component spans by searching inside the unchanged candidate string; reject a candidate when a decoded value cannot be mapped uniquely to one raw source span.
124 +- [x] Scan URL candidates with a bounded regex, parse each with `new URL(candidate)`, and locate raw component spans by searching inside the unchanged candidate string; reject a candidate when a decoded value cannot be mapped uniquely to one raw source span.
124 -- [ ] Require strict Basic credentials with `/^[A-Za-z0-9+/]+={0,2}$/`, canonical Base64 re-encoding, and decoded `:`.
126 +- [x] Require strict Basic credentials with `/^[A-Za-z0-9+/]+={0,2}$/`, canonical Base64 re-encoding, and decoded `:`.
126 -- [ ] Parse cookies only from a complete `Cookie:` line and classify complete pair names with `isSensitiveName`.
128 +- [x] Parse cookies only from a complete `Cookie:` line and classify complete pair names with `isSensitiveName`.
128 -- [ ] Add assignment red/green cases for source constants, lower-camel references, type syntax, XML prose, provider-shaped config values, exact env-style values, transformed text, exact labels, and restoration.
130 +- [x] Add assignment red/green cases for source constants, lower-camel references, type syntax, XML prose, provider-shaped config values, exact env-style values, transformed text, exact labels, and restoration.
130 -- [ ] Replace broad assignment authority with line-anchored recognizers. Reject lines beginning with `const`, `let`, `var`, `function`, `class`, `type`, `interface`, or containing template/interpolation syntax. For JSON/YAML/TOML/XML-like forms, redact only `highConfidenceSecretShape(value)`; dotenv/env exact learning handles arbitrary opaque values.
132 +- [x] Replace broad assignment authority with line-anchored recognizers. Reject lines beginning with `const`, `let`, `var`, `function`, `class`, `type`, `interface`, or containing template/interpolation syntax. For JSON/YAML/TOML/XML-like forms, redact only `highConfidenceSecretShape(value)`; dotenv/env exact learning handles arbitrary opaque values.
132 -- [ ] Run `mise run test -- extensions/leaks/__tests__/structures.test.ts extensions/leaks/__tests__/false-positives.test.ts`; expect PASS.
134 +- [x] Run `mise run test -- extensions/leaks/__tests__/structures.test.ts extensions/leaks/__tests__/false-positives.test.ts`; expect PASS.
134 -- [ ] Commit `fix(leaks): parse structured secret candidates`.
136 +- [x] Commit `fix(leaks): parse structured secret candidates`.
136 138 ## Task 4: Bound Provider, Private-Key, And Environment Detection With Paired TDD
138 140 **Files:** `extensions/leaks/src/detectors.ts`, `extensions/leaks/src/dotenv.ts`, `extensions/leaks/__tests__/detectors.test.ts`, `extensions/leaks/__tests__/dotenv.test.ts`
140 -- [ ] For every provider rule, generate one deterministic valid control and three exact near misses: changed prefix, one-short length, and invalid alphabet. Assert exact zero or one span and exact label.
142 +- [x] For every provider rule, generate one deterministic valid control and three exact near misses: changed prefix, one-short length, and invalid alphabet. Assert exact zero or one span and exact label.
142 -- [ ] Replace the PuTTY regex with a line parser that finds `Private-Lines: N`, consumes exactly N subsequent Base64 lines, and ends before `Private-MAC`. Add a trailing sentinel assertion proving unrelated text remains unchanged after redaction/restoration.
144 +- [x] Replace the PuTTY regex with a line parser that finds `Private-Lines: N`, consumes exactly N subsequent Base64 lines, and ends before `Private-MAC`. Add a trailing sentinel assertion proving unrelated text remains unchanged after redaction/restoration.
144 -- [ ] Add env red/green cases:
146 +- [x] Add env red/green cases:
147 149 expect(learnEnvironmentValues({ GPG_KEY_ID: "0123456789abcdef" }).values)
159 161 Also cover `KEY`, `AUTH`, `SESSION`, `COOKIE`, `JWT`, `SEED`, public prefixes, and credentialed/uncredentialed URLs.
161 -- [ ] Split normalized env names into explicit high-precision, context-required, metadata-suffix, and public-prefix classes matching the spec table.
163 +- [x] Split normalized env names into explicit high-precision, context-required, metadata-suffix, and public-prefix classes matching the spec table.
163 -- [ ] Parse env URL values with `URL`; learn raw password and exact sensitive query values only. Do not learn the complete URL.
165 +- [x] Parse env URL values with `URL`; learn raw password and exact sensitive query values only. Do not learn the complete URL.
165 -- [ ] Run `mise run test -- extensions/leaks/__tests__/detectors.test.ts extensions/leaks/__tests__/dotenv.test.ts`; expect PASS.
167 +- [x] Run `mise run test -- extensions/leaks/__tests__/detectors.test.ts extensions/leaks/__tests__/dotenv.test.ts`; expect PASS.
167 -- [ ] Commit `fix(leaks): tighten provider and environment detection`.
169 +- [x] Commit `fix(leaks): tighten provider and environment detection`.
169 171 ## Task 5: Fuzz Every Detector Family
171 173 **Files:** `extensions/leaks/__fuzz__/arbitraries.ts`, `extensions/leaks/__fuzz__/detectors.fuzz.test.ts`
173 -- [ ] Build semantic arbitraries without importing production regexes for provider tokens, valid/invalid JWTs, URLs, query names, headers, cookies, assignments, private keys, dotenv/env names, and custom regex rules.
175 +- [x] Build semantic arbitraries without importing production regexes for provider tokens, valid/invalid JWTs, URLs, query names, headers, cookies, assignments, private keys, dotenv/env names, and custom regex rules.
175 -- [ ] Every family must generate empty, boundary-length, Unicode-surrounded, punctuation, quoted, multiline, and oversized cases.
177 +- [x] Every family must generate empty, boundary-length, Unicode-surrounded, punctuation, quoted, multiline, and oversized cases.
177 -- [ ] Positive properties assert exact span/value/label, transformed text, unchanged surrounding bytes, and restore identity.
179 +- [x] Positive properties assert exact span/value/label, transformed text, unchanged surrounding bytes, and restore identity.
179 -- [ ] Negative properties mutate one semantic requirement and assert zero spans and unchanged text.
181 +- [x] Negative properties mutate one semantic requirement and assert zero spans and unchanged text.
181 -- [ ] Add custom-regex properties for zero/one/multiple captures, empty-match progress, unsafe-pattern rejection, span boundaries, and adversarial runtime.
183 +- [x] Add custom-regex properties for zero/one/multiple captures, empty-match progress, unsafe-pattern rejection, span boundaries, and adversarial runtime.
183 -- [ ] Add engine properties for idempotence, no source mutation, selected non-overlap, and preservation outside selected spans.
185 +- [x] Add engine properties for idempotence, no source mutation, selected non-overlap, and preservation outside selected spans.
185 -- [ ] Prove shrinking/replay by temporarily forcing a property failure, capture reported seed/path, rerun with `FC_SEED` and `FC_PATH`, then restore the assertion. No failing code is committed.
187 +- [x] Prove shrinking/replay by temporarily forcing a property failure, capture reported seed/path, rerun with `FC_SEED` and `FC_PATH`, then restore the assertion. No failing code is committed.
187 -- [ ] Run `mise run fuzz && mise run test -- extensions/leaks/__tests__`; expect PASS.
189 +- [x] Run `mise run fuzz && mise run test -- extensions/leaks/__tests__`; expect PASS.
189 -- [ ] Commit `test(leaks): fuzz every detector boundary`.
191 +- [x] Commit `test(leaks): fuzz every detector boundary`.
191 193 ## Task 6: Phase Verification
193 195 **Files:** all Phase 1 files
195 -- [ ] Run `mise run fmt`.
197 +- [x] Run `mise run fmt`.
197 -- [ ] Run `mise run lint`.
199 +- [x] Run `mise run lint`.
199 -- [ ] Run `mise run test`.
201 +- [x] Run `mise run test`.
201 -- [ ] Run `mise run fuzz`; verify wall time is below two minutes.
203 +- [x] Run `mise run fuzz`; verify wall time is below two minutes.
203 -- [ ] Run `mise run check`.
205 +- [x] Run `mise run check`.
205 -- [ ] Inspect `git status --short` and preserve unrelated dirty files.
207 +- [x] Inspect `git status --short` and preserve unrelated dirty files.
207 -- [ ] Commit only any formatter changes belonging to Phase 1 as `style(leaks): format detector precision work`.
209 +- [x] Commit only any formatter changes belonging to Phase 1 as `style(leaks): format detector precision work`.
209 211 README and changelog remain Phase 3 scope.

docs/super/plans/2026-07-17-leaks-detector-reliability-phase-2-durable-lifecycle.md

Modified
7 7 **Tech stack:** TypeScript, Node crypto, Pi custom session entries, Vitest, fast-check.
9 +**Status:** Reconciled on 2026-08-10 against `extensions/leaks`; durable lifecycle work shipped.
9 11 ## Task 1: Versioned persistence primitives
11 13 - Add generation and mapping record types.

docs/super/plans/2026-07-17-leaks-detector-reliability-phase-3-integration-ci.md

Modified
4 4 # Leaks Reliability Phase 3 Integration And CI Plan
6 6 **Goal:** Prove durable redaction and strict hydration through real Pi execution, gate the repository against regressions, and ship the behavior as a CI-enforced release.
8 8 **Architecture:** Keep production changes small. Exercise the installed Pi agent loop with scripted provider responses and actual tool implementations. Add a tracked-source negative corpus and exact positive fixture assertions. Expand lifecycle properties around branch projections and failure commands. Put the bounded dedicated fuzz task in the release gate.
10 +**Status:** Reconciled on 2026-08-10 against `extensions/leaks`; integration and CI work shipped.
10 12 ## Task 1: Real agent-loop hydration
12 14 - Run scripted model responses through the actual agent loop into built-in and custom tools.

extensions/TODO.md

Modified
16 16 extension that scans session data for curse words and frustrations and show
17 17 graph over time.
18 18 check leaked claude code for killer regex.
19 -- [ ] pi-modes:
20 - simple personal modes
22 20 ## TUI

extensions/leaks/PLAN.md

Modified
15 15 **Phase:** Single-plan implementation.
17 +**Status:** Archived on 2026-08-10.
18 +This original in-memory rewrite plan conflicts with the current durable placeholder lifecycle in `extensions/leaks/SPEC.md` and the implemented code.
19 +Its unchecked boxes are historical, not current TODO.
17 21 **Plan Location:** `extensions/leaks/PLAN.md`.

extensions/leaks/__tests__/pi-direct.test.ts

Modified
284 284 await runtime.handlers.get("session_start")?.({}, ctx);
285 - expect(view.notices.join("\n")).not.toContain("session entry is not durable");
285 + expect(view.notices.join("\n")).not.toContain(
286 + "session entry is not durable",
287 + );
286 288 const secret = "ghp_" + "B".repeat(36);
287 289 const result = await runtime.handlers.get("before_provider_request")?.(
288 290 { payload: { text: secret } },

extensions/pulse/__tests__/index.test.ts

Modified
11 11 const {
12 12 default: pulse,
13 13 parsePulseArgs,
14 + pulseArgumentCompletions,
14 15 quotePulseArg,
15 16 __setPulseModelClient,
16 17 } = await import("../index.ts");
70 71 const statuses: Array<{ key: string; value: string | undefined }> = [];
71 72 const confirmations: string[] = [];
72 73 const editors: Array<{ title: string; prefill: string }> = [];
74 + const autocompleteFactories: any[] = [];
73 75 const entries: any[] = [];
74 76 let confirmResult = true;
75 77 let editorResult: string | undefined;
91 93 editors.push({ title, prefill });
92 94 return editorResult;
96 + addAutocompleteProvider(factory: any) {
97 + autocompleteFactories.push(factory);
98 + },
95 100 modelRegistry: {
96 101 async getApiKeyAndHeaders() {
132 137 statuses,
133 138 confirmations,
134 139 editors,
140 + autocompleteFactories,
135 141 entries,
136 142 setConfirmResult(value: boolean) {
137 143 confirmResult = value;
199 205 expect(readConfig(root).documents).toEqual([]);
208 + it("completes pulse args when explicit tab forces file completion", async () => {
209 + const root = cwd();
210 + writeConfig(root, { documents: [{ path: "README.md" }] });
211 + const h = harness(root);
213 + await h.events.get("session_start")({}, h.ctx);
214 + const provider = h.autocompleteFactories[0]({
215 + async getSuggestions() {
216 + return null;
217 + },
218 + applyCompletion() {
219 + throw new Error("unused");
220 + },
221 + shouldTriggerFileCompletion() {
222 + return false;
223 + },
224 + });
225 + const line = "/pulse remove ";
227 + expect(provider.shouldTriggerFileCompletion([line], 0, line.length)).toBe(
228 + true,
229 + );
230 + await expect(
231 + provider.getSuggestions([line], 0, line.length, {
232 + signal: new AbortController().signal,
233 + force: true,
234 + }),
235 + ).resolves.toEqual({
236 + items: [{ value: "remove README.md", label: "README.md" }],
237 + prefix: "remove ",
238 + });
239 + });
241 + it("completes pulse arguments directly", () => {
242 + const root = cwd();
243 + writeConfig(root, { documents: [{ path: "README.md" }] });
245 + expect(pulseArgumentCompletions("remove ", root)).toEqual([
246 + { value: "remove README.md", label: "README.md" },
247 + ]);
248 + });
202 250 it("rejects the removed config subcommand", async () => {
203 251 const root = cwd();
204 252 const h = harness(root);

extensions/pulse/index.ts

Modified
621 621 return results.length > 0 ? results : null;
624 +function pulseArgumentText(
625 + lines: string[],
626 + cursorLine: number,
627 + cursorCol: number,
628 +): string | null {
629 + const beforeCursor = (lines[cursorLine] || "").slice(0, cursorCol);
630 + const match = beforeCursor.match(/^\/pulse\s+(.*)$/);
631 + return match ? match[1] : null;
634 +export function pulseArgumentCompletions(
635 + argumentText: string,
636 + cwd: string,
637 +): AutocompleteItem[] | null {
638 + const spaceIdx = argumentText.indexOf(" ");
639 + const noSubcmdArg = spaceIdx === -1 && !argumentText.endsWith(" ");
641 + if (noSubcmdArg) {
642 + const filtered = SUBCOMMANDS.filter((s) => s.startsWith(argumentText));
643 + if (filtered.length > 0 || argumentText === "") {
644 + return filtered.map((s) => ({ value: s, label: s }));
646 + return null;
649 + const subcmd = (
650 + spaceIdx === -1 ? argumentText : argumentText.slice(0, spaceIdx)
651 + ).toLowerCase() as Subcommand;
652 + const argPrefix = spaceIdx === -1 ? "" : argumentText.slice(spaceIdx + 1);
653 + const withSubcmd = (items: AutocompleteItem[] | null) => {
654 + if (!items) return null;
655 + const subPart = argumentText.slice(
656 + 0,
657 + spaceIdx === -1 ? argumentText.length : spaceIdx + 1,
658 + );
659 + return items.map((it) => ({
660 + value: subPart + it.value,
661 + label: it.label ?? it.value,
662 + }));
663 + };
665 + switch (subcmd) {
666 + case "add":
667 + return withSubcmd(getPathCompletions(cwd, argPrefix, "file"));
668 + case "add-dir":
669 + return withSubcmd(getPathCompletions(cwd, argPrefix, "dir"));
670 + case "remove":
671 + return withSubcmd(getDocCompletions(cwd, argPrefix));
672 + default:
673 + return null;
624 677 function gitFingerprint(cwd: string): string | null {
626 679 return execFileSync(
1382 1435 pi.registerCommand("pulse", {
1383 1436 description: "Pulse - living documentation sync",
1384 - // FIXME: Explicit TAB on "/pulse remove " (space at end) forces file completions
1385 - // instead of calling getArgumentCompletions. Pi's handleTabCompletion() routes
1386 - // "/cmd arg " to forceFileAutocomplete(force=true), which skips the slash command
1387 - // branch in getSuggestions(). Only auto-popup (typing) uses force=false.
1388 - // See: https://github.com/badlogic/pi-mono/issues/2874
1389 1437 getArgumentCompletions(argumentText: string): AutocompleteItem[] | null {
1390 - const cwd = state.cwd || getCwd(pi);
1391 - // Pi passes the ENTIRE text after the command name as argumentText.
1392 - // e.g. "/pulse remove p" → argumentText = "remove p"
1393 - // Pi replaces all of argumentText with item.value on completion.
1394 - // So item values must include the subcommand prefix.
1395 - const spaceIdx = argumentText.indexOf(" ");
1396 - const noSubcmdArg = spaceIdx === -1 && !argumentText.endsWith(" ");
1398 - if (noSubcmdArg) {
1399 - const filtered = SUBCOMMANDS.filter((s) => s.startsWith(argumentText));
1400 - if (filtered.length > 0 || argumentText === "") {
1401 - return filtered.map((s) => ({ value: s, label: s }));
1403 - return null;
1406 - const subcmd = (
1407 - spaceIdx === -1 ? argumentText : argumentText.slice(0, spaceIdx)
1408 - ).toLowerCase() as Subcommand;
1409 - const argPrefix = spaceIdx === -1 ? "" : argumentText.slice(spaceIdx + 1);
1411 - // Prepend subcommand to values so pi's full-prefix replacement preserves it
1412 - const withSubcmd = (
1413 - items: AutocompleteItem[] | null,
1414 - ): AutocompleteItem[] | null => {
1415 - if (!items) return null;
1416 - const subPart = argumentText.slice(
1417 - 0,
1418 - spaceIdx === -1 ? argumentText.length : spaceIdx + 1,
1419 - );
1420 - return items.map((it) => ({
1421 - value: subPart + it.value,
1422 - label: it.label ?? it.value,
1423 - }));
1424 - };
1426 - switch (subcmd) {
1427 - case "add":
1428 - return withSubcmd(getPathCompletions(cwd, argPrefix, "file"));
1429 - case "add-dir":
1430 - return withSubcmd(getPathCompletions(cwd, argPrefix, "dir"));
1431 - case "remove":
1432 - return withSubcmd(getDocCompletions(cwd, argPrefix));
1433 - default:
1434 - return null;
1438 + return pulseArgumentCompletions(argumentText, state.cwd || getCwd(pi));
1437 1440 async handler(args, ctx) {
1438 1441 state.cwd = getCwd(pi, ctx);
1519 1522 const ticket = ++generation;
1520 1523 stopTimer();
1521 1524 state.cwd = getCwd(pi, ctx as any);
1525 + (ctx as any).ui.addAutocompleteProvider?.((current: any) => ({
1526 + async getSuggestions(
1527 + lines: string[],
1528 + cursorLine: number,
1529 + cursorCol: number,
1530 + options: { signal: AbortSignal; force?: boolean },
1531 + ) {
1532 + const argumentText = pulseArgumentText(lines, cursorLine, cursorCol);
1533 + if (argumentText !== null) {
1534 + const items = pulseArgumentCompletions(argumentText, state.cwd);
1535 + if (items?.length) return { items, prefix: argumentText };
1537 + return current.getSuggestions(lines, cursorLine, cursorCol, options);
1538 + },
1539 + applyCompletion(
1540 + lines: string[],
1541 + cursorLine: number,
1542 + cursorCol: number,
1543 + item: AutocompleteItem,
1544 + prefix: string,
1545 + ) {
1546 + return current.applyCompletion(
1547 + lines,
1548 + cursorLine,
1549 + cursorCol,
1550 + item,
1551 + prefix,
1552 + );
1553 + },
1554 + shouldTriggerFileCompletion(
1555 + lines: string[],
1556 + cursorLine: number,
1557 + cursorCol: number,
1558 + ) {
1559 + if (pulseArgumentText(lines, cursorLine, cursorCol) !== null)
1560 + return true;
1561 + return (
1562 + current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ??
1563 + true
1564 + );
1565 + },
1566 + }));
1523 1568 const loaded = loadConfigResult(state.cwd);
1524 1569 if (loaded.error) {

extensions/ultra/AGENTS.md

Modified
1 1 # Ultra
3 -- Keep runtime code, tool prompts/schema guidance, and bundled skill guidance semantically synchronized; update every affected surface and lockstep test when contracts change.
3 +- Keep runtime code, tool prompts/schema guidance, and injected authoring prompt guidance semantically synchronized; update every affected surface and lockstep test when contracts change.

extensions/ultra/README.md

Modified
10 10 - **`/ultra <name> [args]`** — interactive command. Runs a saved workflow behind a
11 11 live overlay: a per-agent board, `Tab`/`↑↓` to focus an agent and drill into its
12 - streaming transcript, steer a running sub-agent, and `Esc` to abort. UI only —
13 - headless callers use the tool.
14 -- **`workflow` tool** — model-callable, mid-turn. Pass a saved workflow `name`
15 - (+ optional `args`), or an inline `spec` object for a one-off run. Returns the
16 - aggregated JSON; progress streams to a collapsible result surface.
12 + streaming transcript, steer a running sub-agent, and `Esc` to abort.
13 +- **`/ultra runs`** — browse, inspect, resume, stop, or delete saved runs.
14 +- **`/ultra <instructions>`** — injects the authoring prompt, enables the hidden
15 + `workflow` tool, and starts an agent turn to design or run a workflow.
16 +- **`workflow` tool** — model-callable after `/ultra` enables it. Pass a saved
17 + workflow `name` (+ optional `args`), or an inline `spec` object for a one-off
18 + run. Returns the aggregated JSON; progress streams to a collapsible result
19 + surface.
18 21 ## Workflows
24 27 prompts/tools/schemas, and a closed interpolation grammar that pipes one phase's
25 28 results into the next. The authoritative format reference is
27 -- [`skills/authoring-workflows/references/spec-format.md`](skills/authoring-workflows/references/spec-format.md)
30 +- [`prompts/references/spec-format.md`](prompts/references/spec-format.md)
29 32 — the single source of truth, kept in lockstep with the runtime validator by a
30 33 test. Don't reconstruct the format from memory; read it.
32 35 ### Authoring
34 -The bundled **`authoring-workflows`** skill walks through co-designing and saving a
35 -workflow (phases, the read-only fan-out rule, schemas + join-keys, interpolation,
36 -where to save). It is model-invocable — ask to "create / author / save a workflow"
37 -and it activates.
37 +Run `/ultra <instructions>` to inject the authoring prompt and enable the
38 +`workflow` tool for the next agent turn.
39 +It walks through co-designing and saving a workflow: phases, the read-only
40 +fan-out rule, schemas + join-keys, interpolation, and where to save.
39 42 ### Where workflows live
64 67 The `workflow` tool accepts `background: true` to start a run and return immediately.
65 68 When the detached run finishes, ultra sends its result back into the conversation.
66 -`/ultra-runs` opens a saved-run picker for inspecting, resuming, stopping, or deleting runs.
69 +`/ultra runs` opens a saved-run picker for inspecting, resuming, stopping, or deleting runs.
67 70 Run records live under `~/.pi/agent/ultra-runs/`.
69 72 Workflow runs append incomplete-run checkpoints to the current Pi session as custom entries that never enter LLM context.

extensions/ultra/__tests__/harness.test.ts

Modified
29 29 "Do not use it for an ordinary single-agent task",
31 31 expect(extension.commands.has("ultra")).toBe(true);
32 - expect(extension.commands.has("ultra-runs")).toBe(true);
32 + expect(extension.commands.has("ultra-runs")).toBe(false);
33 + });
35 + it("completes saved workflows and the runs subcommand from /ultra", async () => {
36 + t = await createTestSession({ extensions: [ultraPath()] });
37 + const [extension] = t.session.extensionRunner.extensions;
38 + const items = await extension.commands
39 + .get("ultra")
40 + .getArgumentCompletions("");
42 + expect(items.map((item: { value: string }) => item.value)).toContain(
43 + "runs",
44 + );
45 + expect(items.map((item: { value: string }) => item.value)).toContain(
46 + "review",
47 + );
35 50 it("exposes the runtime workflow schema to tool callers", async () => {

extensions/ultra/__tests__/prompt.test.ts

Added
new file mode 100644
1 +import * as fs from "node:fs";
2 +import { fileURLToPath } from "node:url";
3 +import { describe, expect, it } from "vitest";
4 +import { parseWorkflow, WorkflowSpecSchema } from "../spec.ts";
6 +const PROMPT_PATH = fileURLToPath(
7 + new URL("../prompts/authoring-workflows.md", import.meta.url),
8 +);
9 +const SPEC_FORMAT_PATH = fileURLToPath(
10 + new URL("../prompts/references/spec-format.md", import.meta.url),
11 +);
12 +const README_PATH = fileURLToPath(new URL("../README.md", import.meta.url));
14 +describe("authoring-workflows injected prompt", () => {
15 + it("does not bundle a model-invocable skill", () => {
16 + const packageJson = JSON.parse(
17 + fs.readFileSync(
18 + fileURLToPath(new URL("../package.json", import.meta.url)),
19 + "utf8",
20 + ),
21 + );
22 + expect(packageJson.pi).toEqual({ extensions: ["index.ts"] });
23 + expect(
24 + fs.existsSync(fileURLToPath(new URL("../skills", import.meta.url))),
25 + ).toBe(false);
26 + });
28 + it("keeps invocation-critical semantics in prompt assets", () => {
29 + const prompt = fs.readFileSync(PROMPT_PATH, "utf8");
30 + const reference = fs.readFileSync(SPEC_FORMAT_PATH, "utf8");
32 + expect(prompt).toContain("# Authoring ultra workflows");
33 + expect(prompt).toContain("/ultra <name>");
34 + expect(prompt).not.toContain("name: authoring-workflows");
35 + expect(reference).toContain("Every step returns a JSON object");
36 + });
38 + it("exposes invocation-critical semantics through the tool schema", () => {
39 + const toolGuidance = JSON.stringify(WorkflowSpecSchema);
40 + for (const rule of [
41 + "exact key in top-level schemas",
42 + "{PHASE.results[].FIELD[]}",
43 + "single brace-wrapped selector",
44 + "read, grep, find, ls, bash",
45 + "forbid mutation",
46 + ]) {
47 + expect(toolGuidance).toContain(rule);
48 + }
49 + });
51 + it("keeps the exact interpolation grammar synchronized", () => {
52 + const prompt = fs.readFileSync(PROMPT_PATH, "utf8");
53 + expect(prompt).toContain("{EXPR | where FIELD}");
54 + expect(prompt).not.toContain("{… | where FIELD}");
55 + });
57 + it("keeps phase identifier guidance synchronized", () => {
58 + expect(JSON.stringify(WorkflowSpecSchema)).toContain(
59 + "reserved identifier args",
60 + );
61 + for (const content of [
62 + fs.readFileSync(PROMPT_PATH, "utf8"),
63 + fs.readFileSync(SPEC_FORMAT_PATH, "utf8"),
64 + ]) {
65 + expect(content).toContain("reserved phase ID `args`");
66 + }
67 + });
69 + it("requires deliberate per-step model tiers and thinking levels", () => {
70 + const prompt = fs.readFileSync(PROMPT_PATH, "utf8");
71 + const reference = fs.readFileSync(SPEC_FORMAT_PATH, "utf8");
73 + expect(prompt).toContain("Assign compute deliberately");
74 + expect(prompt).toContain("Explicitly set both fields");
75 + for (const tier of ["`small`", "`medium`", "`big`"]) {
76 + expect(prompt).toContain(tier);
77 + expect(reference).toContain(tier);
78 + }
79 + expect(reference).toContain("relative to that step's difficulty");
80 + expect(reference).toContain("re-evaluate each assignment");
81 + });
83 + it("keeps max thinking guidance synchronized", () => {
84 + expect(JSON.stringify(WorkflowSpecSchema)).toContain('"const":"max"');
85 + for (const content of [
86 + fs.readFileSync(PROMPT_PATH, "utf8"),
87 + fs.readFileSync(SPEC_FORMAT_PATH, "utf8"),
88 + fs.readFileSync(README_PATH, "utf8"),
89 + ]) {
90 + expect(content).toContain("`max`");
91 + }
92 + });
94 + it("matches runtime positional and structured-output semantics", () => {
95 + const prompt = fs.readFileSync(PROMPT_PATH, "utf8");
96 + const reference = fs.readFileSync(SPEC_FORMAT_PATH, "utf8");
98 + expect(reference).toContain(
99 + "last declared parameter absorbs all remaining tokens",
100 + );
101 + expect(reference).not.toContain("extra tokens ignored");
102 + expect(reference).toContain("Every step returns a JSON object");
103 + expect(reference).toContain("`schema` validates");
104 + expect(prompt).toContain(
105 + "how tightly its structured JSON output must be constrained by a schema",
106 + );
107 + });
109 + it("keeps the reference doc and validator in lockstep: every complete JSON example parses", () => {
110 + const md = fs.readFileSync(SPEC_FORMAT_PATH, "utf8");
111 + const blocks = [...md.matchAll(/```json\n([\s\S]*?)```/g)].map((m) => m[1]);
112 + expect(blocks.length).toBeGreaterThan(0);
114 + let completeSpecs = 0;
115 + for (const block of blocks) {
116 + let parsed: unknown;
117 + expect(() => {
118 + parsed = JSON.parse(block);
119 + }).not.toThrow();
121 + const isCompleteSpec =
122 + typeof parsed === "object" &&
123 + parsed !== null &&
124 + !Array.isArray(parsed) &&
125 + "name" in parsed &&
126 + "phases" in parsed;
127 + if (isCompleteSpec) {
128 + completeSpecs += 1;
129 + const spec = parseWorkflow(parsed);
130 + for (const phase of spec.phases) {
131 + expect(phase.step.model).toMatch(/^(small|medium|big)$/);
132 + expect(phase.step.thinkingLevel).toMatch(
133 + /^(off|minimal|low|medium|high|xhigh|max)$/,
134 + );
138 + expect(completeSpecs).toBeGreaterThanOrEqual(1);
139 + });
140 +});

extensions/ultra/__tests__/runner.test.ts

Modified
993 + it("does not let teardown errors mask a finished tool step", async () => {
994 + let release!: () => void;
995 + const harness = makeSessionHarness({
996 + drive: async ({ emit, callStructured }) => {
997 + await new Promise<void>((resolve) => {
998 + release = resolve;
999 + });
1000 + await callStructured({ verdict: "ok" });
1001 + emit({ type: "agent_end", messages: [], willRetry: false });
1002 + },
1003 + });
1004 + const pending = runStep(
1005 + toolStep,
1006 + makeCtx(),
1007 + makeDrivers({ sessionFactory: harness.factory }),
1008 + baseOpts(),
1009 + );
1010 + await new Promise((resolve) => setTimeout(resolve, 0));
1011 + harness.captured.spies?.unsubscribe.mockImplementationOnce(() => {
1012 + throw new Error("unsubscribe exploded");
1013 + });
1014 + harness.captured.spies?.dispose.mockImplementationOnce(() => {
1015 + throw new Error("dispose exploded");
1016 + });
1017 + release();
1019 + await expect(pending).resolves.toEqual({
1020 + ok: true,
1021 + value: { verdict: "ok" },
1022 + });
1023 + });
993 1025 it("records manual aborts as aborted failures", async () => {
994 1026 let release!: () => void;
995 1027 const events: UltraProgressEvent[] = [];

extensions/ultra/__tests__/skill.test.ts

Deleted
deleted file mode 100644
1 -import * as fs from "node:fs";
2 -import { fileURLToPath } from "node:url";
3 -import { loadSkillsFromDir } from "@earendil-works/pi-coding-agent";
4 -import { describe, expect, it } from "vitest";
5 -import { parseWorkflow, WorkflowSpecSchema } from "../spec.ts";
7 -// Root `package.json` registers ultra's skills under `pi.skills` with the
8 -// explicit entry `extensions/ultra/skills` (alongside other skill-bundling
9 -// extensions such as `super`). These tests scope to ultra's own `skills/`
10 -// subtree and load it with the real SDK discovery primitive, so they track
11 -// production behaviour for *this* extension regardless of what others bundle.
12 -const ULTRA_SKILLS_DIR = fileURLToPath(new URL("../skills", import.meta.url));
13 -const SKILL_PATH = fileURLToPath(
14 - new URL("../skills/authoring-workflows/SKILL.md", import.meta.url),
15 -);
16 -const SPEC_FORMAT_PATH = fileURLToPath(
17 - new URL(
18 - "../skills/authoring-workflows/references/spec-format.md",
19 - import.meta.url,
20 - ),
21 -);
22 -const README_PATH = fileURLToPath(new URL("../README.md", import.meta.url));
24 -describe("authoring-workflows companion skill", () => {
25 - it("bundles exactly one skill subdir — authoring-workflows", () => {
26 - // Ultra ships a single skill; this guards against an accidental empty or
27 - // stray skill dir sneaking into the discovered surface as ultra grows.
28 - const dirs = fs
29 - .readdirSync(ULTRA_SKILLS_DIR, { withFileTypes: true })
30 - .filter((e) => e.isDirectory())
31 - .map((e) => e.name)
32 - .sort();
33 - expect(dirs).toEqual(["authoring-workflows"]);
34 - });
36 - it("discovers exactly the authoring-workflows skill from ultra's skills dir — no diagnostics", () => {
37 - const { skills, diagnostics } = loadSkillsFromDir({
38 - dir: ULTRA_SKILLS_DIR,
39 - source: "extensions/ultra/skills",
40 - });
42 - expect(skills.map((s) => s.name)).toEqual(["authoring-workflows"]);
43 - // Valid frontmatter + a clean subtree ⇒ the loader emits nothing.
44 - expect(diagnostics).toEqual([]);
46 - const skill = skills[0];
47 - expect(skill.description.trim().length).toBeGreaterThan(0);
48 - expect(skill.description.length).toBeLessThanOrEqual(1024);
49 - // The description is the model's trigger surface — it must mention what it
50 - // routes on so "author / create / save a workflow" intent lands here.
51 - expect(skill.description.toLowerCase()).toContain("workflow");
52 - // Model-invocable (no `disable-model-invocation`), resolving to the real file.
53 - expect(skill.disableModelInvocation).toBe(false);
54 - expect(skill.filePath).toBe(SKILL_PATH);
55 - expect(fs.existsSync(skill.filePath)).toBe(true);
56 - });
58 - it("exposes invocation-critical semantics through the tool schema", () => {
59 - const toolGuidance = JSON.stringify(WorkflowSpecSchema);
60 - for (const rule of [
61 - "exact key in top-level schemas",
62 - "{PHASE.results[].FIELD[]}",
63 - "single brace-wrapped selector",
64 - "read, grep, find, ls, bash",
65 - "forbid mutation",
66 - ]) {
67 - expect(toolGuidance).toContain(rule);
68 - }
69 - });
71 - it("keeps the exact interpolation grammar synchronized", () => {
72 - const skill = fs.readFileSync(SKILL_PATH, "utf8");
73 - expect(skill).toContain("{EXPR | where FIELD}");
74 - expect(skill).not.toContain("{… | where FIELD}");
75 - });
77 - it("keeps phase identifier guidance synchronized", () => {
78 - expect(JSON.stringify(WorkflowSpecSchema)).toContain(
79 - "reserved identifier args",
80 - );
81 - for (const content of [
82 - fs.readFileSync(SKILL_PATH, "utf8"),
83 - fs.readFileSync(SPEC_FORMAT_PATH, "utf8"),
84 - ]) {
85 - expect(content).toContain("reserved phase ID `args`");
86 - }
87 - });
89 - it("requires deliberate per-step model tiers and thinking levels", () => {
90 - const skill = fs.readFileSync(SKILL_PATH, "utf8");
91 - const reference = fs.readFileSync(SPEC_FORMAT_PATH, "utf8");
93 - expect(skill).toContain("Assign compute deliberately");
94 - expect(skill).toContain("Explicitly set both fields");
95 - for (const tier of ["`small`", "`medium`", "`big`"]) {
96 - expect(skill).toContain(tier);
97 - expect(reference).toContain(tier);
98 - }
99 - expect(reference).toContain("relative to that step's difficulty");
100 - expect(reference).toContain("re-evaluate each assignment");
101 - });
103 - it("keeps max thinking guidance synchronized", () => {
104 - expect(JSON.stringify(WorkflowSpecSchema)).toContain('"const":"max"');
105 - for (const content of [
106 - fs.readFileSync(SKILL_PATH, "utf8"),
107 - fs.readFileSync(SPEC_FORMAT_PATH, "utf8"),
108 - fs.readFileSync(README_PATH, "utf8"),
109 - ]) {
110 - expect(content).toContain("`max`");
111 - }
112 - });
114 - it("matches runtime positional and structured-output semantics", () => {
115 - const skill = fs.readFileSync(SKILL_PATH, "utf8");
116 - const reference = fs.readFileSync(SPEC_FORMAT_PATH, "utf8");
118 - expect(reference).toContain(
119 - "last declared parameter absorbs all remaining tokens",
120 - );
121 - expect(reference).not.toContain("extra tokens ignored");
122 - expect(reference).toContain("Every step returns a JSON object");
123 - expect(reference).toContain("`schema` validates");
124 - expect(skill).toContain(
125 - "how tightly its structured JSON output must be constrained by a schema",
126 - );
127 - });
129 - it("keeps the reference doc and the validator in lockstep: every complete JSON example parses", () => {
130 - // Extract every ```json fenced block from the canonical reference and run
131 - // each *complete* spec (one with both `name` and `phases`) through the
132 - // SAME validator the runtime uses. If an author copies an example verbatim
133 - // it must validate — and if someone edits the doc into an invalid shape,
134 - // this fails loudly. Fragments (lone phases/schemas) are checked only for
135 - // being valid JSON.
136 - const md = fs.readFileSync(SPEC_FORMAT_PATH, "utf8");
137 - const blocks = [...md.matchAll(/```json\n([\s\S]*?)```/g)].map((m) => m[1]);
138 - expect(blocks.length).toBeGreaterThan(0);
140 - let completeSpecs = 0;
141 - for (const block of blocks) {
142 - let parsed: unknown;
143 - expect(() => {
144 - parsed = JSON.parse(block);
145 - }).not.toThrow();
147 - const isCompleteSpec =
148 - typeof parsed === "object" &&
149 - parsed !== null &&
150 - !Array.isArray(parsed) &&
151 - "name" in parsed &&
152 - "phases" in parsed;
153 - if (isCompleteSpec) {
154 - completeSpecs += 1;
155 - const spec = parseWorkflow(parsed);
156 - for (const phase of spec.phases) {
157 - expect(phase.step.model).toMatch(/^(small|medium|big)$/);
158 - expect(phase.step.thinkingLevel).toMatch(
159 - /^(off|minimal|low|medium|high|xhigh|max)$/,
160 - );
161 - }
162 - }
163 - }
164 - // The doc must carry at least one full worked example, not only fragments.
165 - expect(completeSpecs).toBeGreaterThanOrEqual(1);
166 - });
167 -});

extensions/ultra/index.ts

Modified
10 10 // live gate can prove; the harness test asserts registration only.
12 12 import { randomUUID } from "node:crypto";
13 +import { readFileSync } from "node:fs";
13 14 import { complete } from "@earendil-works/pi-ai/compat";
14 15 import {
15 16 createAgentSession,
16 17 DefaultResourceLoader,
17 18 type ExtensionAPI,
19 + type ExtensionCommandContext,
18 20 type ExtensionContext,
19 21 getAgentDir,
20 22 getMarkdownTheme,
103 105 return cache;
108 + let authoringPrompt: string | undefined;
109 + const loadAuthoringPrompt = (): string => {
110 + if (!authoringPrompt) {
111 + const guide = readFileSync(
112 + new URL("./prompts/authoring-workflows.md", import.meta.url),
113 + "utf8",
114 + ).trim();
115 + const reference = readFileSync(
116 + new URL("./prompts/references/spec-format.md", import.meta.url),
117 + "utf8",
118 + ).trim();
119 + authoringPrompt = `${guide}\n\n# Ultra workflow spec reference\n\n${reference}`;
121 + return authoringPrompt;
122 + };
124 + const activateWorkflowTool = () => {
125 + const active = pi.getActiveTools();
126 + if (!active.includes("workflow")) {
127 + pi.setActiveTools([...active, "workflow"]);
129 + };
131 + const deactivateWorkflowTool = () => {
132 + const active = pi.getActiveTools();
133 + if (active.includes("workflow")) {
134 + pi.setActiveTools(active.filter((name) => name !== "workflow"));
136 + };
106 138 const createJournal = (
107 139 ctx: ExtensionContext,
108 140 spec: WorkflowSpec,
331 - pi.registerCommand("ultra-runs", {
332 - description: "Browse, inspect, resume, stop, or delete saved ultra runs.",
333 - handler: async (_args, ctx) => {
334 - const runs = listWorkflowRuns();
335 - if (runs.length === 0) {
336 - ctx.ui.notify("No saved ultra runs.", "info");
337 - return;
338 - }
339 - const labels = runs.map(
340 - (run) => `${run.status} · ${run.workflow} · ${run.id}`,
341 - );
342 - const selected = await ctx.ui.select("Ultra runs", labels);
343 - const run = runs[labels.indexOf(selected ?? "")];
344 - if (!run) return;
345 - const actions = ["Inspect"];
346 - const active = activeRuns.has(run.id);
347 - if (active) actions.push("Stop");
348 - else actions.push("Delete");
349 - if (!active && run.spec && run.cwd === ctx.cwd) actions.push("Resume");
350 - const action = await ctx.ui.select(
351 - `${run.workflow} · ${run.id}`,
352 - actions,
353 - );
354 - if (action === "Stop") {
355 - activeRuns.get(run.id)?.abort();
356 - ctx.ui.notify(`Stopping ultra run ${run.id}.`, "warning");
357 - return;
358 - }
359 - if (action === "Resume" && run.spec) {
360 - startBackground(ctx, run.spec, run.args, settings(ctx.cwd), run.id);
361 - ctx.ui.notify(`Resumed ultra run ${run.id}.`, "info");
362 - return;
363 - }
364 - if (action === "Delete") {
365 - activeRuns.get(run.id)?.abort();
366 - deleteWorkflowRun(undefined, run.id);
367 - ctx.ui.notify(`Deleted ultra run ${run.id}.`, "info");
368 - return;
369 - }
370 - const details = run.result as WorkflowResult | undefined;
371 - pi.sendMessage({
372 - customType: "ultra-result",
373 - content: `ultra saved run ${run.id}\n\n${JSON.stringify(run, null, 2)}`,
374 - display: true,
375 - details: details ?? {
376 - workflow: run.workflow,
377 - phases: [],
378 - phaseResults: {},
379 - phaseFailures: {},
380 - result: { status: run.status, error: run.error },
381 - steered: false,
382 - tokenUsage: {
383 - input: 0,
384 - output: 0,
385 - total: 0,
386 - cacheRead: 0,
387 - cacheWrite: 0,
388 - cost: 0,
389 - },
390 - },
391 - });
363 + pi.on("session_start", () => deactivateWorkflowTool());
365 + type SavedRun = ReturnType<typeof listWorkflowRuns>[number];
367 + const runLabel = (run: SavedRun): string =>
368 + `${run.status} · ${run.workflow} · ${run.id}`;
370 + const runActions = (run: SavedRun, cwd: string): string[] => {
371 + const active = activeRuns.has(run.id);
372 + return [
373 + "Inspect",
374 + active ? "Stop" : "Delete",
375 + ...(!active && run.spec && run.cwd === cwd ? ["Resume"] : []),
376 + ];
377 + };
379 + const runFallbackDetails = (run: SavedRun): WorkflowResult => ({
380 + workflow: run.workflow,
381 + phases: [],
382 + phaseResults: {},
383 + phaseFailures: {},
384 + result: { status: run.status, error: run.error },
385 + steered: false,
386 + tokenUsage: {
387 + input: 0,
388 + output: 0,
389 + total: 0,
390 + cacheRead: 0,
391 + cacheWrite: 0,
392 + cost: 0,
395 - // ── `/ultra <name> [args]` command (idle, Tier-3 overlay surface) ──
396 + const inspectRun = (run: SavedRun) => {
397 + pi.sendMessage({
398 + customType: "ultra-result",
399 + content: `ultra saved run ${run.id}\n\n${JSON.stringify(run, null, 2)}`,
400 + display: true,
401 + details:
402 + (run.result as WorkflowResult | undefined) ?? runFallbackDetails(run),
403 + });
404 + };
406 + const runAction = (
407 + run: SavedRun,
408 + action: string | undefined,
409 + ctx: ExtensionCommandContext,
410 + ) => {
411 + if (action === "Stop") {
412 + activeRuns.get(run.id)?.abort();
413 + ctx.ui.notify(`Stopping ultra run ${run.id}.`, "warning");
414 + return;
416 + if (action === "Resume" && run.spec) {
417 + startBackground(ctx, run.spec, run.args, settings(ctx.cwd), run.id);
418 + ctx.ui.notify(`Resumed ultra run ${run.id}.`, "info");
419 + return;
421 + if (action === "Delete") {
422 + activeRuns.get(run.id)?.abort();
423 + deleteWorkflowRun(undefined, run.id);
424 + ctx.ui.notify(`Deleted ultra run ${run.id}.`, "info");
425 + return;
427 + if (action === "Inspect") inspectRun(run);
428 + };
430 + const browseRuns = async (ctx: ExtensionCommandContext) => {
431 + const runs = listWorkflowRuns();
432 + if (runs.length === 0) {
433 + ctx.ui.notify("No saved ultra runs.", "info");
434 + return;
436 + const labels = runs.map(runLabel);
437 + const selected = await ctx.ui.select("Ultra runs", labels);
438 + const run = runs[labels.indexOf(selected ?? "")];
439 + if (!run) return;
440 + const action = await ctx.ui.select(
441 + `${run.workflow} · ${run.id}`,
442 + runActions(run, ctx.cwd),
443 + );
444 + runAction(run, action, ctx);
445 + };
447 + const injectAuthoringPrompt = (request: string) => {
448 + activateWorkflowTool();
449 + pi.sendMessage(
451 + customType: "ultra-authoring",
452 + content: `${loadAuthoringPrompt()}\n\n# User request\n\n${request}\n\nThe workflow tool is now available; use it only when ultra orchestration is justified.`,
453 + display: false,
454 + details: { request },
455 + },
456 + { triggerTurn: true, deliverAs: "followUp" },
457 + );
458 + };
460 + // ── `/ultra [runs | <name> [args] | <instructions>]` command ──
396 461 pi.registerCommand("ultra", {
397 - description: "Run a saved ultra workflow with a live multi-agent overlay.",
398 - getArgumentCompletions: (prefix) =>
399 - completeWorkflowNames(discover(process.cwd()), prefix),
462 + description:
463 + "Run ultra workflows, browse saved runs, or author a workflow from instructions.",
464 + getArgumentCompletions: (prefix) => {
465 + const p = prefix.toLowerCase();
466 + const runs = "runs".startsWith(p)
467 + ? [{ value: "runs", label: "runs", description: "saved runs" }]
468 + : [];
469 + const workflows =
470 + completeWorkflowNames(discover(process.cwd()), prefix) ?? [];
471 + const items = [...runs, ...workflows];
472 + return items.length > 0 ? items : null;
473 + },
400 474 handler: async (argString, ctx) => {
401 475 const cfg = settings(ctx.cwd);
402 476 if (!cfg.enabled) {
412 486 if (!ctx.hasUI) {
413 487 return;
489 + activateWorkflowTool();
491 + const trimmed = argString.trim();
492 + const discovered = discover(ctx.cwd);
493 + const parsed = parseCommandLine(trimmed);
494 + if (parsed.name === "runs") {
495 + await browseRuns(ctx);
496 + return;
498 + if (!parsed.name) {
499 + ctx.ui.notify(
500 + "Usage: /ultra runs | /ultra <workflow> [args] | /ultra <instructions>",
501 + "warning",
502 + );
503 + return;
505 + if (!discovered.some((workflow) => workflow.name === parsed.name)) {
506 + injectAuthoringPrompt(trimmed);
507 + ctx.ui.notify("ultra authoring prompt sent.", "info");
508 + return;
416 511 let resolved: { spec: WorkflowSpec; args?: Record<string, unknown> };
418 - const { name, args, rest } = parseCommandLine(argString);
419 513 resolved = resolveWorkflowInput(
420 - { name, args },
421 - discover(ctx.cwd),
422 - rest,
514 + { name: parsed.name, args: parsed.args },
515 + discovered,
516 + parsed.rest,
424 518 } catch (err) {
425 519 ctx.ui.notify(

extensions/ultra/package.json

Modified
27 27 "pi": {
28 28 "extensions": [
29 29 "index.ts"
30 - ],
31 - "skills": [
32 - "skills"

extensions/ultra/prompts/authoring-workflows.md

Added
new file mode 100644
1 +# Authoring ultra workflows
3 +These instructions help you co-design a **persisted** ultra workflow with the
4 +user and save it to disk so they can re-run it as `/ultra <name>`. The canonical
5 +spec format is injected below — use it before writing any spec; do not restate it
6 +from memory.
8 +## First: persist vs. one-off (decide silently)
10 +Creation language — "create / author / build / save / write me a workflow that
11 +…" — means the user wants a **persisted** workflow. That is the default this
12 +prompt serves: co-design the spec and write the JSON file.
14 +Divert to an **ephemeral one-off** — call the `workflow` tool with an inline
15 +`spec` and skip the authoring/saving flow entirely — only on an explicit
16 +override cue:
18 +- "just run it once" / "one-off" / "don't save it" / "throwaway"
19 +- "try this without saving" / "ad hoc"
21 +Decide silently. **Do not ask "should I save this or just run it?"** and do not
22 +announce the routing — the user's wording already carries the intent, and the
23 +choice is cheap to reverse: a one-off can be saved afterward, and a saved file
24 +can be deleted. When in genuine doubt with creation language, persist (the
25 +reversible, lower-regret default).
27 +## Single-agent gate
29 +Do not create or invoke ultra for an ordinary task that one agent can perform directly.
30 +A workflow with one agent is justified only when it specifically needs context isolation, background execution, an alternate model, resumability, strict structured output, or future reuse as orchestration.
31 +Otherwise perform the task directly and skip ultra's orchestration overhead.
33 +## Authoring flow (persisted)
35 +1. **Understand the goal.** What does each stage do, and what flows between
36 + stages? Most workflows are _fan-out then synthesize_: parallel agents each
37 + handle one item (a dimension, a file, a finding), then a `single` pass
38 + judges or merges. Sketch the phases before writing JSON.
40 +2. **Co-design the phases.** For each phase decide:
41 + - Give every phase a unique interpolation identifier; the reserved phase ID `args` is forbidden.
42 + - `single` (one synthesis/judge pass) vs. `fanout` (one agent per item).
43 + - `fanout` needs an `over` — a literal array, or an interpolation token over
44 + a prior phase's results (e.g. `{review.results[].findings[]}`).
45 + - Optional `when` uses one existing selector; empty/false skips the phase and produces empty results.
46 + - A recovery fan-out may use `{PHASE.failures}` for both `when` and `over`; recovery remains one explicit later phase, never a loop.
47 + - The step `prompt`, its `tools`, and how tightly its structured JSON output must be constrained by a schema.
49 +3. **Apply the read-only fan-out rule.** A `fanout` step with tools must stay
50 + within `read`, `grep`, `find`, `ls`, `bash` **and** the prompt must forbid
51 + mutation — parallel writers race. Put any writing work in a `single` phase.
53 +4. **Design schemas and join-keys.** Give a step a `schema` (named in `schemas`,
54 + or inline) when a later phase consumes its output. When phase B fans out over
55 + phase A's findings, add a shared field (a join-key) to both schemas and tell
56 + B to echo it, so each result ties back to its source. See the `review`
57 + worked example in the reference.
59 +5. **Wire interpolation.** Use only the closed grammar (`{args.NAME}`, `{item}`,
60 + `{PHASE.results}`, `{PHASE.failures}`, `{PHASE.results[].FIELD[]}`, `{EXPR | where FIELD}`). Keep
61 + literal `{`/`}` out of prompts except these tokens. Set `return` to the
62 + selector for the workflow's final value.
64 +6. **Assign compute deliberately.** For every step:
65 + - `big` — planning, specification, architecture, critique, synthesis.
66 + - `medium` — coding, testing, editing, routine implementation.
67 + - `small` — scouting, extraction, classification, easy text work.
68 + - Set `thinkingLevel` from `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` based on that step's relative ambiguity, constraints, and cost of mistakes. `max` is the highest opt-in budget and requires model support.
69 + - Explicitly set both fields. If every phase uses the same pair, challenge the assignment before saving.
71 +7. **Self-check the spec (there is no validator tool).** You can't call
72 + `parseWorkflow` directly — verify by inspection against the reference: every
73 + required field is present, every `fanout` has an `over`, every `when` is one selector, every string
74 + `schema` names a key in `schemas`, and interpolation uses only the closed
75 + grammar. The real validator is the load itself: saving and test-running
76 + (steps 8–9) parses the file through the runtime's `parseWorkflow`, which
77 + surfaces a TypeBox error naming the offending path if anything is malformed —
78 + fix and re-run until it loads clean. One caveat: a JSON _syntax_ error (a
79 + trailing comma, a missing quote) makes the file invisible to discovery
80 + entirely, so `/ultra <name>` reports `unknown workflow` rather than a schema
81 + error — if a saved workflow seems to vanish, confirm it is valid JSON first.
83 +8. **Save it.** Write the spec as `<name>.json` (filename matching the spec's
84 + `name`):
85 + - project-scoped (lives in the repo): `<cwd>/.pi/workflows/<name>.json`
86 + - personal / global: `~/.pi/agent/workflows/<name>.json`
88 + Ask which scope only if it isn't clear from context (a repo-specific review
89 + workflow → project; a personal utility → global).
91 +9. **Offer a test run.** After saving, offer to run it: `/ultra <name>` (with
92 + any `args` the spec's `hint` declares). Tighten prompts/schemas from what the
93 + first run surfaces.
95 +## Ephemeral one-off
97 +On an explicit override cue, skip the flow above: construct the spec inline and
98 +call the `workflow` tool with it as `spec`. Same format and rules
99 +(`spec-format.md`, read-only fan-out), but nothing is written to disk. If the
100 +user later likes it, save it via the persisted flow.

extensions/ultra/prompts/references/spec-format.md

Added
new file mode 100644
1 +# ultra workflow spec — canonical reference
3 +A workflow is a single JSON object. `parseWorkflow` (the same validator the
4 +runtime uses) checks it structurally and rejects anything malformed. This file
5 +is the authoritative format reference; the extension `README.md` links here
6 +rather than restating it.
8 +## Top-level fields
10 +| Field | Required | Type | Meaning |
11 +| ------------- | -------- | --------------------------- | -------------------------------------------------------------- |
12 +| `name` | yes | string (non-empty) | Workflow id. The file is invoked as `/ultra <name>`. |
13 +| `description` | no | string | One line shown in the picker. |
14 +| `args` | no | object (`{ hint?, ... }`) | Declares run inputs; `hint` is the usage shown after the name. |
15 +| `schemas` | no | record<string, JSON Schema> | Named, reusable output schemas referenced by steps. |
16 +| `phases` | yes | array (≥1) of phases | The ordered stages. Each is `single` or `fanout`. |
17 +| `return` | no | string (one selector token) | Selects the workflow's final value from phase results. |
19 +`args` may also declare `params`: an ordered list of input names. A bare
20 +`/ultra <name> tokA tokB` line maps tokens onto them positionally; the last declared parameter absorbs all remaining tokens so it can carry free text. Values are exposed as `{args.NAME}`. Without `params`, pass inputs as a trailing JSON object — `/ultra <name> {"k": "v"}`. A missing `{args.NAME}` renders to the empty string.
22 +## Phases
24 +A phase has an `id` (referenced by interpolation and `return`), a `kind`, a
25 +`step`, an optional `concurrency` cap, and an optional `when` selector.
26 +Phase IDs must be unique identifiers matching `[A-Za-z_][A-Za-z0-9_]*`; the reserved phase ID `args` is forbidden because it belongs to the workflow-input namespace.
28 +- **`single`** — runs the step exactly once, for one synthesis / judge /
29 + aggregation pass over prior results. (`over` is accepted by the schema but
30 + **ignored** in v1; for per-item parallelism use `fanout`.)
31 +- **`fanout`** — runs the step once per element of `over`, concurrently (capped
32 + by `concurrency` and the engine's global pool). `over` is **required**.
34 +`when` uses the existing single-selector grammar.
35 +If it resolves to `false`, `null`, `undefined`, an empty string, or an empty array, the phase is skipped and records `{ ran: 0, ok: 0, dropped: 0 }` with empty results.
36 +Any other value runs the phase.
37 +A skipped phase may still be referenced later through empty `{PHASE.results}` and `{PHASE.failures}` arrays.
38 +There are no loops or arbitrary expressions.
40 +`over` is either a literal array or a single interpolation token string (e.g.
41 +`"{review.results[].findings[]}"`).
43 +### The read-only fan-out rule (v1)
45 +A `fanout` step that grants tools must stay within the read-only allowlist —
46 +`read`, `grep`, `find`, `ls`, `bash` — and the prompt must instruct the agent
47 +not to mutate anything. Parallel agents that write race each other; v1 keeps
48 +fan-out side-effect-free. A `single` synthesis phase can be given broader tools
49 +if a workflow genuinely needs to write.
51 +## Steps
53 +| Field | Required | Type | Meaning |
54 +| --------------- | -------- | --------------------- | ------------------------------------------------------------------------------------------------- |
55 +| `prompt` | yes | string | The agent instruction. Interpolates `{...}` tokens (see below). |
56 +| `tools` | no | string[] | Tool allowlist. Omit for a tool-less completion (pure reasoning). |
57 +| `model` | no | string | `provider/id` override, or configured tier `small`/`medium`/`big`; defaults to the session model. |
58 +| `thinkingLevel` | no | off…max | Reasoning budget for this step. |
59 +| `schema` | no | string \| JSON Schema | A `schemas` name, or an inline schema that validates structured output. |
61 +Every step returns a JSON object through completion parsing or the terminating `structured_output` tool.
62 +Without `schema`, any JSON object is accepted.
63 +A `schema` validates that object and is required when downstream phases depend on a stable shape.
64 +A string `schema` is a **name reference** and must resolve in the spec's `schemas` map, or validation fails.
66 +Configured model tiers live in Pi settings under `ultra.modelTiers`.
67 +If a step sets `model` to `small`, `medium`, or `big`, ultra resolves it through that map; an unset tier falls back to the session model.
68 +Tier values may include a thinking suffix like `openai/gpt-5-mini:low`, used only when the step omits `thinkingLevel`.
70 +### Model tier and thinking rubric
72 +Set both `model` and `thinkingLevel` on every authored step.
73 +Choose them from the work that step performs, not by copying another phase:
75 +| Work | Tier |
76 +| ---------------------------------------------------------- | -------- |
77 +| Planning, specification, architecture, critique, synthesis | `big` |
78 +| Coding, testing, editing, routine implementation | `medium` |
79 +| Scouting, extraction, classification, easy text work | `small` |
81 +Choose `big` models that gather context and knowledge.
82 +Choose `medium` models when context and knowledge has already been gathered in previous steps.
84 +Choose thinking independently from the tier and relative to that step's difficulty:
86 +- `off` / `minimal` — deterministic extraction, transcription, or formatting with negligible ambiguity.
87 +- `low` / `medium` — routine decisions with bounded context and cheap mistakes and when context has been prepared beforehand.
88 +- `high` / `xhigh` / `max` — ambiguous, multi-constraint reasoning where a wrong decision is costly downstream. `max` is the highest opt-in budget and requires model support.
90 +If every phase has the same model/thinking pair, re-evaluate each assignment before saving.
91 +Uniform settings are valid only when the phases genuinely perform equally difficult work of the same kind.
93 +Examples:
95 +- Repository inventory: `medium` + `low`.
96 +- Implement a well-specified edit: `big` + `medium`.
97 +- Design architecture from conflicting requirements: `big` + `high`.
98 +- Adversarially critique a risky plan: `big` + `xhigh`.
100 +## Interpolation grammar
102 +A closed mini-syntax — not an expression evaluator, no `eval`. Tokens
103 +(braces are literal here, shown without JSON quoting):
105 +```text
106 +{args.NAME} workflow input value
107 +{item} current fanout item (string verbatim; else compact JSON)
108 +{PHASE.results} a prior phase's results array (nulls retained positionally)
109 +{PHASE.failures} a prior phase's typed failure array
110 +{PHASE.results[].FIELD[]} flatten: concat each result's FIELD array (nulls/missing skipped)
111 +{EXPR | where FIELD} keep elements whose boolean FIELD is truthy
112 +```
114 +Anything outside this grammar raises a validation error at run time. In a
115 +step `prompt`, the only literal braces allowed are these tokens — do not put
116 +raw `{`/`}` (e.g. an inline JSON example) in a prompt; describe the shape in
117 +words and use a `schema` instead.
119 +### Explicit linear recovery
121 +A dropped step appears in `{PHASE.failures}` with `agentId`, `index`, optional original `item`, `code`, `message`, `retryable`, `attempts`, optional `model`, optional `thinkingLevel`, and an optional 2,000-character `transcriptTail`.
122 +Failure codes are `auth`, `transport`, `invalid-json`, `schema`, `missing-output`, `aborted`, or `session`.
124 +Use the non-empty failure array to condition and fan out one later recovery phase:
126 +```json
128 + "id": "recover",
129 + "kind": "fanout",
130 + "when": "{work.failures}",
131 + "over": "{work.failures}",
132 + "step": {
133 + "prompt": "Recover this failed task and return the required result. Failure: {item}",
134 + "model": "big",
135 + "thinkingLevel": "high"
138 +```
140 +Ultra has no timeout, automatic rerun, loop, or back-edge.
141 +`ultra.maxRetries` retries tool-less transport failures and invalid completion output inside one step.
142 +Workflow authors explicitly place any recovery phase after the failed phase.
144 +### Schema join-keys
146 +When one phase fans out over another's findings, give the producer schema and
147 +the consumer schema a shared field (a "join key") and instruct the consumer to
148 +echo it. In the worked example below, `Findings.file` is echoed into
149 +`Verdict.file`, so each verdict ties back to the finding it judges.
151 +## Worked example — minimal single fan-out
153 +Every `fanout` agent reads one path and returns a structured summary. Tools are
154 +read-only; the prompt forbids mutation.
156 +```json
158 + "name": "summarize-paths",
159 + "description": "Summarize each input path in parallel.",
160 + "args": { "hint": "<paths>" },
161 + "phases": [
163 + "id": "summarize",
164 + "kind": "fanout",
165 + "over": "{args.paths}",
166 + "step": {
167 + "prompt": "Read the file at {item} and return JSON with two string fields: path (the file path you were given) and summary (one sentence). Do not modify anything.",
168 + "tools": ["read"],
169 + "model": "small",
170 + "thinkingLevel": "low",
171 + "schema": {
172 + "type": "object",
173 + "properties": {
174 + "path": { "type": "string" },
175 + "summary": { "type": "string" }
176 + },
177 + "required": ["path", "summary"]
181 + ],
182 + "return": "{summarize.results}"
184 +```
186 +## Worked example — two phases with a join key
188 +Fan out a review across dimensions, then fan out verification over the flattened
189 +findings. `Findings.file` → `Verdict.file` is the join key; `return` filters to
190 +the verdicts the verifier judged `real`. The single `params` entry lets a bare
191 +`/ultra review main` map `main` to `{args.base}` (a missing arg renders empty, so
192 +the diff falls back to the working tree).
194 +```json
196 + "name": "review",
197 + "description": "Review the diff across dimensions, then adversarially verify each finding.",
198 + "args": { "hint": "[base-ref]", "params": ["base"] },
199 + "schemas": {
200 + "Findings": {
201 + "type": "object",
202 + "properties": {
203 + "findings": {
204 + "type": "array",
205 + "items": {
206 + "type": "object",
207 + "properties": {
208 + "title": { "type": "string" },
209 + "file": { "type": "string" },
210 + "detail": { "type": "string" }
211 + },
212 + "required": ["title", "file"]
215 + },
216 + "required": ["findings"]
217 + },
218 + "Verdict": {
219 + "type": "object",
220 + "properties": {
221 + "title": { "type": "string" },
222 + "real": { "type": "boolean" },
223 + "why": { "type": "string" },
224 + "file": {
225 + "type": "string",
226 + "description": "echo of the reviewed finding's file, for correlation"
228 + },
229 + "required": ["title", "real", "file"]
231 + },
232 + "phases": [
234 + "id": "review",
235 + "kind": "fanout",
236 + "over": ["correctness", "security", "performance"],
237 + "step": {
238 + "prompt": "Review the diff for {item} issues. Inspect it with `git diff {args.base}` (no base ref → the working tree; a base ref → everything since that ref), plus read/grep as needed; do not modify any files. Return JSON matching the Findings schema, and set each finding's file to the path it concerns.",
239 + "tools": ["read", "bash", "grep", "find", "ls"],
240 + "model": "small",
241 + "thinkingLevel": "medium",
242 + "schema": "Findings"
244 + },
246 + "id": "verify",
247 + "kind": "fanout",
248 + "over": "{review.results[].findings[]}",
249 + "step": {
250 + "prompt": "Adversarially try to refute this finding. Default to real=false if uncertain. Echo the finding's file verbatim in your verdict's file field so the verdict ties back to its finding. Finding: {item}",
251 + "model": "big",
252 + "thinkingLevel": "high",
253 + "schema": "Verdict"
256 + ],
257 + "return": "{verify.results | where real}"
259 +```
261 +## Where workflows live
263 +Discovery merges three locations, lowest-to-highest precedence — a later source
264 +overrides a bundled name:
266 +1. **bundled** — `<extension>/workflows/*.json` (ships with ultra)
267 +2. **global** — `~/.pi/agent/workflows/*.json`
268 +3. **project** — `<cwd>/.pi/workflows/*.json`
270 +Save an authored workflow as `<name>.json` (filename should match the spec's
271 +`name`) in the project dir for repo-scoped workflows, or the global dir for
272 +personal ones.

extensions/ultra/runner.ts

Modified
724 724 validator: CompiledValidator | undefined,
725 725 tier: string | undefined,
726 726 ): Promise<RunStepResult> {
727 - const { agentId, phase, onProgress } = opts;
728 - const startedAt = Date.now();
729 727 let model: unknown;
731 729 model = drivers.resolveModel(step.model);
736 734 thinkingLevel: step.thinkingLevel,
739 738 const meta = {
741 740 model: modelLabel(model, step.model),
742 741 thinkingLevel: step.thinkingLevel,
743 - startedAt,
742 + startedAt: Date.now(),
744 + const state: ToolStepState = { transcript: "", manuallyAborted: false };
745 + const structuredOutputTool = makeStructuredOutputTool(
746 + schemaObj,
747 + validator,
748 + state,
749 + );
746 - // The terminating StructuredOutput tool: validates the model's call against
747 - // the step schema, captures the validated payload as the step result, and
748 - // ends the sub-agent loop via `terminate: true`. An invalid call throws,
749 - // surfacing a retryable tool-error to the model (the in-session retry).
750 - let captured: { value: unknown } | undefined;
751 - const structuredOutputTool: StructuredOutputTool = {
751 + let session: SessionLike | undefined;
752 + let unsubscribe: () => void = () => {};
753 + try {
754 + session = await drivers.sessionFactory({
755 + model,
756 + thinkingLevel: step.thinkingLevel,
757 + tools: [
758 + ...sanitizeSubagentTools(step.tools),
759 + STRUCTURED_OUTPUT_TOOL_NAME,
760 + ],
761 + customTools: [structuredOutputTool],
762 + sessionManager: ctxLike.newSessionManager(),
763 + });
764 + unsubscribe = observeToolSession(session, opts, meta, state);
765 + return await promptToolSession(
766 + session,
767 + step.prompt,
768 + opts.signal,
769 + meta,
770 + state,
771 + );
772 + } catch (error) {
773 + const message = error instanceof Error ? error.message : String(error);
774 + return failed(
775 + "session",
776 + message,
777 + true,
778 + session ? 1 : 0,
779 + meta,
780 + state.transcript,
781 + );
782 + } finally {
783 + safeCall(unsubscribe);
784 + safeCall(() => session?.dispose());
788 +interface ToolStepState {
789 + captured?: { value: unknown };
790 + usage?: TokenUsage;
791 + transcript: string;
792 + manuallyAborted: boolean;
795 +type ToolStepMeta = Pick<
796 + AgentProgressEvent,
797 + "tier" | "model" | "thinkingLevel" | "startedAt"
800 +function makeStructuredOutputTool(
801 + schemaObj: object | undefined,
802 + validator: CompiledValidator | undefined,
803 + state: ToolStepState,
804 +): StructuredOutputTool {
805 + return {
752 806 name: STRUCTURED_OUTPUT_TOOL_NAME,
753 807 label: "Structured Output",
754 808 description: "Return the final structured result for this step and finish.",
759 813 `${STRUCTURED_OUTPUT_TOOL_NAME}: schema validation failed: ${formatValidatorErrors(validator, params)}`,
762 - captured = { value: params };
816 + state.captured = { value: params };
763 817 return {
764 818 content: [{ type: "text", text: "Structured output recorded." }],
765 819 details: params,
771 - let session: SessionLike | undefined;
772 - let unsubscribe: () => void = () => {};
773 - let usage: TokenUsage | undefined;
774 - let transcript = "";
775 - let manuallyAborted = false;
777 - try {
778 - const sessionManager = ctxLike.newSessionManager();
779 - session = await drivers.sessionFactory({
780 - model,
781 - thinkingLevel: step.thinkingLevel,
782 - // The structured-output tool name is APPENDED to the step allowlist
783 - // (correction #5) — it must be present or the registry filters it out.
784 - // ultra's own `workflow` tool is stripped first (recursion defense).
785 - tools: [
786 - ...sanitizeSubagentTools(step.tools),
787 - STRUCTURED_OUTPUT_TOOL_NAME,
788 - ],
789 - customTools: [structuredOutputTool],
790 - sessionManager,
826 +function observeToolSession(
827 + session: SessionLike,
828 + opts: RunStepOptions,
829 + meta: ToolStepMeta,
830 + state: ToolStepState,
831 +): () => void {
832 + const controls = toolControls(session, state);
833 + return session.subscribe((event) => {
834 + if (event.type === "message_start" && event.message.role === "assistant")
835 + state.transcript = "";
836 + if (event.type === "agent_end")
837 + state.usage = lastAssistantUsage(
838 + (event as { messages?: unknown }).messages,
839 + );
840 + const update =
841 + event.type === "message_update" ? event.assistantMessageEvent : undefined;
842 + if (update?.type === "text_delta")
843 + state.transcript = appendTranscriptTail(state.transcript, update.delta);
844 + const mapped = mapSessionEvent(event, opts.agentId, opts.phase);
845 + if (!mapped) return;
846 + opts.onProgress?.({
847 + ...mapped,
848 + ...meta,
849 + usage: mapped.kind === "end" ? state.usage : undefined,
850 + controls,
852 + });
793 - const live = session;
794 - const controls: AgentControls = {
795 - steer: (text: string) =>
796 - Promise.resolve(live.steer(text)).catch(() => {}),
797 - abort: () => {
798 - manuallyAborted = true;
799 - return Promise.resolve(live.abort()).catch(() => {});
800 - },
801 - };
855 +function toolControls(
856 + session: SessionLike,
857 + state: ToolStepState,
858 +): AgentControls {
859 + return {
860 + steer: (text: string) =>
861 + Promise.resolve(session.steer(text)).catch(() => {}),
862 + abort: () => {
863 + state.manuallyAborted = true;
864 + return Promise.resolve(session.abort()).catch(() => {});
865 + },
866 + };
803 - unsubscribe = session.subscribe((event) => {
804 - if (event.type === "message_start" && event.message.role === "assistant")
805 - transcript = "";
806 - if (event.type === "agent_end") {
807 - usage = lastAssistantUsage((event as { messages?: unknown }).messages);
808 - }
809 - const update =
810 - event.type === "message_update"
811 - ? event.assistantMessageEvent
812 - : undefined;
813 - if (update?.type === "text_delta")
814 - transcript = appendTranscriptTail(transcript, update.delta);
815 - const mapped = mapSessionEvent(event, agentId, phase);
816 - if (mapped)
817 - onProgress?.({
818 - ...mapped,
819 - ...meta,
820 - usage: mapped.kind === "end" ? usage : undefined,
821 - controls,
822 - });
823 - });
825 - const guarded = await raceAbort(
826 - () => live.prompt(step.prompt, { source: "extension" }),
827 - opts.signal,
828 - );
830 - if (guarded.outcome !== "done") {
831 - // Sessions accept no external signal — abort the live session ourselves.
832 - await Promise.resolve(live.abort()).catch(() => {});
833 - return failed("aborted", "aborted", true, 1, meta, transcript);
834 - }
835 - if (manuallyAborted)
836 - return failed("aborted", "aborted", true, 1, meta, transcript);
837 - if (guarded.error !== undefined) {
838 - const message =
839 - guarded.error instanceof Error
840 - ? guarded.error.message
841 - : String(guarded.error);
842 - return failed("session", message, true, 1, meta, transcript);
843 - }
844 - if (captured) return { ok: true, value: captured.value, usage };
845 - return failed(
846 - "missing-output",
847 - "no structured output produced",
848 - true,
849 - 1,
850 - meta,
851 - transcript,
852 - );
853 - } catch (error) {
854 - const message = error instanceof Error ? error.message : String(error);
855 - return failed("session", message, true, session ? 1 : 0, meta, transcript);
856 - } finally {
857 - try {
858 - unsubscribe();
859 - } catch {}
860 - try {
861 - session?.dispose();
862 - } catch {}
869 +async function promptToolSession(
870 + session: SessionLike,
871 + prompt: string,
872 + signal: AbortSignal | undefined,
873 + meta: ToolStepMeta,
874 + state: ToolStepState,
875 +): Promise<RunStepResult> {
876 + const guarded = await raceAbort(
877 + () => session.prompt(prompt, { source: "extension" }),
878 + signal,
879 + );
880 + if (guarded.outcome !== "done") {
881 + await Promise.resolve(session.abort()).catch(() => {});
882 + return failed("aborted", "aborted", true, 1, meta, state.transcript);
884 + if (state.manuallyAborted)
885 + return failed("aborted", "aborted", true, 1, meta, state.transcript);
886 + if (guarded.error !== undefined) {
887 + const message =
888 + guarded.error instanceof Error
889 + ? guarded.error.message
890 + : String(guarded.error);
891 + return failed("session", message, true, 1, meta, state.transcript);
893 + if (state.captured)
894 + return { ok: true, value: state.captured.value, usage: state.usage };
895 + return failed(
896 + "missing-output",
897 + "no structured output produced",
898 + true,
899 + 1,
900 + meta,
901 + state.transcript,
902 + );
905 +function safeCall(fn: () => void): void {
906 + try {
907 + fn();
908 + } catch {}
866 911 // ---------------------------------------------------------------------------

extensions/ultra/skills/authoring-workflows/SKILL.md

Deleted
deleted file mode 100644
1 ----
2 -name: authoring-workflows
3 -description: Create, author, save, or reuse an ultra multi-agent workflow. Use when the user wants to design a reusable workflow spec — phases, fan-out, output schemas, interpolation — and persist it so it can be re-run later as `/ultra <name>`. Covers the JSON spec format, the read-only fan-out rule, validation, and where to save.
4 ----
6 -# Authoring ultra workflows
8 -This skill helps you co-design a **persisted** ultra workflow with the user and
9 -save it to disk so they can re-run it as `/ultra <name>`. The canonical spec
10 -format lives in [references/spec-format.md](references/spec-format.md) — read it
11 -before writing any spec; do not restate it from memory.
13 -## First: persist vs. one-off (decide silently)
15 -Creation language — "create / author / build / save / write me a workflow that
16 -…" — means the user wants a **persisted** workflow. That is the default this
17 -skill serves: co-design the spec and write the JSON file.
19 -Divert to an **ephemeral one-off** — call the `workflow` tool with an inline
20 -`spec` and skip the authoring/saving flow entirely — only on an explicit
21 -override cue:
23 -- "just run it once" / "one-off" / "don't save it" / "throwaway"
24 -- "try this without saving" / "ad hoc"
26 -Decide silently. **Do not ask "should I save this or just run it?"** and do not
27 -announce the routing — the user's wording already carries the intent, and the
28 -choice is cheap to reverse: a one-off can be saved afterward, and a saved file
29 -can be deleted. When in genuine doubt with creation language, persist (the
30 -reversible, lower-regret default).
32 -## Single-agent gate
34 -Do not create or invoke ultra for an ordinary task that one agent can perform directly.
35 -A workflow with one agent is justified only when it specifically needs context isolation, background execution, an alternate model, resumability, strict structured output, or future reuse as orchestration.
36 -Otherwise perform the task directly and skip ultra's orchestration overhead.
38 -## Authoring flow (persisted)
40 -1. **Understand the goal.** What does each stage do, and what flows between
41 - stages? Most workflows are _fan-out then synthesize_: parallel agents each
42 - handle one item (a dimension, a file, a finding), then a `single` pass
43 - judges or merges. Sketch the phases before writing JSON.
45 -2. **Co-design the phases.** For each phase decide:
46 - - Give every phase a unique interpolation identifier; the reserved phase ID `args` is forbidden.
47 - - `single` (one synthesis/judge pass) vs. `fanout` (one agent per item).
48 - - `fanout` needs an `over` — a literal array, or an interpolation token over
49 - a prior phase's results (e.g. `{review.results[].findings[]}`).
50 - - Optional `when` uses one existing selector; empty/false skips the phase and produces empty results.
51 - - A recovery fan-out may use `{PHASE.failures}` for both `when` and `over`; recovery remains one explicit later phase, never a loop.
52 - - The step `prompt`, its `tools`, and how tightly its structured JSON output must be constrained by a schema.
54 -3. **Apply the read-only fan-out rule.** A `fanout` step with tools must stay
55 - within `read`, `grep`, `find`, `ls`, `bash` **and** the prompt must forbid
56 - mutation — parallel writers race. Put any writing work in a `single` phase.
58 -4. **Design schemas and join-keys.** Give a step a `schema` (named in `schemas`,
59 - or inline) when a later phase consumes its output. When phase B fans out over
60 - phase A's findings, add a shared field (a join-key) to both schemas and tell
61 - B to echo it, so each result ties back to its source. See the `review`
62 - worked example in the reference.
64 -5. **Wire interpolation.** Use only the closed grammar (`{args.NAME}`, `{item}`,
65 - `{PHASE.results}`, `{PHASE.failures}`, `{PHASE.results[].FIELD[]}`, `{EXPR | where FIELD}`). Keep
66 - literal `{`/`}` out of prompts except these tokens. Set `return` to the
67 - selector for the workflow's final value.
69 -6. **Assign compute deliberately.** For every step:
70 - - `big` — planning, specification, architecture, critique, synthesis.
71 - - `medium` — coding, testing, editing, routine implementation.
72 - - `small` — scouting, extraction, classification, easy text work.
73 - - Set `thinkingLevel` from `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` based on that step's relative ambiguity, constraints, and cost of mistakes. `max` is the highest opt-in budget and requires model support.
74 - - Explicitly set both fields. If every phase uses the same pair, challenge the assignment before saving.
76 -7. **Self-check the spec (there is no validator tool).** You can't call
77 - `parseWorkflow` directly — verify by inspection against the reference: every
78 - required field is present, every `fanout` has an `over`, every `when` is one selector, every string
79 - `schema` names a key in `schemas`, and interpolation uses only the closed
80 - grammar. The real validator is the load itself: saving and test-running
81 - (steps 8–9) parses the file through the runtime's `parseWorkflow`, which
82 - surfaces a TypeBox error naming the offending path if anything is malformed —
83 - fix and re-run until it loads clean. One caveat: a JSON _syntax_ error (a
84 - trailing comma, a missing quote) makes the file invisible to discovery
85 - entirely, so `/ultra <name>` reports `unknown workflow` rather than a schema
86 - error — if a saved workflow seems to vanish, confirm it is valid JSON first.
88 -8. **Save it.** Write the spec as `<name>.json` (filename matching the spec's
89 - `name`):
90 - - project-scoped (lives in the repo): `<cwd>/.pi/workflows/<name>.json`
91 - - personal / global: `~/.pi/agent/workflows/<name>.json`
93 - Ask which scope only if it isn't clear from context (a repo-specific review
94 - workflow → project; a personal utility → global).
96 -9. **Offer a test run.** After saving, offer to run it: `/ultra <name>` (with
97 - any `args` the spec's `hint` declares). Tighten prompts/schemas from what the
98 - first run surfaces.
100 -## Ephemeral one-off
102 -On an explicit override cue, skip the flow above: construct the spec inline and
103 -call the `workflow` tool with it as `spec`. Same format and rules
104 -(`spec-format.md`, read-only fan-out), but nothing is written to disk. If the
105 -user later likes it, save it via the persisted flow.

extensions/ultra/skills/authoring-workflows/references/spec-format.md

Deleted
deleted file mode 100644
1 -# ultra workflow spec — canonical reference
3 -A workflow is a single JSON object. `parseWorkflow` (the same validator the
4 -runtime uses) checks it structurally and rejects anything malformed. This file
5 -is the authoritative format reference; the extension `README.md` links here
6 -rather than restating it.
8 -## Top-level fields
10 -| Field | Required | Type | Meaning |
11 -| ------------- | -------- | --------------------------- | -------------------------------------------------------------- |
12 -| `name` | yes | string (non-empty) | Workflow id. The file is invoked as `/ultra <name>`. |
13 -| `description` | no | string | One line shown in the picker. |
14 -| `args` | no | object (`{ hint?, ... }`) | Declares run inputs; `hint` is the usage shown after the name. |
15 -| `schemas` | no | record<string, JSON Schema> | Named, reusable output schemas referenced by steps. |
16 -| `phases` | yes | array (≥1) of phases | The ordered stages. Each is `single` or `fanout`. |
17 -| `return` | no | string (one selector token) | Selects the workflow's final value from phase results. |
19 -`args` may also declare `params`: an ordered list of input names. A bare
20 -`/ultra <name> tokA tokB` line maps tokens onto them positionally; the last declared parameter absorbs all remaining tokens so it can carry free text. Values are exposed as `{args.NAME}`. Without `params`, pass inputs as a trailing JSON object — `/ultra <name> {"k": "v"}`. A missing `{args.NAME}` renders to the empty string.
22 -## Phases
24 -A phase has an `id` (referenced by interpolation and `return`), a `kind`, a
25 -`step`, an optional `concurrency` cap, and an optional `when` selector.
26 -Phase IDs must be unique identifiers matching `[A-Za-z_][A-Za-z0-9_]*`; the reserved phase ID `args` is forbidden because it belongs to the workflow-input namespace.
28 -- **`single`** — runs the step exactly once, for one synthesis / judge /
29 - aggregation pass over prior results. (`over` is accepted by the schema but
30 - **ignored** in v1; for per-item parallelism use `fanout`.)
31 -- **`fanout`** — runs the step once per element of `over`, concurrently (capped
32 - by `concurrency` and the engine's global pool). `over` is **required**.
34 -`when` uses the existing single-selector grammar.
35 -If it resolves to `false`, `null`, `undefined`, an empty string, or an empty array, the phase is skipped and records `{ ran: 0, ok: 0, dropped: 0 }` with empty results.
36 -Any other value runs the phase.
37 -A skipped phase may still be referenced later through empty `{PHASE.results}` and `{PHASE.failures}` arrays.
38 -There are no loops or arbitrary expressions.
40 -`over` is either a literal array or a single interpolation token string (e.g.
41 -`"{review.results[].findings[]}"`).
43 -### The read-only fan-out rule (v1)
45 -A `fanout` step that grants tools must stay within the read-only allowlist —
46 -`read`, `grep`, `find`, `ls`, `bash` — and the prompt must instruct the agent
47 -not to mutate anything. Parallel agents that write race each other; v1 keeps
48 -fan-out side-effect-free. A `single` synthesis phase can be given broader tools
49 -if a workflow genuinely needs to write.
51 -## Steps
53 -| Field | Required | Type | Meaning |
54 -| --------------- | -------- | --------------------- | ------------------------------------------------------------------------------------------------- |
55 -| `prompt` | yes | string | The agent instruction. Interpolates `{...}` tokens (see below). |
56 -| `tools` | no | string[] | Tool allowlist. Omit for a tool-less completion (pure reasoning). |
57 -| `model` | no | string | `provider/id` override, or configured tier `small`/`medium`/`big`; defaults to the session model. |
58 -| `thinkingLevel` | no | off…max | Reasoning budget for this step. |
59 -| `schema` | no | string \| JSON Schema | A `schemas` name, or an inline schema that validates structured output. |
61 -Every step returns a JSON object through completion parsing or the terminating `structured_output` tool.
62 -Without `schema`, any JSON object is accepted.
63 -A `schema` validates that object and is required when downstream phases depend on a stable shape.
64 -A string `schema` is a **name reference** and must resolve in the spec's `schemas` map, or validation fails.
66 -Configured model tiers live in Pi settings under `ultra.modelTiers`.
67 -If a step sets `model` to `small`, `medium`, or `big`, ultra resolves it through that map; an unset tier falls back to the session model.
68 -Tier values may include a thinking suffix like `openai/gpt-5-mini:low`, used only when the step omits `thinkingLevel`.
70 -### Model tier and thinking rubric
72 -Set both `model` and `thinkingLevel` on every authored step.
73 -Choose them from the work that step performs, not by copying another phase:
75 -| Work | Tier |
76 -| ---------------------------------------------------------- | -------- |
77 -| Planning, specification, architecture, critique, synthesis | `big` |
78 -| Coding, testing, editing, routine implementation | `medium` |
79 -| Scouting, extraction, classification, easy text work | `small` |
81 -Choose `big` models that gather context and knowledge.
82 -Choose `medium` models when context and knowledge has already been gathered in previous steps.
84 -Choose thinking independently from the tier and relative to that step's difficulty:
86 -- `off` / `minimal` — deterministic extraction, transcription, or formatting with negligible ambiguity.
87 -- `low` / `medium` — routine decisions with bounded context and cheap mistakes and when context has been prepared beforehand.
88 -- `high` / `xhigh` / `max` — ambiguous, multi-constraint reasoning where a wrong decision is costly downstream. `max` is the highest opt-in budget and requires model support.
90 -If every phase has the same model/thinking pair, re-evaluate each assignment before saving.
91 -Uniform settings are valid only when the phases genuinely perform equally difficult work of the same kind.
93 -Examples:
95 -- Repository inventory: `medium` + `low`.
96 -- Implement a well-specified edit: `big` + `medium`.
97 -- Design architecture from conflicting requirements: `big` + `high`.
98 -- Adversarially critique a risky plan: `big` + `xhigh`.
100 -## Interpolation grammar
102 -A closed mini-syntax — not an expression evaluator, no `eval`. Tokens
103 -(braces are literal here, shown without JSON quoting):
105 -```text
106 -{args.NAME} workflow input value
107 -{item} current fanout item (string verbatim; else compact JSON)
108 -{PHASE.results} a prior phase's results array (nulls retained positionally)
109 -{PHASE.failures} a prior phase's typed failure array
110 -{PHASE.results[].FIELD[]} flatten: concat each result's FIELD array (nulls/missing skipped)
111 -{EXPR | where FIELD} keep elements whose boolean FIELD is truthy
112 -```
114 -Anything outside this grammar raises a validation error at run time. In a
115 -step `prompt`, the only literal braces allowed are these tokens — do not put
116 -raw `{`/`}` (e.g. an inline JSON example) in a prompt; describe the shape in
117 -words and use a `schema` instead.
119 -### Explicit linear recovery
121 -A dropped step appears in `{PHASE.failures}` with `agentId`, `index`, optional original `item`, `code`, `message`, `retryable`, `attempts`, optional `model`, optional `thinkingLevel`, and an optional 2,000-character `transcriptTail`.
122 -Failure codes are `auth`, `transport`, `invalid-json`, `schema`, `missing-output`, `aborted`, or `session`.
124 -Use the non-empty failure array to condition and fan out one later recovery phase:
126 -```json
128 - "id": "recover",
129 - "kind": "fanout",
130 - "when": "{work.failures}",
131 - "over": "{work.failures}",
132 - "step": {
133 - "prompt": "Recover this failed task and return the required result. Failure: {item}",
134 - "model": "big",
135 - "thinkingLevel": "high"
136 - }
138 -```
140 -Ultra has no timeout, automatic rerun, loop, or back-edge.
141 -`ultra.maxRetries` retries tool-less transport failures and invalid completion output inside one step.
142 -Workflow authors explicitly place any recovery phase after the failed phase.
144 -### Schema join-keys
146 -When one phase fans out over another's findings, give the producer schema and
147 -the consumer schema a shared field (a "join key") and instruct the consumer to
148 -echo it. In the worked example below, `Findings.file` is echoed into
149 -`Verdict.file`, so each verdict ties back to the finding it judges.
151 -## Worked example — minimal single fan-out
153 -Every `fanout` agent reads one path and returns a structured summary. Tools are
154 -read-only; the prompt forbids mutation.
156 -```json
158 - "name": "summarize-paths",
159 - "description": "Summarize each input path in parallel.",
160 - "args": { "hint": "<paths>" },
161 - "phases": [
162 - {
163 - "id": "summarize",
164 - "kind": "fanout",
165 - "over": "{args.paths}",
166 - "step": {
167 - "prompt": "Read the file at {item} and return JSON with two string fields: path (the file path you were given) and summary (one sentence). Do not modify anything.",
168 - "tools": ["read"],
169 - "model": "small",
170 - "thinkingLevel": "low",
171 - "schema": {
172 - "type": "object",
173 - "properties": {
174 - "path": { "type": "string" },
175 - "summary": { "type": "string" }
176 - },
177 - "required": ["path", "summary"]
178 - }
179 - }
180 - }
181 - ],
182 - "return": "{summarize.results}"
184 -```
186 -## Worked example — two phases with a join key
188 -Fan out a review across dimensions, then fan out verification over the flattened
189 -findings. `Findings.file` → `Verdict.file` is the join key; `return` filters to
190 -the verdicts the verifier judged `real`. The single `params` entry lets a bare
191 -`/ultra review main` map `main` to `{args.base}` (a missing arg renders empty, so
192 -the diff falls back to the working tree).
194 -```json
196 - "name": "review",
197 - "description": "Review the diff across dimensions, then adversarially verify each finding.",
198 - "args": { "hint": "[base-ref]", "params": ["base"] },
199 - "schemas": {
200 - "Findings": {
201 - "type": "object",
202 - "properties": {
203 - "findings": {
204 - "type": "array",
205 - "items": {
206 - "type": "object",
207 - "properties": {
208 - "title": { "type": "string" },
209 - "file": { "type": "string" },
210 - "detail": { "type": "string" }
211 - },
212 - "required": ["title", "file"]
213 - }
214 - }
215 - },
216 - "required": ["findings"]
217 - },
218 - "Verdict": {
219 - "type": "object",
220 - "properties": {
221 - "title": { "type": "string" },
222 - "real": { "type": "boolean" },
223 - "why": { "type": "string" },
224 - "file": {
225 - "type": "string",
226 - "description": "echo of the reviewed finding's file, for correlation"
227 - }
228 - },
229 - "required": ["title", "real", "file"]
230 - }
231 - },
232 - "phases": [
233 - {
234 - "id": "review",
235 - "kind": "fanout",
236 - "over": ["correctness", "security", "performance"],
237 - "step": {
238 - "prompt": "Review the diff for {item} issues. Inspect it with `git diff {args.base}` (no base ref → the working tree; a base ref → everything since that ref), plus read/grep as needed; do not modify any files. Return JSON matching the Findings schema, and set each finding's file to the path it concerns.",
239 - "tools": ["read", "bash", "grep", "find", "ls"],
240 - "model": "small",
241 - "thinkingLevel": "medium",
242 - "schema": "Findings"
243 - }
244 - },
245 - {
246 - "id": "verify",
247 - "kind": "fanout",
248 - "over": "{review.results[].findings[]}",
249 - "step": {
250 - "prompt": "Adversarially try to refute this finding. Default to real=false if uncertain. Echo the finding's file verbatim in your verdict's file field so the verdict ties back to its finding. Finding: {item}",
251 - "model": "big",
252 - "thinkingLevel": "high",
253 - "schema": "Verdict"
254 - }
255 - }
256 - ],
257 - "return": "{verify.results | where real}"
259 -```
261 -## Where workflows live
263 -Discovery merges three locations, lowest-to-highest precedence — a later source
264 -overrides a bundled name:
266 -1. **bundled** — `<extension>/workflows/*.json` (ships with ultra)
267 -2. **global** — `~/.pi/agent/workflows/*.json`
268 -3. **project** — `<cwd>/.pi/workflows/*.json`
270 -Save an authored workflow as `<name>.json` (filename should match the spec's
271 -`name`) in the project dir for repo-scoped workflows, or the global dir for
272 -personal ones.

package.json

Modified
26 26 "extensions/*/index.ts"
28 28 "skills": [
29 - "extensions/ultra/skills",
30 29 "extensions/lazy/skills"

scripts/extensions.mjs

Modified
892 892 errors.push("root: pi.extensions must be ['extensions/*/index.ts']");
894 894 JSON.stringify(pkg.pi?.skills) !==
895 - JSON.stringify(["extensions/ultra/skills", "extensions/lazy/skills"])
895 + JSON.stringify(["extensions/lazy/skills"])
897 - errors.push(
898 - "root: pi.skills must be ['extensions/ultra/skills', 'extensions/lazy/skills']",
899 - );
897 + errors.push("root: pi.skills must be ['extensions/lazy/skills']");
900 898 if ("prompts" in (pkg.pi ?? {}))
901 899 errors.push("root: pi.prompts must be absent");
902 900 if ("themes" in (pkg.pi ?? {})) errors.push("root: pi.themes must be absent");

scripts/test_extensions_static_check.mjs

Modified
175 175 assert.deepEqual(rootPkg().pi, {
176 176 extensions: ["extensions/*/index.ts"],
177 - skills: ["extensions/ultra/skills", "extensions/lazy/skills"],
177 + skills: ["extensions/lazy/skills"],
180 180 assert.deepEqual(