repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs: plan mise task architecture phase one

7306ac6033c8aae83cb1330a2891039ab9b675f7

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (2)

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

Added
new file mode 100644
1 +# Mise Task Architecture Phase 1 Implementation Plan
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Establish mise monorepo task ownership, move all existing benchmarks into extension-local tasks, add a sequential root benchmark aggregate, and remove `goal-expect`.
7 +**Architecture:** Root mise keeps shared tools and repository-wide workflows while explicit extension config roots provide qualified local tasks. Each benchmark-owning extension receives one `bench` task, and the root aggregate dispatches those tasks with one mise job so measurements never overlap.
9 +**Tech Stack:** mise 2026.6+, TOML, Node.js 26 native TypeScript stripping, Vitest benchmark runner, npm workspaces.
11 +**Roadmap:** [`docs/super/roadmaps/2026-07-12-mise-task-architecture-roadmap.md`](../roadmaps/2026-07-12-mise-task-architecture-roadmap.md)
13 +**Phase:** Phase 1: Monorepo Foundation And Benchmarks
15 +---
17 +## File Structure
19 +**Create:**
21 +- `extensions/goal/mise.toml`: goal replay benchmark command.
22 +- `extensions/llmiterate/mise.toml`: parser/path-filter and gitignore benchmark commands.
23 +- `extensions/prompt-autopsy/mise.toml`: prompt grouping benchmark command.
24 +- `extensions/q/mise.toml`: heuristic extraction benchmark command.
25 +- `extensions/terse/mise.toml`: terse prompt injection benchmark command.
26 +- `extensions/web/mise.toml`: HTML processing benchmark command.
28 +**Modify:**
30 +- `.miserc.toml`: retain the already-created portable parent-config ceiling.
31 +- `mise.toml`: enable monorepo discovery, add aggregate `bench`, remove `bench-q` and `goal-expect`.
32 +- `extensions/llmiterate/__bench__/bench.ts`: use explicit `.ts` imports supported by Node 26.
33 +- `extensions/goal/package.json`: remove the stale, broken package-level benchmark script.
34 +- `AGENTS.md`: document the Phase 1 benchmark task surface and qualified task syntax while retaining legacy E2E commands until Phase 2.
35 +- Benchmark-owning extension READMEs: document local and root-qualified benchmark commands.
37 +**Delete:**
39 +- `scripts/test_goal_expect.mjs`: nondeterministic external-model Expect smoke workflow.
41 +**Unchanged:**
43 +- `vitest.config.ts`: unit and integration test aggregation remains root-owned.
44 +- Playwright files and E2E tasks: deferred to Phase 2.
45 +- Root `ci`: retains lint, test, and check until E2E coverage is complete in Phase 4.
47 +### Task 1: Establish Portable Mise Monorepo Discovery
49 +**Files:**
51 +- Modify: `.miserc.toml`
52 +- Modify: `mise.toml:1-7`
54 +- [ ] **Step 1: Record the unrelated root config diff before editing**
56 +Run:
58 +```bash
59 +git diff -- mise.toml
60 +git status --short
61 +```
63 +Expected: `mise.toml` already shows unrelated removal of the Nushell tool and inline-shell settings, and `.miserc.toml` is untracked.
64 +Do not restore, rewrite, stage, or commit those pre-existing root changes.
66 +- [ ] **Step 2: Run the failing monorepo discovery check**
68 +Run:
70 +```bash
71 +mise tasks --all --name-only
72 +```
74 +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 +Ensure `.miserc.toml` contains exactly:
80 +```toml
81 +ceiling_paths = ["{{ config_root | dirname }}"]
82 +```
84 +This file is early-init configuration and must not move into `mise.toml`.
86 +- [ ] **Step 4: Enable explicit monorepo roots**
88 +Add these root-level keys before `[tools]` in `mise.toml`:
90 +```toml
91 +monorepo_root = true
93 +[monorepo]
94 +config_roots = ["extensions/*"]
95 +```
97 +Keep the existing `[tools]` table and every task unchanged in this step.
98 +Preserve the pre-existing Nushell/settings removals exactly.
100 +- [ ] **Step 5: Verify config isolation and monorepo parsing**
102 +Run:
104 +```bash
105 +mise config ls
106 +mise tasks --all --name-only
107 +```
109 +Expected from `mise config ls`: only `~/Workspace/dotfiles/pi-ext/mise.toml` is listed as project config, plus no parent `dotfiles/mise.toml`.
110 +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 +Run:
116 +```bash
117 +git add .miserc.toml
118 +git diff --cached --check
119 +git commit -m "build: isolate pi-ext mise config"
120 +```
122 +Expected: the commit contains `.miserc.toml` only.
123 +Leave `mise.toml` unstaged because it contains pre-existing unrelated work that cannot safely be staged as a whole.
125 +### Task 2: Add Extension-Local Benchmark Tasks
127 +**Files:**
129 +- Create: `extensions/goal/mise.toml`
130 +- Create: `extensions/llmiterate/mise.toml`
131 +- Create: `extensions/prompt-autopsy/mise.toml`
132 +- Create: `extensions/q/mise.toml`
133 +- Create: `extensions/terse/mise.toml`
134 +- Create: `extensions/web/mise.toml`
135 +- Modify: `extensions/llmiterate/__bench__/bench.ts:1-4`
137 +- [ ] **Step 1: Confirm qualified benchmark tasks are missing**
139 +Run:
141 +```bash
142 +mise tasks --all --name-only
143 +```
145 +Expected: none of these names exists:
147 +```text
148 +//extensions/goal:bench
149 +//extensions/llmiterate:bench
150 +//extensions/prompt-autopsy:bench
151 +//extensions/q:bench
152 +//extensions/terse:bench
153 +//extensions/web:bench
154 +```
156 +- [ ] **Step 2: Add the goal benchmark task**
158 +Create `extensions/goal/mise.toml`:
160 +```toml
161 +[tasks.bench]
162 +description = "Benchmark goal state replay"
163 +depends = ["//:install"]
164 +run = "node --no-warnings --experimental-strip-types __benches__/goal-state.bench.ts"
165 +```
167 +- [ ] **Step 3: Make llmiterate’s standalone benchmark Node-resolvable**
169 +Change the imports at the top of `extensions/llmiterate/__bench__/bench.ts` to:
171 +```ts
172 +import { performance } from "node:perf_hooks";
173 +import { defaultConfig } from "../config.ts";
174 +import { parseMarkerPrompts } from "../parser.ts";
175 +import {
176 + compilePathFilter,
177 + shouldIncludeCompiledPath,
178 +} from "../path-filter.ts";
179 +```
181 +Do not alter benchmark inputs, iteration controls, or output.
183 +- [ ] **Step 4: Add both llmiterate benchmarks to one local task**
185 +Create `extensions/llmiterate/mise.toml`:
187 +```toml
188 +[tasks.bench]
189 +description = "Benchmark marker parsing and gitignore scans"
190 +depends = ["//:install"]
191 +run = [
192 + "node --no-warnings --experimental-strip-types __bench__/bench.ts",
193 + "npm exec -- vitest bench __benches__/gitignore.bench.ts --run --project fast --reporter=default",
195 +```
197 +The explicit `fast` project prevents the root Vitest multi-project config from running the same benchmark twice.
198 +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 +Create `extensions/prompt-autopsy/mise.toml`:
204 +```toml
205 +[tasks.bench]
206 +description = "Benchmark system prompt grouping"
207 +depends = ["//:install"]
208 +run = "node --no-warnings --experimental-strip-types __bench__/bench.ts"
209 +```
211 +- [ ] **Step 6: Add the q benchmark task**
213 +Create `extensions/q/mise.toml`:
215 +```toml
216 +[tasks.bench]
217 +description = "Benchmark heuristic question extraction"
218 +depends = ["//:install"]
219 +run = "node --no-warnings --experimental-strip-types --experimental-loader ../../scripts/ts-js-loader.mjs __benches__/extract.bench.ts"
220 +```
222 +- [ ] **Step 7: Add the terse benchmark task**
224 +Create `extensions/terse/mise.toml`:
226 +```toml
227 +[tasks.bench]
228 +description = "Benchmark terse prompt injection"
229 +depends = ["//:install"]
230 +run = "node --no-warnings --experimental-strip-types __bench__/bench.ts"
231 +```
233 +- [ ] **Step 8: Add the web benchmark task**
235 +Create `extensions/web/mise.toml`:
237 +```toml
238 +[tasks.bench]
239 +description = "Benchmark web processing hot paths"
240 +depends = ["//:install"]
241 +run = "node --no-warnings --experimental-strip-types --experimental-loader ../../scripts/ts-js-loader.mjs __bench__/bench.ts"
242 +```
244 +- [ ] **Step 9: Verify discovery and each command shape**
246 +Run:
248 +```bash
249 +mise tasks --all --name-only
250 +mise run --dry-run //extensions/goal:bench
251 +mise run --dry-run //extensions/llmiterate:bench
252 +mise run --dry-run //extensions/prompt-autopsy:bench
253 +mise run --dry-run //extensions/q:bench
254 +mise run --dry-run //extensions/terse:bench
255 +mise run --dry-run //extensions/web:bench
256 +```
258 +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 +Run:
264 +```bash
265 +mise run //extensions/llmiterate:bench
266 +mise run //extensions/q:bench
267 +```
269 +Expected: both commands exit 0 and print benchmark results.
270 +The llmiterate output contains both standalone `Benchmark...` lines and the Vitest `gitignore scan performance` table.
272 +- [ ] **Step 11: Commit extension benchmark ownership**
274 +Run:
276 +```bash
277 +git add extensions/goal/mise.toml extensions/llmiterate/mise.toml extensions/llmiterate/__bench__/bench.ts extensions/prompt-autopsy/mise.toml extensions/q/mise.toml extensions/terse/mise.toml extensions/web/mise.toml
278 +git diff --cached --check
279 +git commit -m "build: localize extension benchmarks"
280 +```
282 +Expected: the commit contains six local mise configs and the llmiterate import correction only.
284 +### Task 3: Add Root Benchmark Aggregation And Remove Obsolete Workflows
286 +**Files:**
288 +- Modify: `mise.toml:48-51,163-end`
289 +- Modify: `extensions/goal/package.json`
290 +- Delete: `scripts/test_goal_expect.mjs`
292 +- [ ] **Step 1: Confirm the old root surface still exists**
294 +Run:
296 +```bash
297 +mise tasks --name-only
298 +```
300 +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 +Replace the complete `[tasks.bench-q]` block in `mise.toml` with:
306 +```toml
307 +[tasks.bench]
308 +description = "Run all extension benchmarks sequentially"
309 +depends = ["install"]
310 +run = "mise run --jobs 1 //extensions/...:bench"
311 +```
313 +The extension-qualified wildcard excludes the root aggregate itself.
314 +`--jobs 1` is mandatory because concurrent benchmark processes contaminate measurements.
316 +- [ ] **Step 3: Remove the root goal Expect task**
318 +Delete the complete `[tasks.goal-expect]` block from `mise.toml`, including its usage specification and multiline command.
319 +Do not change `tasks.ci` or any E2E task in this phase.
321 +- [ ] **Step 4: Delete the nondeterministic smoke script**
323 +Delete `scripts/test_goal_expect.mjs`.
324 +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 +In `extensions/goal/package.json`, remove:
330 +```json
331 +"scripts": {
332 + "bench": "node bench/goal-state.bench.ts"
334 +```
336 +The path is stale (`bench/` versus `__benches__/`), and local mise now owns the benchmark command.
337 +Keep every dependency and package metadata field unchanged.
339 +- [ ] **Step 6: Verify the clean root task surface**
341 +Run:
343 +```bash
344 +mise tasks --name-only
345 +mise tasks --all --name-only
346 +mise run --dry-run bench
347 +```
349 +Expected root names: `bench` exists; `bench-q` and `goal-expect` do not.
350 +Expected all-task names: all six qualified extension benchmarks still exist.
351 +Expected dry-run behavior: root `install` precedes one nested `mise run --jobs 1 //extensions/...:bench` command.
353 +- [ ] **Step 7: Run the aggregate benchmark**
355 +Run:
357 +```bash
358 +mise run bench
359 +```
361 +Expected: goal, llmiterate, prompt-autopsy, q, terse, and web benchmarks run one after another and the task exits 0.
362 +No two `[//extensions/...:bench]` task headers overlap in time.
364 +- [ ] **Step 8: Commit only safely isolated files**
366 +Run:
368 +```bash
369 +git add extensions/goal/package.json scripts/test_goal_expect.mjs
370 +git diff --cached --check
371 +git commit -m "build: remove goal expect smoke"
372 +```
374 +Expected: the commit removes the Expect script and stale goal package script.
375 +Keep `mise.toml` unstaged unless its pre-existing unrelated hunk can be isolated without staging it.
376 +Never commit the existing Nushell/settings removal as part of this work.
378 +### Task 4: Document Root And Local Commands
380 +**Files:**
382 +- Modify: `AGENTS.md:8-31`
383 +- Modify: `extensions/goal/README.md`
384 +- Modify: `extensions/llmiterate/README.md`
385 +- Modify: `extensions/prompt-autopsy/README.md`
386 +- Modify: `extensions/q/README.md:36-39`
387 +- Modify: `extensions/terse/README.md`
388 +- Modify: `extensions/web/README.md`
390 +- [ ] **Step 1: Update the root task table**
392 +In `AGENTS.md`, remove the `Goal expect` row.
393 +Keep the existing `E2E browsers` and `E2E review` rows until Phase 2 replaces those tasks.
394 +Add this row after `Test`:
396 +```markdown
397 +| Bench | `mise run bench` | Run extension benchmarks sequentially |
398 +```
400 +Defer all E2E documentation changes until Phase 2 introduces the aggregate.
401 +Keep the CI description as `Release gate (lint + test + check)` in this phase.
403 +- [ ] **Step 2: Document qualified local task syntax**
405 +After the root task table in `AGENTS.md`, add:
407 +```markdown
408 +Extension-specific tasks live in extension-local `mise.toml` files.
409 +Run one from the root with `mise //extensions/<name>:<task>`.
410 +Use `mise tasks --all` to list root and extension-local tasks.
411 +```
413 +- [ ] **Step 3: Replace q’s obsolete benchmark command**
415 +In `extensions/q/README.md`, replace:
417 +```markdown
418 +- `mise run bench-q` — benchmark the local heuristic extractor.
419 +```
421 +with:
423 +```markdown
424 +- `mise run bench` from this extension, or `mise //extensions/q:bench` from the repository root, benchmarks the local heuristic extractor.
425 +```
427 +- [ ] **Step 4: Add one benchmark sentence to each remaining owner README**
429 +Add a `## Bench` section near the command or development documentation in each README.
430 +Use these exact sentences:
432 +`extensions/goal/README.md`:
434 +```markdown
435 +## Bench
437 +Run `mise run bench` here, or `mise //extensions/goal:bench` from the repository root, to benchmark goal state replay.
438 +```
440 +`extensions/llmiterate/README.md`:
442 +```markdown
443 +## Bench
445 +Run `mise run bench` here, or `mise //extensions/llmiterate:bench` from the repository root, to benchmark marker parsing, path filtering, and gitignore scans.
446 +```
448 +`extensions/prompt-autopsy/README.md`:
450 +```markdown
451 +## Bench
453 +Run `mise run bench` here, or `mise //extensions/prompt-autopsy:bench` from the repository root, to benchmark system prompt grouping.
454 +```
456 +`extensions/terse/README.md`:
458 +```markdown
459 +## Bench
461 +Run `mise run bench` here, or `mise //extensions/terse:bench` from the repository root, to benchmark terse prompt injection.
462 +```
464 +`extensions/web/README.md`:
466 +```markdown
467 +## Bench
469 +Run `mise run bench` here, or `mise //extensions/web:bench` from the repository root, to benchmark web processing hot paths.
470 +```
472 +Preserve each README’s existing semantic line breaks.
474 +- [ ] **Step 5: Verify obsolete documentation is gone**
476 +Run:
478 +```bash
479 +node -e "const fs=require('node:fs'); for(const p of ['AGENTS.md','extensions/q/README.md']) { const s=fs.readFileSync(p,'utf8'); for(const old of ['bench-q','goal-expect']) if(s.includes(old)) throw new Error(p+': '+old); }"
480 +```
482 +Expected: exit 0 with no output.
483 +The existing E2E task names remain documented until Phase 2.
485 +- [ ] **Step 6: Verify formatting without mutating the dirty worktree**
487 +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 +The final `mise run ci` step runs the non-mutating lint checks and reports any formatting failures.
490 +Run:
492 +```bash
493 +git diff --check -- AGENTS.md extensions/goal/README.md extensions/llmiterate/README.md extensions/prompt-autopsy/README.md extensions/q/README.md extensions/terse/README.md extensions/web/README.md
494 +```
496 +Expected: exit 0 with no output.
498 +- [ ] **Step 7: Commit documentation only**
500 +Run:
502 +```bash
503 +git add AGENTS.md extensions/goal/README.md extensions/llmiterate/README.md extensions/prompt-autopsy/README.md extensions/q/README.md extensions/terse/README.md extensions/web/README.md
504 +git diff --cached --check
505 +git commit -m "docs: explain extension benchmark tasks"
506 +```
508 +Expected: only command documentation is committed.
509 +Do not stage unrelated formatting changes.
511 +### Task 5: Verify Phase Boundary And Reconcile Root Config Staging
513 +**Files:**
515 +- Verify: `.miserc.toml`
516 +- Verify: `mise.toml`
517 +- Verify: all six extension `mise.toml` files
518 +- Verify: repository test and static-check paths
520 +- [ ] **Step 1: Validate mise task definitions**
522 +Run:
524 +```bash
525 +mise tasks validate
526 +mise tasks --name-only
527 +mise tasks --all --name-only
528 +```
530 +Expected: validation exits 0.
531 +The root list contains `bench` but not `bench-q` or `goal-expect`.
532 +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 +Run:
538 +```bash
539 +mise run bench
540 +```
542 +Expected: all six extension benchmark groups exit 0 and execute sequentially.
544 +- [ ] **Step 3: Run the unchanged Phase 1 release gate**
546 +Run:
548 +```bash
549 +mise run ci
550 +```
552 +Expected: lint, Vitest, and static checks all pass.
553 +E2E does not run in Phase 1.
555 +- [ ] **Step 4: Inspect all work and preserve unrelated changes**
557 +Run:
559 +```bash
560 +git status --short
561 +git diff --stat
562 +git diff -- mise.toml
563 +git diff --cached --stat
564 +```
566 +Expected: unrelated pre-existing changes remain present and unstaged.
567 +The `mise.toml` diff contains both the owner’s pre-existing Nushell/settings removal and this phase’s monorepo/task changes.
568 +Do not claim or commit the former.
570 +- [ ] **Step 5: Commit the root config only if the relevant patch can be isolated**
572 +Use interactive patch staging for `mise.toml` and select only:
574 +- `monorepo_root = true`.
575 +- `[monorepo]` and `config_roots = ["extensions/*"]`.
576 +- Replacement of `bench-q` with `bench`.
577 +- Removal of `[tasks.goal-expect]`.
579 +Run:
581 +```bash
582 +git add -p mise.toml
583 +git diff --cached -- mise.toml
584 +git diff --cached --check
585 +git commit -m "build: organize mise monorepo tasks"
586 +```
588 +Expected staged diff: no Nushell tool or inline-shell setting changes.
589 +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 +Run:
595 +```bash
596 +mise config ls
597 +mise run --dry-run bench
598 +mise run --dry-run ci
599 +```
601 +Expected:
603 +- Parent dotfiles project config is absent.
604 +- Benchmark aggregation resolves all local tasks with one job.
605 +- CI still resolves lint, test, and check only.
606 +- No E2E task migration or browser configuration changed.
608 +- [ ] **Step 7: Report completion evidence**
610 +Report:
612 +- Root and qualified task-list results.
613 +- `mise run bench` result.
614 +- `mise run ci` result.
615 +- Commits created.
616 +- Any intentionally unstaged `mise.toml` implementation hunk caused by the pre-existing dirty file.
617 +- Confirmation that Phase 2 remains unimplemented.

docs/super/roadmaps/2026-07-12-mise-task-architecture-roadmap.md

Added
new file mode 100644
1 +# Mise Task Architecture Roadmap
3 +> **For agentic workers:** Use /skill:writing-plans to create one detailed implementation plan per phase. Start with Phase 1 and proceed sequentially unless the user explicitly changes the order.
5 +**Goal:** Create a clean mise monorepo where root tasks aggregate repository workflows and extension configs own benchmarks and browser E2E details.
7 +**Design Spec:** [`docs/super/specs/2026-07-12-mise-task-architecture-design.md`](../specs/2026-07-12-mise-task-architecture-design.md)
9 +**Planning Strategy:** Separate task ownership migration from browser coverage because the existing benchmark move is mechanical while each browser suite crosses distinct server, process, and interaction boundaries.
11 +---
13 +## Phase 1: Monorepo Foundation And Benchmarks
15 +**Outcome:** Mise monorepo discovery works, benchmark ownership is extension-local, aggregate benchmarks run sequentially, and `goal-expect` is gone.
16 +Legacy root E2E tasks remain temporarily until Phase 2 replaces them atomically.
18 +**Why now:** Later E2E aggregation depends on qualified extension-local task discovery and a stable root task surface.
20 +**Scope:**
22 +- Enable explicit mise monorepo config roots for `extensions/*`.
23 +- Preserve shared tools and repository-wide lifecycle, release, and hook tasks at root.
24 +- Add local `bench` tasks to goal, llmiterate, prompt-autopsy, q, terse, and web.
25 +- Add a sequential root `bench` aggregate.
26 +- Remove `bench-q`, `goal-expect`, and the external-model Expect script.
27 +- Commit the portable `.miserc.toml` ceiling that isolates pi-ext from the parent dotfiles config.
28 +- Update benchmark and root-task documentation affected by the move.
30 +**Out of scope:**
32 +- Playwright configuration changes.
33 +- New browser tests.
34 +- Adding E2E to CI.
36 +**Key files/areas likely affected:**
38 +- `mise.toml`: monorepo declaration, root task cleanup, and benchmark aggregate.
39 +- `.miserc.toml`: portable parent-config ceiling.
40 +- `extensions/{goal,llmiterate,prompt-autopsy,q,terse,web}/mise.toml`: local benchmark ownership.
41 +- `scripts/test_goal_expect.mjs`: removal.
42 +- `AGENTS.md` and benchmark-owning extension READMEs: command documentation.
44 +**Dependencies:**
46 +- Approved design spec.
48 +**Verification:**
50 +- Root task listing contains no extension-specific benchmark or goal smoke task.
51 +- Existing E2E root tasks remain functional until Phase 2 replaces them.
52 +- All qualified benchmark tasks are discoverable from root.
53 +- Root `bench` invokes all six benchmark groups sequentially.
54 +- Existing `mise run ci` remains green with its pre-E2E behavior.
56 +**Phase boundary health:** The test and release gate remain unchanged while task discovery and manual benchmark ownership become coherent.
58 +**Risks:**
60 +- The root `mise.toml` already contains unrelated dirty work, so edits must preserve and avoid committing those lines.
61 +- Benchmark directory names differ between extensions, so each local task must cover all existing benchmark entrypoints without renaming source files unnecessarily.
63 +**Context notes:** Prefer mise monorepo path syntax over custom dispatch scripts, and do not add a benchmark framework or shared wrapper.
65 +## Phase 2: Existing E2E Suites And Aggregate Command
67 +**Outcome:** Diff-review and UI own consistent local E2E tasks, both suites run in Chromium and Firefox, and one root `e2e` command installs browsers once and dispatches discovered suites.
69 +**Why now:** These are the existing Playwright suites and establish the minimal reusable task shape before adding coverage to untested browser servers.
71 +**Scope:**
73 +- Move diff-review’s root-specific E2E task into `extensions/diff-review/mise.toml`.
74 +- Add local mise ownership for UI’s existing E2E suite.
75 +- Normalize both Playwright configurations to Chromium and Firefox projects.
76 +- Replace the public root `e2e-diff-review` and extension-specific browser installer with one aggregate root `e2e` workflow.
77 +- Ensure browser installation occurs once per aggregate run.
78 +- Keep detailed logic in Vitest and browser coverage smoke-focused.
80 +**Out of scope:**
82 +- Mockup browser coverage.
83 +- Tune browser coverage.
84 +- Making E2E a CI gate before all required HTML-serving extensions are covered.
86 +**Key files/areas likely affected:**
88 +- `mise.toml`: aggregate E2E entrypoint and browser setup.
89 +- `extensions/diff-review/mise.toml`: local E2E task.
90 +- `extensions/ui/mise.toml`: local E2E task.
91 +- `extensions/diff-review/playwright.config.ts`: two-browser matrix.
92 +- `extensions/ui/playwright.config.ts`: two-browser matrix.
93 +- Existing package scripts and Playwright dependencies: remove duplicate command ownership where safe.
95 +**Dependencies:**
97 +- Phase 1 monorepo task discovery.
98 +- Playwright Chromium and Firefox availability on supported platforms.
100 +**Verification:**
102 +- Qualified diff-review and UI E2E tasks pass in Chromium and Firefox.
103 +- Root `mise run e2e` installs required browsers once and runs both suites.
104 +- Root Vitest still excludes `__e2e__`.
105 +- Existing CI remains green without yet invoking E2E.
107 +**Phase boundary health:** All existing browser suites gain one consistent manual aggregate while the release gate remains unchanged until complete coverage exists.
109 +**Risks:**
111 +- Firefox may expose assumptions hidden by Chromium-only UI tests.
112 +- Browser installation and executable selection differ across Windows, macOS, Linux, and CI, so Playwright defaults should replace OS-specific executable logic unless explicitly required.
114 +**Context notes:** Exercise the real extension and browser path; avoid mocks that reduce E2E to another unit test.
116 +## Phase 3: Mockup Browser E2E Coverage
118 +**Outcome:** The-system’s mockup server has a local Playwright suite covering its essential browser feedback round trip in Chromium and Firefox.
120 +**Why now:** Mockup is an interactive HTML server with blocking browser-to-agent behavior and deserves isolated treatment before CI promotion.
122 +**Scope:**
124 +- Add a local `e2e` task and Playwright configuration to the-system.
125 +- Cover page startup, option rendering, one selection or feedback interaction, and completion back to the server.
126 +- Make the new suite automatically participate in the root E2E aggregate.
127 +- Preserve current Vitest tests for validation and server internals.
129 +**Out of scope:**
131 +- Visual pixel regression testing.
132 +- Exhaustive combinations of notes, annotations, selection modes, and iteration cycles.
133 +- Tune browser coverage.
134 +- CI promotion.
136 +**Key files/areas likely affected:**
138 +- `extensions/the-system/mise.toml`: local E2E ownership.
139 +- `extensions/the-system/playwright.config.ts`: browser matrix and test location.
140 +- `extensions/the-system/__e2e__/`: real browser smoke path.
141 +- `extensions/the-system/mockup.ts`: test seam changes only if the actual boundary cannot be driven deterministically.
143 +**Dependencies:**
145 +- Phase 2 aggregate E2E command and browser setup.
147 +**Verification:**
149 +- The mockup suite passes in Chromium and Firefox.
150 +- Root `mise run e2e` discovers and runs three extension suites.
151 +- Existing mockup Vitest coverage remains green.
153 +**Phase boundary health:** Browser behavior is covered without changing CI or weakening existing deterministic tests.
155 +**Risks:**
157 +- The mockup tool blocks while waiting for browser feedback, so lifecycle and teardown must be condition-driven rather than timeout-driven.
158 +- Opening a user browser must be suppressed through the real supported extension path during automation.
160 +**Context notes:** Keep the suite tiny and verify the browser-server contract rather than duplicating mockup unit cases.
162 +## Phase 4: Tune Browser E2E And CI Promotion
164 +**Outcome:** Every interactive HTML-serving extension has two-browser smoke coverage, root CI runs the complete ordered gate, and task documentation matches reality.
166 +**Why now:** Tune is the final uncovered HTML server; only after it passes can E2E safely become a required release gate.
168 +**Scope:**
170 +- Add a local `e2e` task and Playwright suite for tune’s browser interface.
171 +- Cover page startup, essential rendering, one primary interaction, and the browser-to-extension result path.
172 +- Make tune automatically participate in the aggregate E2E command.
173 +- Change root `ci` order to lint, test, e2e, then check.
174 +- Update Git-hook and task documentation for the final command surface.
175 +- Verify GitHub Actions needs no extension-specific browser logic beyond `mise run ci`.
177 +**Out of scope:**
179 +- Browser E2E for HTML consumers that do not serve interactive pages.
180 +- Pixel-perfect visual regression infrastructure.
181 +- Benchmark CI gates.
182 +- New browser products beyond Chromium and Firefox.
184 +**Key files/areas likely affected:**
186 +- `extensions/tune/mise.toml`: local E2E ownership.
187 +- `extensions/tune/playwright.config.ts`: browser matrix.
188 +- `extensions/tune/__e2e__/`: real browser smoke path.
189 +- `extensions/tune/index.ts`: minimal deterministic test seam only if required.
190 +- `mise.toml`: final CI ordering.
191 +- `AGENTS.md`, extension READMEs, and task documentation: final commands.
192 +- `.github/workflows/check.yml`: verification, with changes only if browser system dependencies require them.
194 +**Dependencies:**
196 +- Phases 1 through 3.
197 +- Stable aggregate E2E execution on local and GitHub Actions environments.
199 +**Verification:**
201 +- Tune passes in Chromium and Firefox.
202 +- Root `mise run e2e` runs diff-review, UI, mockup, and tune in both browsers.
203 +- Root `mise run test` runs Vitest only.
204 +- Root `mise run bench` remains sequential and excluded from CI.
205 +- `mise run ci` passes in the documented order locally and in GitHub Actions.
206 +- Root and all-task listings satisfy the design acceptance criteria.
208 +**Phase boundary health:** The repository ends with one complete release gate and no partial migration or extension-specific root task leakage.
210 +**Risks:**
212 +- Adding browser installation to CI increases runtime and may require Playwright’s supported Linux dependency installation path.
213 +- Tune’s server is embedded in a large extension file, so any test seam must remain minimal and avoid refactoring unrelated behavior.
215 +**Context notes:** Treat CI promotion as the final step after all four suites are stable; do not hide flaky tests with retries beyond the existing justified policy.