oh-my-opencode 4.16.0 → 4.16.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (160) hide show
  1. package/.agents/skills/codex-qa/SKILL.md +9 -7
  2. package/.agents/skills/codex-qa/references/logging-debug.md +6 -4
  3. package/.agents/skills/opencode-qa/SKILL.md +9 -9
  4. package/.agents/skills/opencode-qa/references/tui-tmux.md +10 -8
  5. package/dist/cli/codex-ulw-loop.d.ts +8 -0
  6. package/dist/cli/get-local-version/types.d.ts +1 -1
  7. package/dist/cli/index.js +260 -207
  8. package/dist/cli-node/index.js +260 -207
  9. package/dist/features/background-agent/parent-wake-dedupe.d.ts +1 -0
  10. package/dist/features/background-agent/parent-wake-flush-runner.d.ts +2 -0
  11. package/dist/features/background-agent/parent-wake-prompt-dispatch.d.ts +1 -0
  12. package/dist/features/builtin-commands/templates/refactor-sections/intro-and-analysis.d.ts +1 -1
  13. package/dist/features/builtin-commands/templates/remove-ai-slops.d.ts +1 -1
  14. package/dist/features/builtin-commands/templates/start-work.d.ts +1 -1
  15. package/dist/features/monitor/process.d.ts +17 -1
  16. package/dist/index.js +1098 -1020
  17. package/dist/skills/frontend/SKILL.md +9 -9
  18. package/dist/skills/frontend/references/design/README.md +7 -3
  19. package/dist/skills/frontend/references/design/_INDEX.md +1 -1
  20. package/dist/skills/frontend/references/design/design-system-architecture.md +24 -2
  21. package/dist/skills/frontend/references/designpowers/README.md +2 -2
  22. package/dist/skills/frontend/references/designpowers/lane-b-execution.md +1 -1
  23. package/dist/skills/review-work/SKILL.md +3 -1
  24. package/dist/skills/start-work/SKILL.md +4 -2
  25. package/dist/skills/ulw-research/SKILL.md +3 -1
  26. package/dist/skills/visual-qa/SKILL.md +13 -17
  27. package/docs/reference/web-terminal-visual-qa.md +39 -45
  28. package/package.json +31 -25
  29. package/packages/omo-codex/plugin/.codex-plugin/plugin.json +1 -1
  30. package/packages/omo-codex/plugin/components/bootstrap/hooks/hooks.json +1 -1
  31. package/packages/omo-codex/plugin/components/bootstrap/package.json +1 -1
  32. package/packages/omo-codex/plugin/components/codegraph/package.json +1 -1
  33. package/packages/omo-codex/plugin/components/comment-checker/hooks/hooks.json +1 -1
  34. package/packages/omo-codex/plugin/components/comment-checker/package.json +1 -1
  35. package/packages/omo-codex/plugin/components/git-bash/hooks/hooks.json +2 -2
  36. package/packages/omo-codex/plugin/components/git-bash/package.json +1 -1
  37. package/packages/omo-codex/plugin/components/lazycodex-executor-verify/hooks/hooks.json +1 -1
  38. package/packages/omo-codex/plugin/components/lazycodex-executor-verify/package.json +1 -1
  39. package/packages/omo-codex/plugin/components/lsp/hooks/hooks.json +2 -2
  40. package/packages/omo-codex/plugin/components/lsp/package.json +1 -1
  41. package/packages/omo-codex/plugin/components/rules/bundled-rules/hephaestus.md +1 -1
  42. package/packages/omo-codex/plugin/components/rules/hooks/hooks.json +4 -4
  43. package/packages/omo-codex/plugin/components/rules/package.json +1 -1
  44. package/packages/omo-codex/plugin/components/start-work-continuation/directive.md +3 -3
  45. package/packages/omo-codex/plugin/components/start-work-continuation/hooks/hooks.json +2 -2
  46. package/packages/omo-codex/plugin/components/start-work-continuation/package.json +1 -1
  47. package/packages/omo-codex/plugin/components/start-work-continuation/test/codex-hook.test.ts +1 -1
  48. package/packages/omo-codex/plugin/components/teammode/AGENTS.md +1 -1
  49. package/packages/omo-codex/plugin/components/teammode/hooks/hooks.json +1 -1
  50. package/packages/omo-codex/plugin/components/teammode/package.json +1 -1
  51. package/packages/omo-codex/plugin/components/teammode/skills/teammode/SKILL.md +3 -3
  52. package/packages/omo-codex/plugin/components/telemetry/hooks/hooks.json +1 -1
  53. package/packages/omo-codex/plugin/components/telemetry/package.json +1 -1
  54. package/packages/omo-codex/plugin/components/ultrawork/directive.md +19 -10
  55. package/packages/omo-codex/plugin/components/ultrawork/hooks/hooks.json +1 -1
  56. package/packages/omo-codex/plugin/components/ultrawork/package.json +1 -1
  57. package/packages/omo-codex/plugin/components/ultrawork/skills/ultrawork/SKILL.md +19 -10
  58. package/packages/omo-codex/plugin/components/ultrawork/skills/ulw-plan/SKILL.md +13 -0
  59. package/packages/omo-codex/plugin/components/ultrawork/skills/ulw-plan/references/full-workflow.md +2 -0
  60. package/packages/omo-codex/plugin/components/ultrawork/test/codex-hook.test.ts +22 -1
  61. package/packages/omo-codex/plugin/components/ulw-loop/CHANGELOG.md +4 -0
  62. package/packages/omo-codex/plugin/components/ulw-loop/directive.md +19 -10
  63. package/packages/omo-codex/plugin/components/ulw-loop/dist/cli-commands.js +15 -2
  64. package/packages/omo-codex/plugin/components/ulw-loop/dist/cli-steering.js +2 -1
  65. package/packages/omo-codex/plugin/components/ulw-loop/dist/cli.js +89 -27
  66. package/packages/omo-codex/plugin/components/ulw-loop/dist/plan-io.d.ts +6 -0
  67. package/packages/omo-codex/plugin/components/ulw-loop/dist/plan-io.js +55 -9
  68. package/packages/omo-codex/plugin/components/ulw-loop/dist/steering-snapshot.d.ts +15 -0
  69. package/packages/omo-codex/plugin/components/ulw-loop/dist/steering-snapshot.js +33 -0
  70. package/packages/omo-codex/plugin/components/ulw-loop/dist/steering-types.d.ts +10 -3
  71. package/packages/omo-codex/plugin/components/ulw-loop/dist/steering.js +15 -11
  72. package/packages/omo-codex/plugin/components/ulw-loop/hooks/hooks.json +2 -2
  73. package/packages/omo-codex/plugin/components/ulw-loop/package.json +1 -1
  74. package/packages/omo-codex/plugin/components/ulw-loop/skills/ulw-loop/SKILL.md +3 -1
  75. package/packages/omo-codex/plugin/components/ulw-loop/skills/ulw-loop/references/full-workflow.md +7 -7
  76. package/packages/omo-codex/plugin/components/ulw-loop/src/cli-commands.ts +17 -2
  77. package/packages/omo-codex/plugin/components/ulw-loop/src/cli-steering.ts +2 -1
  78. package/packages/omo-codex/plugin/components/ulw-loop/src/plan-io.ts +59 -11
  79. package/packages/omo-codex/plugin/components/ulw-loop/src/steering-snapshot.ts +38 -0
  80. package/packages/omo-codex/plugin/components/ulw-loop/src/steering-types.ts +11 -3
  81. package/packages/omo-codex/plugin/components/ulw-loop/src/steering.ts +15 -7
  82. package/packages/omo-codex/plugin/components/ulw-loop/test/cli-create-goals.test.ts +16 -0
  83. package/packages/omo-codex/plugin/components/ulw-loop/test/plan-io.test.ts +260 -2
  84. package/packages/omo-codex/plugin/components/ulw-loop/test/skill-contract.test.ts +1 -1
  85. package/packages/omo-codex/plugin/components/ulw-loop/test/steering-snapshot.test.ts +124 -0
  86. package/packages/omo-codex/plugin/components/ulw-loop/test/steering.test.ts +101 -2
  87. package/packages/omo-codex/plugin/hooks/post-compact-resetting-git-bash-mcp-reminder.json +1 -1
  88. package/packages/omo-codex/plugin/hooks/post-compact-resetting-lsp-diagnostics-cache.json +1 -1
  89. package/packages/omo-codex/plugin/hooks/post-compact-resetting-project-rule-cache.json +1 -1
  90. package/packages/omo-codex/plugin/hooks/post-tool-use-checking-codegraph-init-guidance.json +1 -1
  91. package/packages/omo-codex/plugin/hooks/post-tool-use-checking-comments.json +1 -1
  92. package/packages/omo-codex/plugin/hooks/post-tool-use-checking-lsp-diagnostics.json +1 -1
  93. package/packages/omo-codex/plugin/hooks/post-tool-use-checking-thread-title-hygiene.json +1 -1
  94. package/packages/omo-codex/plugin/hooks/post-tool-use-matching-project-rules.json +1 -1
  95. package/packages/omo-codex/plugin/hooks/pre-tool-use-enforcing-unlimited-goal-budget.json +1 -1
  96. package/packages/omo-codex/plugin/hooks/pre-tool-use-recommending-git-bash-mcp.json +1 -1
  97. package/packages/omo-codex/plugin/hooks/session-start-checking-auto-update.json +1 -1
  98. package/packages/omo-codex/plugin/hooks/session-start-checking-bootstrap-provisioning.json +1 -1
  99. package/packages/omo-codex/plugin/hooks/session-start-checking-codegraph-bootstrap.json +1 -1
  100. package/packages/omo-codex/plugin/hooks/session-start-loading-project-rules.json +1 -1
  101. package/packages/omo-codex/plugin/hooks/session-start-recording-session-telemetry.json +1 -1
  102. package/packages/omo-codex/plugin/hooks/stop-checking-start-work-continuation.json +1 -1
  103. package/packages/omo-codex/plugin/hooks/subagent-stop-checking-start-work-continuation.json +1 -1
  104. package/packages/omo-codex/plugin/hooks/subagent-stop-verifying-lazycodex-executor-evidence.json +1 -1
  105. package/packages/omo-codex/plugin/hooks/user-prompt-submit-checking-ultrawork-trigger.json +1 -1
  106. package/packages/omo-codex/plugin/hooks/user-prompt-submit-checking-ulw-loop-steering.json +1 -1
  107. package/packages/omo-codex/plugin/hooks/user-prompt-submit-loading-project-rules.json +1 -1
  108. package/packages/omo-codex/plugin/package-lock.json +13 -13
  109. package/packages/omo-codex/plugin/package.json +1 -1
  110. package/packages/omo-codex/plugin/scripts/auto-update.mjs +64 -17
  111. package/packages/omo-codex/plugin/scripts/hook-status-message.mjs +10 -6
  112. package/packages/omo-codex/plugin/scripts/migrate-codex-config/multi-agent-v2-guard.mjs +186 -20
  113. package/packages/omo-codex/plugin/scripts/migrate-codex-config/subagent-limit-guard.mjs +51 -3
  114. package/packages/omo-codex/plugin/scripts/migrate-codex-config.mjs +33 -5
  115. package/packages/omo-codex/plugin/scripts/sync-skills.mjs +1 -1
  116. package/packages/omo-codex/plugin/skills/frontend/SKILL.md +9 -9
  117. package/packages/omo-codex/plugin/skills/frontend/references/design/README.md +7 -3
  118. package/packages/omo-codex/plugin/skills/frontend/references/design/_INDEX.md +1 -1
  119. package/packages/omo-codex/plugin/skills/frontend/references/design/design-system-architecture.md +24 -2
  120. package/packages/omo-codex/plugin/skills/frontend/references/designpowers/README.md +2 -2
  121. package/packages/omo-codex/plugin/skills/frontend/references/designpowers/lane-b-execution.md +1 -1
  122. package/packages/omo-codex/plugin/skills/init-deep/SKILL.md +1 -1
  123. package/packages/omo-codex/plugin/skills/refactor/SKILL.md +1 -1
  124. package/packages/omo-codex/plugin/skills/remove-ai-slops/SKILL.md +1 -1
  125. package/packages/omo-codex/plugin/skills/review-work/SKILL.md +1 -1
  126. package/packages/omo-codex/plugin/skills/start-work/SKILL.md +3 -3
  127. package/packages/omo-codex/plugin/skills/teammode/SKILL.md +3 -3
  128. package/packages/omo-codex/plugin/skills/ultrawork/SKILL.md +19 -10
  129. package/packages/omo-codex/plugin/skills/ulw-loop/SKILL.md +3 -1
  130. package/packages/omo-codex/plugin/skills/ulw-loop/references/full-workflow.md +7 -7
  131. package/packages/omo-codex/plugin/skills/ulw-plan/SKILL.md +13 -0
  132. package/packages/omo-codex/plugin/skills/ulw-plan/references/full-workflow.md +2 -0
  133. package/packages/omo-codex/plugin/skills/ulw-research/SKILL.md +1 -1
  134. package/packages/omo-codex/plugin/skills/visual-qa/SKILL.md +14 -18
  135. package/packages/omo-codex/plugin/test/aggregate-hooks.test.mjs +4 -4
  136. package/packages/omo-codex/plugin/test/aggregate-plugin-fixture.mjs +1 -1
  137. package/packages/omo-codex/plugin/test/auto-update.test.mjs +35 -1
  138. package/packages/omo-codex/plugin/test/bootstrap-hooks.test.mjs +1 -1
  139. package/packages/omo-codex/plugin/test/hook-status-message.test.mjs +22 -9
  140. package/packages/omo-codex/plugin/test/migrate-codex-config.test.mjs +275 -19
  141. package/packages/omo-codex/plugin/test/subagent-limit-migration.test.mjs +33 -0
  142. package/packages/omo-codex/plugin/test/sync-hook-status-messages.test.mjs +6 -6
  143. package/packages/omo-codex/plugin/test/sync-skills-orchestration.test.mjs +4 -2
  144. package/packages/omo-codex/plugin/test/ulw-plan-skill-contract.test.mjs +52 -0
  145. package/packages/omo-codex/scripts/install-dist/install-local.mjs +65 -39
  146. package/packages/omo-codex/scripts/install-lazycodex-version-stamp.test.mjs +2 -2
  147. package/packages/shared-skills/skills/frontend/SKILL.md +9 -9
  148. package/packages/shared-skills/skills/frontend/references/design/README.md +7 -3
  149. package/packages/shared-skills/skills/frontend/references/design/_INDEX.md +1 -1
  150. package/packages/shared-skills/skills/frontend/references/design/design-system-architecture.md +24 -2
  151. package/packages/shared-skills/skills/frontend/references/designpowers/README.md +2 -2
  152. package/packages/shared-skills/skills/frontend/references/designpowers/lane-b-execution.md +1 -1
  153. package/packages/shared-skills/skills/review-work/SKILL.md +3 -1
  154. package/packages/shared-skills/skills/start-work/SKILL.md +4 -2
  155. package/packages/shared-skills/skills/ulw-research/SKILL.md +3 -1
  156. package/packages/shared-skills/skills/visual-qa/SKILL.md +13 -17
  157. package/script/qa/strip-ansi.mjs +10 -0
  158. package/script/qa/web-terminal-visual-qa.mjs +112 -195
  159. package/script/qa/xterm-live-terminal.mjs +180 -0
  160. package/script/qa/web-terminal-renderer.mjs +0 -218
@@ -16,7 +16,7 @@ This file is a router, not a rulebook. The rules live in four rulesets under `re
16
16
  | ANY UI implementation, styling, redesign, mockup, or visual decision | `references/design/README.md` FIRST. It enforces two mandatory gates — the Design System Gate (a `DESIGN.md` must exist before any component is written) and the React Dev Tooling Gate (react-grab / react-scan / react-doctor installed by default) — then routes to the taste and brand references below. |
17
17
  | Writing or modifying frontend code, OR auditing performance / SEO / accessibility / quality | ALSO `references/perfection/README.md`. Lighthouse 100 in every category, measured on real Playwright Chromium (never the `lighthouse` CLI), achieved through architecture — never by dropping animations or hiding content. |
18
18
  | Looking up a concrete style, color palette, font pairing, chart type, landing-page structure, or UX guideline — or generating a project design system from keywords | `references/ui-ux-db/README.md`. A searchable CSV database with a CLI; a lookup tool, not a posture. Load on demand; `design` stays the source of truth for taste and the `DESIGN.md` contract. |
19
- | Design operating-layer work: personas, cognitive accessibility, design critique, design debt, handoff, synthetic user testing, or designpowers-style guidance | `references/designpowers/README.md`. This is an internal frontend ruleset, not a separate skill. It enriches `/frontend` routing with design brief, role-reference, accessibility, evidence, and debt language while preserving the `design` and `perfection` gates. |
19
+ | ANY implementation or redesign that creates or updates `DESIGN.md` — plus explicit operating-layer asks (personas, critique, debt, handoff, synthetic user testing) | `references/designpowers/README.md` + `references/designpowers/lane-c-review.md`. An internal frontend ruleset, not a separate skill: lane-c is the Phase Final flatness/critique reviewer, and its accessibility-constraints and accepted-debt language fills the required `DESIGN.md` sections. Load other lanes only when their phase applies. |
20
20
 
21
21
  **For implementation work, design + perfection load together.** A page that hits Lighthouse 100 but looks like AI slop has failed; a page that looks beautiful but ships a 2 MB bundle has failed. Both win or neither does.
22
22
 
@@ -28,15 +28,15 @@ Every implementation must choose one of these branches before UI code changes:
28
28
  - **Static visual reference** (screenshot, generated mockup, Stitch/Imagen output, Figma export, overview, or annotated packet): load `references/design/image-to-code-skill.md` plus the relevant design/perfection files, extract the reference's exact tokens, layout geometry, copy, spacing, states, and responsive intent into `DESIGN.md`, then implement reusable primitives against that contract.
29
29
  - **Live site or URL reference** (the user names a site to clone or gives a URL): load `references/design/clone-from-url.md`. Drive a real browser and extract the runtime truth via `getComputedStyle` — tokens, layout geometry, default/hover/focus/active states, transitions and keyframes, and downloaded assets — into `DESIGN.md`, then clone-code reusable primitives against that contract.
30
30
  Final QA for both runs `/visual-qa` in reference-fidelity mode: compare the actual UI against the reference pixel-by-pixel and verify the code is an extensible design-system implementation, not a screenshot-matched one-off.
31
- 2. **Greenfield or fresh setup:** if the user gave no concrete visual reference, design direction is a research deliverable, not a vibe. Fire every available research lane IN PARALLEL before `DESIGN.md` is written; skip a lane only when its tool or network is genuinely unavailable, and name the skip in `DESIGN.md`:
32
- - **Embedded references:** use `references/design/_INDEX.md` to shortlist 2-3 plausible Layer B references, then deeply load exactly one Layer A style skill and one Layer B brand/design-system reference; use `open-design` only when the curated set has no fit; add `ui-ux-db` lookups for palette/type/domain questions.
33
- - **Lazyweb real-product screens:** run the curl-only recipe in `references/design/lazyweb.md` to see how shipped products in the target domain actually look; harvest layout grammar and component patterns, never pixel copies.
34
- - **Imagen concept drafts:** generate 2-3 imagen concept drafts, each seeded with the loaded Layer A + Layer B tokens (palette, type, material); pick the strongest and treat the chosen draft as the reference-fidelity contract.
35
- Synthesize every lane into `DESIGN.md`. Treat sources as source material, not mood labels: extract tokens, layout grammar, component anatomy, interaction states, motion, and taste decisions, then recombine them into project-specific primitives. Never freestyle past the selected references, never copy logos or brand-specific copy. Define Section 5 primitives and their default/hover/active/focus/disabled/loading/empty/error states before code, and pass each through mobile/tablet/desktop visual QA before product screens.
31
+ 2. **Greenfield or fresh setup:** if the user gave no concrete visual reference, design research is a build step with named deliverables — not exploration to be budgeted. Exploration-stop instincts ("enough exploration", two-wave caps) do not apply here. Fire every research lane IN PARALLEL before `DESIGN.md` is written, and open `DESIGN.md` with a `## 0. Research Log` section recording each lane's deliverable — a lane with no Research Log line did not run. Skip a lane only when its tool or network is genuinely unavailable, and name the skip in `DESIGN.md`:
32
+ - **Embedded references:** use `references/design/_INDEX.md` to shortlist 2-3 plausible Layer B references, then read exactly one Layer A style skill and one Layer B reference in full — every line, no partial reads (they are 200-500 lines; a sliced read produces the flattened token set this gate exists to prevent). Log the shortlist, the pick, and why. Use `open-design` only when the curated set has no fit; add `ui-ux-db` lookups for palette/type/domain questions.
33
+ - **Lazyweb real-product screens:** READ `references/design/lazyweb.md` FIRST and run its recipe verbatim — do not improvise curl calls against lazyweb.com; the recipe mints its own anonymous token. Log the queries run, how many screens you actually VIEWED, and the layout grammar harvested never pixel copies.
34
+ - **Imagen concept drafts:** generate 2-3 imagen concept drafts, each seeded with the loaded Layer A + Layer B tokens (palette, type, material); pick the strongest and treat the chosen draft as the reference-fidelity contract. Log the draft paths and the pick.
35
+ Synthesize every lane into `DESIGN.md`. Treat sources as source material, not mood labels: extract tokens, layout grammar, component anatomy, interaction states, motion, and taste decisions, then recombine them into project-specific primitives. Never freestyle past the selected references, never copy logos or brand-specific copy. Then run the Primitive Showcase Gate (`references/design/README.md` Phase 0) before any product screen.
36
36
  3. **Existing project with `DESIGN.md` or a component system:** read it, follow it, and update it before implementation only when the requested work needs a new token, primitive, state, motion rule, accessibility constraint, accepted debt, or reference-fidelity requirement.
37
37
  4. **Existing project with UI but no `DESIGN.md` and no reusable component layer:** STOP and ask the user one focused question: should you preserve the current look with copy-nearby styling, or extract a real `DESIGN.md` plus reusable components before continuing? Do not silently choose.
38
38
 
39
- When `references/designpowers/README.md` is loaded for implementation, redesign, or design-system work, feed its personas, accessibility, critique, debt, handoff, and role-reference guidance into the branch above. The resulting `DESIGN.md` is the implementation contract: tokens, typography, spacing, primitives, motion, responsive behavior, accessibility constraints, and accepted debt must be named there before code uses them. Verify component primitives, states, and final screens with real visual QA evidence; pass design-system decisions, implementation evidence, and unresolved debt into `/review-work` for significant implementation work.
39
+ For implementation, redesign, or design-system work that creates or updates `DESIGN.md`, `references/designpowers/README.md` + `lane-c-review.md` are part of the default load feed their personas, accessibility, critique, debt, handoff, and role-reference guidance into the branch above. The resulting `DESIGN.md` is the implementation contract: tokens, typography, spacing, primitives, motion, responsive behavior, accessibility constraints, and accepted debt must be named there before code uses them. Verify component primitives, states, and final screens with real visual QA evidence; pass design-system decisions, implementation evidence, and unresolved debt into `/review-work` for significant implementation work.
40
40
 
41
41
  ## Ruleset 1 — design (`references/design/`)
42
42
 
@@ -46,7 +46,7 @@ The reference library has one architecture file, 12 taste skills (Layer A — *h
46
46
 
47
47
  | File | Read when |
48
48
  |---|---|
49
- | `design-system-architecture.md` | The project has no `DESIGN.md` (defines the 7-section structure you must create first), or you are extracting a design system from existing UI code. |
49
+ | `design-system-architecture.md` | The project has no `DESIGN.md` (defines the structure you must create first — 8 sections plus a greenfield-only `## 0. Research Log`), or you are extracting a design system from existing UI code. |
50
50
 
51
51
  ### Layer A — taste skills (pick AT MOST ONE style skill; they encode opposing philosophies)
52
52
 
@@ -102,7 +102,7 @@ Domains: `product` `style` `typography` `color` `landing` `chart` `ux` `react` `
102
102
 
103
103
  ## Ruleset 4 — designpowers (`references/designpowers/`)
104
104
 
105
- `README.md` routes design operating-layer guidance from the pinned `Owl-Listener/designpowers` reference corpus into the existing frontend workflow. Load it when a frontend task needs explicit personas, accessibility and cognitive constraints, design critique, design debt, handoff, synthetic user testing, motion guidance, or role-reference prompts. It does not replace this frontend skill, `/visual-qa`, `/ulw-plan`, `/start-work`, or `/review-work`; it supplies richer design context that must first be distilled into the project `DESIGN.md`, then used as the design-system contract for implementation and verification.
105
+ `README.md` routes design operating-layer guidance from the pinned `Owl-Listener/designpowers` reference corpus into the existing frontend workflow. Load it — together with `lane-c-review.md` — for every implementation or redesign that creates or updates `DESIGN.md`, and additionally when a task needs explicit personas, accessibility and cognitive constraints, design critique, design debt, handoff, synthetic user testing, motion guidance, or role-reference prompts. It does not replace this frontend skill, `/visual-qa`, `/ulw-plan`, `/start-work`, or `/review-work`; it supplies richer design context that must first be distilled into the project `DESIGN.md`, then used as the design-system contract for implementation and verification.
106
106
 
107
107
  ## Quick routes — most common requests
108
108
 
@@ -38,12 +38,12 @@ Before touching any UI code, before routing to any reference, before even thinki
38
38
 
39
39
  1. Read `design-system-architecture.md` — it defines the exact structure.
40
40
  2. Identify the branch: greenfield setup, existing UI with implicit patterns/components, or existing UI with no reusable component layer.
41
- 3. **Greenfield setup:** if the user gave no concrete visual reference, use `_INDEX.md` to shortlist 2-3 plausible Layer B references, then deeply load exactly one Layer A style skill and one Layer B brand/design-system reference; use `open-design` only when the curated set has no fit. Treat those references as source material, not mood labels: extract tokens, layout grammar, component anatomy, interaction states, motion, and taste decisions into `DESIGN.md`, then recombine them into project-specific primitives. Customize for the user's product and content, but do not freestyle past the selected references; never copy logos, trademarked assets, or brand-specific copy.
41
+ 3. **Greenfield setup:** if the user gave no concrete visual reference, use `_INDEX.md` to shortlist 2-3 plausible Layer B references, then read exactly one Layer A style skill and one Layer B brand/design-system reference in full — every line, no partial reads; use `open-design` only when the curated set has no fit. Open `DESIGN.md` with a `## 0. Research Log` recording each research lane's deliverable (embedded-reference shortlist + pick, lazyweb screens viewed, imagen drafts — see the SKILL.md workflow); a lane with no line did not run. Treat those references as source material, not mood labels: extract tokens, layout grammar, component anatomy, interaction states, motion, and taste decisions into `DESIGN.md`, then recombine them into project-specific primitives. Customize for the user's product and content, but do not freestyle past the selected references; never copy logos, trademarked assets, or brand-specific copy.
42
42
  - **Commit a distinctive direction BEFORE extracting tokens.** In 1-2 sentences, name the atmosphere, the signature material, the color story, and the one moment a visitor will remember. For an expressive brief, sketch 2-3 genuinely different directions and pick the boldest one you can defend with the loaded reference; do not average them, because the average IS the generic default this skill exists to beat. A locked, never-revisited one-shot decision is how a page ends up flat.
43
43
  - **The reference's distinctive material MUST survive extraction (expressive briefs).** The common failure is loading a rich reference and then distilling it into a generic dark-SaaS token set. Your `DESIGN.md` must carry the *non-default* decisions forward and name which reference each came from: the actual elevation recipe (the specific layers that make a surface read as glass/glossy, not a single blur), a multi-stop perceptual color ramp (not one brand hex reused at varied opacity), the explicit display/body/mono type choices, and one signature interaction. Self-check before writing code: if your `DESIGN.md` could describe any generic dark SaaS, you flattened the reference — go back and put the specific material in.
44
44
  4. **Existing UI with implicit patterns/components:** extract the colors, typography, spacing, primitives, states, and motion already in use. Write `DESIGN.md` to codify what exists before changing UI code.
45
45
  5. **Existing UI with no reusable component layer:** STOP and ask whether to preserve the current style with copy-nearby edits or extract a `DESIGN.md` plus reusable components first. Do not silently choose the cheaper path or the larger refactor.
46
- 6. **Do not proceed to product screens until `DESIGN.md` exists, Section 5 names the reusable primitives and their states, and each primitive plus required state passes mobile/tablet/desktop visual QA in a component showcase or equivalent state harness.**
46
+ 6. Finish the triage at the Primitive Showcase Gate below.
47
47
 
48
48
  #### If YES design system exists → READ IT, FOLLOW IT
49
49
 
@@ -52,7 +52,11 @@ Before touching any UI code, before routing to any reference, before even thinki
52
52
  3. If you need a token that doesn't exist, **add it to `DESIGN.md` first**, then use it.
53
53
  4. Never introduce raw hex codes, arbitrary px values, or ad-hoc component patterns that bypass the system.
54
54
 
55
- **This gate is non-negotiable. No design system = no UI work. Period.**
55
+ **The Design System Gate is non-negotiable. No design system = no UI work. Period.**
56
+
57
+ ### Primitive Showcase Gate (MANDATORY)
58
+
59
+ **Do not proceed to product screens until `DESIGN.md` exists, Section 5 names the reusable primitives and their states, and each primitive plus required state passes mobile/tablet/desktop visual QA in a component showcase or equivalent state harness.** Skipping this gate ships ad-hoc-styled product screens and re-enters the redesign loop.
56
60
 
57
61
 
58
62
  ## Phase 0.5 — React Dev Tooling Gate (MANDATORY for React projects)
@@ -13,7 +13,7 @@ All reference files live flat in this directory. Three layers:
13
13
 
14
14
  | File | Purpose | Load when |
15
15
  |---|---|---|
16
- | `design-system-architecture.md` | Defines the 7-section `DESIGN.md` structure (atmosphere, color tokens, typography scale, spacing system, components, motion, depth). Creation workflow for new and existing projects. Validation rules and memory management. | Phase 0 fires and no `DESIGN.md` exists in the project. Also load when extracting a design system from existing code. |
16
+ | `design-system-architecture.md` | Defines the `DESIGN.md` structure — 8 sections plus a greenfield-only `## 0. Research Log` (atmosphere, color tokens, typography scale, spacing system, components, motion, depth, accessibility constraints & accepted debt). Creation workflow for new and existing projects. Validation rules and memory management. | Phase 0 fires and no `DESIGN.md` exists in the project. Also load when extracting a design system from existing code. |
17
17
 
18
18
  ---
19
19
 
@@ -16,11 +16,19 @@ Every frontend project MUST have a `DESIGN.md` at its root. This file is the sin
16
16
 
17
17
  ## DESIGN.md Structure
18
18
 
19
- The file has 7 sections. Every section is mandatory. Skip nothing.
19
+ The file has 8 sections plus a greenfield-only `## 0. Research Log`. Every section is mandatory. Skip nothing.
20
20
 
21
21
  ```markdown
22
22
  # [Project Name] Design System
23
23
 
24
+ ## 0. Research Log (greenfield only)
25
+
26
+ One line per research lane, written before the sections below — a lane with no line did not run:
27
+ - Embedded refs: shortlisted [2-3 Layer B candidates] → picked [Layer A] + [Layer B] because [reason]
28
+ - Lazyweb: [N] queries, [M] screens viewed → [layout grammar taken]
29
+ - Imagen drafts: [paths] → picked [draft] as the reference-fidelity contract
30
+ - Skipped lanes: [lane] — [tool/network reason]
31
+
24
32
  ## 1. Atmosphere & Identity
25
33
 
26
34
  One paragraph. What this product FEELS like. Not what it does — how it feels to use.
@@ -165,6 +173,19 @@ If borders:
165
173
 
166
174
  If tonal-shift:
167
175
  Surfaces use progressively lighter/darker shades. No borders, no shadows.
176
+
177
+ ## 8. Accessibility Constraints & Accepted Debt
178
+
179
+ ### Constraints
180
+ - WCAG target: [e.g. 2.2 AA] — contrast floor [4.5:1 body / 3:1 large text], visible focus on every
181
+ interactive element, full keyboard reachability, `prefers-reduced-motion` respected (Section 6).
182
+
183
+ ### Accepted Debt
184
+ | Item | Location | Why accepted | Owner / Exit |
185
+ |------|----------|--------------|--------------|
186
+ | [debt] | [file/screen] | [reason + user sign-off] | [when it gets fixed] |
187
+
188
+ New debt is recorded here at the moment it is accepted — never silently.
168
189
  ```
169
190
 
170
191
  ## Creation Workflow
@@ -173,7 +194,7 @@ Surfaces use progressively lighter/darker shades. No borders, no shadows.
173
194
 
174
195
  1. **Select references before taste** — no visual reference means `_INDEX.md` shortlist of 2-3 Layer B candidates, then exactly one Layer A style skill and one Layer B brand/design-system reference. Use `open-design` only when the curated set has no fit.
175
196
  2. **Assemble from references** — extract tokens, layout grammar, component anatomy, states, motion, and taste decisions, then recombine them into project-specific primitives. Customize for the user's product; never copy logos, trademarked assets, or brand-specific copy.
176
- 3. **Define the system** — atmosphere, palette, typography, spacing, and one depth strategy, grounded in the selected references and product semantics.
197
+ 3. **Define the system** — atmosphere, palette, typography, spacing, and one depth strategy, grounded in the selected references and product semantics. Sanity-check the palette and type pairing with one `ui-ux-db` domain search (CLI in `references/ui-ux-db/README.md`).
177
198
  4. **Document initial primitives** — only components you are about to build, including variants and states.
178
199
  5. **Write it to `DESIGN.md`** at project root.
179
200
  6. **Build a primitive showcase first** — exercise each primitive's default, hover, active, focus, disabled, loading, empty, and error states at mobile/tablet/desktop widths before composing product screens.
@@ -199,6 +220,7 @@ After every component implementation, check:
199
220
  - [ ] Component reused 2+ times? Documented in Section 5.
200
221
  - [ ] Motion follows the timing table. No arbitrary durations.
201
222
  - [ ] Component visual QA passed for each primitive and required state before product screens were composed.
223
+ - [ ] Section 8 accessibility constraints hold for the new component; any new debt is recorded in Section 8, not silently accepted.
202
224
 
203
225
  ## Memory Management
204
226
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  This is an internal frontend ruleset, not a standalone skill. `/frontend` remains the only public activation point for web UI, UX, visual design, accessibility, design QA, and frontend implementation routing.
4
4
 
5
- Load this reference from the frontend router when a task needs design operating-layer guidance: personas, cognitive accessibility, critique, design debt, handoff, synthetic user testing, motion guidance, or designpowers-style role references.
5
+ Load this reference from the frontend router for EVERY implementation or redesign that creates or updates `DESIGN.md`, and whenever a task needs design operating-layer guidance: personas, cognitive accessibility, critique, design debt, handoff, synthetic user testing, motion guidance, or designpowers-style role references.
6
6
 
7
7
  The purpose of this ruleset is to enrich the existing frontend workflow while preserving its gates:
8
8
 
@@ -18,7 +18,7 @@ Read these files before applying designpowers guidance:
18
18
  1. `README.md` - this frontend integration contract.
19
19
  2. `routing.md` - how designpowers context feeds existing frontend, planning, execution, visual QA, and review routes.
20
20
  3. `orchestration.md` - shared state, Direct/Auto prompt semantics, safeguards, and role-reference rules.
21
- 4. Phase lane docs, loaded only when relevant:
21
+ 4. Phase lane docs `lane-c-review.md` loads with this README for every implementation or redesign heading into Phase Final review (it is the flatness/critique reviewer); the other lanes load only when their phase applies:
22
22
  - `lane-a-direction.md` for planning, direction, discovery, personas, taste, and accessibility constraints.
23
23
  - `lane-b-execution.md` for execution, UI build prompts, frontend handoff, and implementation evidence.
24
24
  - `lane-c-review.md` for visual QA, design critique, review gates, and objective evidence before judgment.
@@ -44,7 +44,7 @@ Lane B worker DoneClaims must include:
44
44
 
45
45
  - Exact changed files and the `frontend` references loaded.
46
46
  - The real-surface QA invocation required by `start-work` for the UI surface, with captured artifact path.
47
- - Screenshot, browser, HTTP, or tmux artifacts appropriate to the visible surface.
47
+ - Screenshot, browser, HTTP, or xterm.js web-terminal artifacts appropriate to the visible surface.
48
48
  - Accessibility evidence from the existing OpenAgent frontend path, such as Lighthouse, react-doctor, keyboard checks, or other plan-required checks.
49
49
  - A short design trace: which persona, design principle, token, or state requirement each major UI decision satisfies.
50
50
  - Cleanup receipts for any browser session, server, tmux session, temporary artifact, or process used during QA.
@@ -16,7 +16,9 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
16
16
  | `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
17
17
  | `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent`, `multi_agent_v1.send_input`, `multi_agent_v1.wait_agent`, and `multi_agent_v1.close_agent` |
18
18
 
19
- Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` — pass the matching name as `agent_type` so the child gets that role's model and instructions. On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
19
+ Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` — pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
20
+
21
+ Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. `agent_type` works the same on both surfaces. If a code block below conflicts with this section, this section wins.
20
22
 
21
23
  For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
22
24
 
@@ -20,6 +20,8 @@ Translate any OpenCode-only tool name in an inherited example to its Codex equiv
20
20
 
21
21
  When translating `load_skills=[...]`, name the skills inside the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
22
22
 
23
+ Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. `agent_type` works the same on both surfaces. If a code block below conflicts with this section, this section wins.
24
+
23
25
  ## Codex Subagent Reliability
24
26
 
25
27
  Every `multi_agent_v1.spawn_agent` message is a self-contained executable assignment: `TASK: <imperative assignment>`, then `DELIVERABLE`, `SCOPE`, and `VERIFY`, with role instructions inside `message`. Use `fork_context: false` unless full history is truly required; paste only the context the child needs.
@@ -99,10 +101,10 @@ Each sub-task message must include:
99
101
  4. Automated verification commands to run.
100
102
  5. One Manual-QA channel, named with the exact tool and exact invocation (the literal `curl`, `send-keys`, `browser:control-in-app-browser` action, `page.click`, payload, selectors, and the binary observable that decides PASS/FAIL), not "verify it works". A LIGHT checkbox needs one real-surface proof of its deliverable, and auxiliary surfaces (CLI stdout, DB state diff, parsed config dump) are first-class when the surface is CLI- or data-shaped:
101
103
  - HTTP call: `curl -i` against the live endpoint.
102
- - tmux: a `tmux` session driven with `send-keys`, dumped via `capture-pane`.
104
+ - Terminal / TUI: drive a real pty; `tmux send-keys` is fine for a boot/behavior smoke, but color/layout/CJK evidence goes through the xterm.js web terminal below, NEVER `tmux capture-pane`.
103
105
  - Browser use: in Codex, use `browser:control-in-app-browser` first when available and the scenario does not need an authenticated or persistent user browser profile; otherwise drive the real page with Chrome, or agent-browser (https://github.com/vercel-labs/agent-browser) when Chrome is unavailable.
104
106
  - Computer use: OS-level GUI automation against the running desktop app when the surface is not a page.
105
- - TUI visual evidence: when a tmux/TUI claim needs visual QA or PR proof, run `node script/qa/web-terminal-visual-qa.mjs --from-file <capture.txt> --evidence-dir <dir>` and attach `terminal.png` plus `metadata.json`.
107
+ - TUI visual evidence: when a TUI claim needs visual QA or PR proof, run `node script/qa/web-terminal-visual-qa.mjs --command "<cmd>" --input "{Enter}" --evidence-dir <dir>` (real pty rendered through xterm.js in Chrome) and attach `terminal.png` plus `metadata.json`.
106
108
  6. The adversarial classes that apply to this sub-task (from the 9 ultraqa classes) and how each is probed.
107
109
  7. Required artifact path and cleanup receipt.
108
110
 
@@ -17,7 +17,9 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
17
17
  | `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
18
18
  | `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent`, `multi_agent_v1.send_input`, `multi_agent_v1.wait_agent`, and `multi_agent_v1.close_agent` |
19
19
 
20
- Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` — pass the matching name as `agent_type` so the child gets that role's model and instructions. On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
20
+ Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` — pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
21
+
22
+ Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. `agent_type` works the same on both surfaces. If a code block below conflicts with this section, this section wins.
21
23
 
22
24
  For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
23
25
 
@@ -57,32 +57,28 @@ For reference-fidelity work, repeat the capture and diff for every referenced vi
57
57
 
58
58
  ### TUI
59
59
 
60
- 1. Capture plain text and an ANSI-preserving copy:
61
-
62
- ```
63
- tmux capture-pane -p > capture.txt
64
- tmux capture-pane -e -p > capture-ansi.txt
65
- ```
66
-
67
- 2. When the TUI evidence will be attached to a PR or reviewed visually, render
68
- the capture through the browser helper from the repository root:
60
+ 1. Render the TUI through the REAL xterm.js web terminal and screenshot it -
61
+ NEVER `tmux capture-pane`, which degrades truecolor and misaligns wide (CJK)
62
+ glyphs. Run the command in a real pty and capture the browser render from the
63
+ repository root:
69
64
 
70
65
  ```
71
66
  node script/qa/web-terminal-visual-qa.mjs --title "TUI Visual QA" \
72
- --from-file capture.txt \
67
+ --command "<tui-command>" \
68
+ --input "{ArrowDown}" --input "{Enter}" \
73
69
  --evidence-dir .omo/evidence/<slug>/tui-web-terminal
74
70
  ```
75
71
 
76
- This produces `terminal.png`, `terminal.html`, `terminal.txt`,
77
- `terminal-ansi.txt`, and `metadata.json`. Treat this as the standard TUI visual
78
- artifact pattern for terminal screenshots. If the project is outside this repo,
79
- copy the same pattern: terminal capture -> browser-rendered page -> PNG +
80
- metadata with cleanup receipt.
72
+ Replay a saved raw stream with `--from-file <capture.ansi>` instead of
73
+ `--command`. This produces `terminal.png` (the true-color artifact),
74
+ `terminal.txt`, `terminal-ansi.txt`, and `metadata.json`. Treat this as the
75
+ standard TUI visual artifact pattern. Outside this repo, copy the pattern:
76
+ real pty -> xterm.js in a browser -> PNG + metadata with cleanup receipt.
81
77
 
82
- 3. Run the check with the REAL terminal width and keep the JSON:
78
+ 2. Run the width check on the produced text and keep the JSON:
83
79
 
84
80
  ```
85
- node "$SKILL_DIR/scripts/visual-qa.mjs" tui-check capture.txt --cols <N>
81
+ node "$SKILL_DIR/scripts/visual-qa.mjs" tui-check .omo/evidence/<slug>/tui-web-terminal/terminal.txt --cols <N>
86
82
  ```
87
83
 
88
84
  Key fields: `maxWidth`, `overflowLines[]`, `borderMisaligned`, `wideCharColumns[]`, `hasAnsi`.
@@ -1,81 +1,75 @@
1
1
  # Web Terminal Visual QA
2
2
 
3
- Use `script/qa/web-terminal-visual-qa.mjs` whenever QA needs TUI visual evidence. It turns a terminal or tmux transcript into browser-rendered evidence so PRs can carry the same artifacts as web UI visual QA.
3
+ Use `script/qa/web-terminal-visual-qa.mjs` whenever QA needs TUI visual evidence. It runs the command in a real pty (node-pty), renders it through a **real xterm.js terminal in headless Chrome**, drives scripted interaction through that browser terminal, and screenshots it. The color path is xterm.js, so truecolor, 256-color, box-drawing, and CJK width are faithful. **NEVER use `tmux capture-pane` for color/visual/layout/CJK TUI evidence** - it degrades truecolor and misaligns wide glyphs. tmux stays useful only for boot smoke ("did it render, did it accept a key"), never for the pixel evidence a reviewer trusts.
4
4
 
5
5
  ## Evidence Contract
6
6
 
7
7
  Each run writes these files under the chosen evidence directory:
8
8
 
9
- - `terminal.txt`: redacted plain terminal text for review and assertions.
10
- - `terminal-ansi.txt`: redacted ANSI capture when available.
11
- - `terminal.html`: browser-renderable terminal frame that preserves ANSI colors and SGR styles.
12
- - `terminal.png`: Chrome/Chromium screenshot with the same ANSI styling, unless `--no-browser` is used.
13
- - `metadata.json`: connector, source, output paths, and cleanup receipt.
9
+ - `terminal.png`: the xterm.js screenshot (true color). The primary artifact - cite and attach this.
10
+ - `terminal.txt`: redacted rendered screen text (from the xterm.js buffer) for review and assertions.
11
+ - `terminal-ansi.txt`: the redacted raw pty byte stream, for debugging.
12
+ - `metadata.json`: connector, color path, source, interaction, output paths, and cleanup receipt.
14
13
 
15
- The PR should cite `metadata.json` and attach or link `terminal.png` for OpenCode/Codex TUI proof. For PR-body image hosting, use GitHub user attachments as documented in [docs/reference/github-attachment-upload.md](github-attachment-upload.md); do not commit temporary PNGs, use releases, or use external image hosts.
14
+ The PR should cite `metadata.json` and attach `terminal.png` for OpenCode/Codex TUI proof. For PR-body image hosting, use GitHub user attachments as documented in [docs/reference/github-attachment-upload.md](github-attachment-upload.md); do not commit temporary PNGs, use releases, or use external image hosts.
16
15
 
17
- ## Redaction Contract
18
-
19
- The helper redacts terminal content before writing `terminal.txt`, `terminal-ansi.txt`, `terminal.html`, or `terminal.png`. Built-in rules cover common authorization headers, token/password/key assignments, GitHub tokens, and OpenAI-style `sk-...` tokens.
20
-
21
- Add exact local values with `--redact <literal>` and project-specific patterns with `--redact-regex <expr>`:
16
+ ## Live Capture (default)
22
17
 
23
18
  ```bash
24
19
  node script/qa/web-terminal-visual-qa.mjs \
25
20
  --title "Codex TUI QA" \
26
- --from-file .omo/evidence/run/capture.txt \
27
- --evidence-dir .omo/evidence/run/codex-web-terminal \
28
- --redact "$LOCAL_TOKEN" \
29
- --redact-regex 'session_[A-Za-z0-9]+'
21
+ --command "codex --help" \
22
+ --source-label "codex help smoke" \
23
+ --cwd "$PWD" \
24
+ --evidence-dir .omo/evidence/run/codex-web-terminal
30
25
  ```
31
26
 
32
- Custom `--redact-regex` rules replace the full regex match, even when the expression contains capture groups. Prefix-preserving redaction is reserved for the built-in authorization and key-assignment rules.
27
+ Drive an interactive TUI by scripting keystrokes with repeatable `--input`, applied in order through the browser terminal. Literal text is typed; `{Enter}`, `{Tab}`, `{Escape}`, `{ArrowDown}`, `{Ctrl+C}` and similar tokens are pressed as keys:
28
+
29
+ ```bash
30
+ node script/qa/web-terminal-visual-qa.mjs --title "menu nav" --command "my-tui" \
31
+ --input "{ArrowDown}" --input "{ArrowDown}" --input "{Enter}" \
32
+ --dwell-ms 2000 --evidence-dir .omo/evidence/run/menu
33
+ ```
33
34
 
34
- Do not rely on screenshots to hide secrets. If a capture might include cookies, auth headers, raw env dumps, launchd environments, provider keys, or browser storage, redact first or summarize the run instead of storing the transcript.
35
+ ## Redaction Contract
35
36
 
36
- ## Replay An Existing Capture
37
+ The helper redacts terminal content before writing `terminal.txt`, `terminal-ansi.txt`, and - when a rule matches - re-renders the masked stream so `terminal.png` never shows the secret. Built-in rules cover common authorization headers, token/password/key assignments, GitHub tokens, and OpenAI-style `sk-...` tokens.
37
38
 
38
- Use this path for maximum OS compatibility, including Windows hosts without tmux:
39
+ Add exact local values with `--redact <literal>` and project-specific patterns with `--redact-regex <expr>`:
39
40
 
40
41
  ```bash
41
42
  node script/qa/web-terminal-visual-qa.mjs \
42
- --title "Codex TUI QA" \
43
- --from-file .omo/evidence/run/capture.txt \
44
- --evidence-dir .omo/evidence/run/codex-web-terminal
43
+ --title "Codex TUI QA" --command "codex --help" \
44
+ --evidence-dir .omo/evidence/run/codex-web-terminal \
45
+ --redact "$LOCAL_TOKEN" \
46
+ --redact-regex 'session_[A-Za-z0-9]+'
45
47
  ```
46
48
 
47
- Long terminal lines wrap by default for readable PR evidence. Pass `--no-wrap` only when horizontal scrolling is part of the behavior under test.
49
+ The raw --command string is process data and may contain inline secrets, so it is never persisted to metadata; use `--source-label` for a reviewer-safe description. Do not rely on screenshots to hide secrets: if a capture might include cookies, auth headers, raw env dumps, or provider keys, redact first or summarize the run instead of storing the transcript.
48
50
 
49
- ## Run Through The PTY Connector
51
+ ## Replay And Chrome-less Fallback
50
52
 
51
- Use this when `tmux` is available on macOS/Linux or a Windows environment that provides tmux, such as Git Bash/MSYS2:
53
+ Render an existing raw terminal byte stream through xterm.js:
52
54
 
53
55
  ```bash
54
- node script/qa/web-terminal-visual-qa.mjs \
55
- --title "OpenCode TUI QA" \
56
- --command "opencode --help" \
57
- --source-label "opencode help smoke" \
58
- --cwd "$PWD" \
59
- --evidence-dir .omo/evidence/run/opencode-web-terminal
56
+ node script/qa/web-terminal-visual-qa.mjs --title "Replay" \
57
+ --from-file .omo/evidence/run/capture.ansi --evidence-dir .omo/evidence/run/replay
60
58
  ```
61
59
 
62
- `--command` starts a short-lived tmux-backed PTY connector, captures the pane, renders the web evidence, then records a `tmux kill-session` cleanup receipt in `metadata.json`. The raw --command string is process data and may contain inline secrets, so it is never persisted to metadata; use `--source-label` for a reviewer-safe description.
60
+ `--no-browser` skips xterm.js/Chrome and writes only the text and raw-stream artifacts (no PNG). Use it on hosts without Chrome; it is text-only evidence, not color/visual proof.
63
61
 
64
62
  ## OS Notes
65
63
 
66
- - macOS/Linux: prefer `--command` when `tmux` is installed; otherwise replay a saved pane with `--from-file`.
67
- - Windows: prefer `--from-file` for native shells. Git Bash/MSYS2 environments with tmux may use `--command`.
68
- - Windows-native ConPTY live capture should plug into this same artifact and metadata contract before becoming required.
64
+ - The harness needs `node-pty` (real pty) plus a system Chrome/Chromium (`--chrome-bin` or `CHROME_BIN` to override). `node-pty` ships prebuilds for macOS and Windows; Linux builds from source on install.
65
+ - Windows: node-pty uses ConPTY, so live capture works natively - no tmux, no Git Bash PTY shim required.
69
66
 
70
67
  ## QA Guidance
71
68
 
72
- For OpenCode/Codex QA, pair the harness-specific smoke with this helper:
73
-
74
- 1. Drive the TUI through the normal QA skill or script.
75
- 2. Capture the pane or use the helper's `--command` mode.
76
- 3. Store the output under `.omo/evidence/<YYYYMMDD>-<slug>/`.
77
- 4. Review `terminal.txt`, `terminal-ansi.txt`, and `metadata.json` for accidental secrets before citing them.
78
- 5. Include `terminal.png`, `terminal.txt`, and `metadata.json` in the evidence summary.
79
- 6. Verify cleanup receipts: no leftover tmux sessions, PIDs, ports, or temp state.
69
+ 1. Drive the TUI with `--command` (plus `--input` for interactive flows), or replay a saved stream with `--from-file`.
70
+ 2. Store the output under `.omo/evidence/<YYYYMMDD>-<slug>/`.
71
+ 3. Review `terminal.txt` and `terminal-ansi.txt` for accidental secrets before citing them.
72
+ 4. Include `terminal.png`, `terminal.txt`, and `metadata.json` in the evidence summary.
73
+ 5. Verify the cleanup receipt in `metadata.json`: no leftover pty, Chrome, PIDs, ports, or temp state.
80
74
 
81
- Tests alone are not TUI visual QA. The passing artifact is the rendered terminal evidence plus a binary observation, such as expected text present, no overflow, and no obvious border misalignment.
75
+ Tests alone are not TUI visual QA. The passing artifact is the xterm.js-rendered `terminal.png` plus a binary observation - expected text present, colors correct, no overflow, no border or CJK-width misalignment.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "oh-my-opencode",
3
- "version": "4.16.0",
3
+ "version": "4.16.2",
4
4
  "description": "The Best AI Agent Harness - Batteries-Included OpenCode Plugin with Multi-Model Orchestration, Parallel Background Agents, and Crafted LSP/AST Tools",
5
5
  "main": "./dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -46,10 +46,11 @@
46
46
  "dist",
47
47
  "bin",
48
48
  "postinstall.mjs",
49
+ "script/qa/strip-ansi.mjs",
49
50
  "script/qa/web-terminal-redaction.d.mts",
50
51
  "script/qa/web-terminal-redaction.mjs",
51
- "script/qa/web-terminal-renderer.mjs",
52
52
  "script/qa/web-terminal-visual-qa.mjs",
53
+ "script/qa/xterm-live-terminal.mjs",
53
54
  "docs/reference/github-attachment-upload.md",
54
55
  "docs/reference/web-terminal-visual-qa.md",
55
56
  ".opencode/command",
@@ -115,6 +116,7 @@
115
116
  "build:all": "bun run build && bun run build:binaries",
116
117
  "build:binaries": "bun run script/build-binaries.ts",
117
118
  "build:schema": "bun run script/build-schema.ts",
119
+ "build:omo-schema": "bun run script/build-omo-schema.ts",
118
120
  "build:model-capabilities": "bun run script/build-model-capabilities.ts",
119
121
  "clean": "rm -rf dist",
120
122
  "prepack": "bun run build:materialize-frontend",
@@ -171,51 +173,55 @@
171
173
  "zod": "^4.4.3"
172
174
  },
173
175
  "devDependencies": {
174
- "@oh-my-opencode/git-bash-mcp": "workspace:*",
175
- "@oh-my-opencode/lsp-core": "workspace:*",
176
- "@oh-my-opencode/mcp-stdio-core": "workspace:*",
177
- "@oh-my-opencode/mcp-client-core": "workspace:*",
178
176
  "@oh-my-opencode/agents-md-core": "workspace:*",
179
177
  "@oh-my-opencode/boulder-state": "workspace:*",
180
178
  "@oh-my-opencode/claude-code-compat-core": "workspace:*",
181
- "@oh-my-opencode/skills-loader-core": "workspace:*",
182
179
  "@oh-my-opencode/comment-checker-core": "workspace:*",
183
180
  "@oh-my-opencode/delegate-core": "workspace:*",
181
+ "@oh-my-opencode/git-bash-mcp": "workspace:*",
184
182
  "@oh-my-opencode/hashline-core": "workspace:*",
185
- "@oh-my-opencode/tmux-core": "workspace:*",
186
- "@oh-my-opencode/team-core": "workspace:*",
187
- "@oh-my-opencode/openclaw-core": "workspace:*",
183
+ "@oh-my-opencode/lsp-core": "workspace:*",
184
+ "@oh-my-opencode/mcp-client-core": "workspace:*",
185
+ "@oh-my-opencode/mcp-stdio-core": "workspace:*",
188
186
  "@oh-my-opencode/model-core": "workspace:*",
189
- "@oh-my-opencode/omo-config-core": "workspace:*",
190
187
  "@oh-my-opencode/omo-codex": "workspace:*",
188
+ "@oh-my-opencode/omo-config-core": "workspace:*",
191
189
  "@oh-my-opencode/omo-senpi": "workspace:*",
192
- "@oh-my-opencode/senpi-task": "workspace:*",
190
+ "@oh-my-opencode/openclaw-core": "workspace:*",
193
191
  "@oh-my-opencode/pi-goal": "workspace:*",
194
192
  "@oh-my-opencode/pi-webfetch": "workspace:*",
195
193
  "@oh-my-opencode/prompts-core": "workspace:*",
196
194
  "@oh-my-opencode/rules-engine": "workspace:*",
195
+ "@oh-my-opencode/senpi-task": "workspace:*",
197
196
  "@oh-my-opencode/shared-skills": "workspace:*",
197
+ "@oh-my-opencode/skills-loader-core": "workspace:*",
198
+ "@oh-my-opencode/team-core": "workspace:*",
198
199
  "@oh-my-opencode/telemetry-core": "workspace:*",
200
+ "@oh-my-opencode/tmux-core": "workspace:*",
199
201
  "@oh-my-opencode/utils": "workspace:*",
200
- "@typescript/native-preview": "7.0.0-dev.20260518.1",
201
202
  "@types/js-yaml": "^4.0.9",
202
203
  "@types/picomatch": "^4.0.3",
204
+ "@typescript/native-preview": "7.0.0-dev.20260518.1",
205
+ "@xterm/addon-unicode11": "^0.9.0",
206
+ "@xterm/xterm": "^6.0.0",
203
207
  "bun-types": "1.3.14",
208
+ "node-pty": "^1.1.0",
209
+ "puppeteer-core": "^25.3.0",
204
210
  "typescript": "^6.0.3"
205
211
  },
206
212
  "optionalDependencies": {
207
- "oh-my-opencode-darwin-arm64": "4.16.0",
208
- "oh-my-opencode-darwin-x64": "4.16.0",
209
- "oh-my-opencode-darwin-x64-baseline": "4.16.0",
210
- "oh-my-opencode-linux-arm64": "4.16.0",
211
- "oh-my-opencode-linux-arm64-musl": "4.16.0",
212
- "oh-my-opencode-linux-x64": "4.16.0",
213
- "oh-my-opencode-linux-x64-baseline": "4.16.0",
214
- "oh-my-opencode-linux-x64-musl": "4.16.0",
215
- "oh-my-opencode-linux-x64-musl-baseline": "4.16.0",
216
- "oh-my-opencode-windows-arm64": "4.16.0",
217
- "oh-my-opencode-windows-x64": "4.16.0",
218
- "oh-my-opencode-windows-x64-baseline": "4.16.0"
213
+ "oh-my-opencode-darwin-arm64": "4.16.2",
214
+ "oh-my-opencode-darwin-x64": "4.16.2",
215
+ "oh-my-opencode-darwin-x64-baseline": "4.16.2",
216
+ "oh-my-opencode-linux-arm64": "4.16.2",
217
+ "oh-my-opencode-linux-arm64-musl": "4.16.2",
218
+ "oh-my-opencode-linux-x64": "4.16.2",
219
+ "oh-my-opencode-linux-x64-baseline": "4.16.2",
220
+ "oh-my-opencode-linux-x64-musl": "4.16.2",
221
+ "oh-my-opencode-linux-x64-musl-baseline": "4.16.2",
222
+ "oh-my-opencode-windows-arm64": "4.16.2",
223
+ "oh-my-opencode-windows-x64": "4.16.2",
224
+ "oh-my-opencode-windows-x64-baseline": "4.16.2"
219
225
  },
220
226
  "overrides": {
221
227
  "@earendil-works/pi-agent-core": "0.80.3",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "omo",
3
- "version": "4.16.0",
3
+ "version": "4.16.2",
4
4
  "description": "One Codex plugin namespace for Yeongyu's local Codex components.",
5
5
  "author": {
6
6
  "name": "Yeongyu Kim",
@@ -8,7 +8,7 @@
8
8
  "command": "node \"${PLUGIN_ROOT}/components/bootstrap/dist/cli.js\" hook session-start",
9
9
  "commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\bootstrap.ps1\"",
10
10
  "timeout": 30,
11
- "statusMessage": "(OmO) Checking Bootstrap Provisioning"
11
+ "statusMessage": "(OmO 4.16.2) Checking Bootstrap Provisioning"
12
12
  }
13
13
  ]
14
14
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sisyphuslabs/codex-bootstrap",
3
- "version": "4.16.0",
3
+ "version": "4.16.2",
4
4
  "description": "Codex SessionStart bootstrap component that provisions LazyCodex runtime dependencies from a detached worker.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sisyphuslabs/codex-codegraph",
3
- "version": "4.16.0",
3
+ "version": "4.16.2",
4
4
  "description": "Codex plugin MCP wrapper for CodeGraph.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -8,7 +8,7 @@
8
8
  "type": "command",
9
9
  "command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook post-tool-use",
10
10
  "timeout": 30,
11
- "statusMessage": "(OmO) Checking Comments"
11
+ "statusMessage": "(OmO 4.16.2) Checking Comments"
12
12
  }
13
13
  ]
14
14
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@code-yeongyu/codex-comment-checker",
3
- "version": "4.16.0",
3
+ "version": "4.16.2",
4
4
  "description": "Codex plugin that runs comment-checker after edit-like PostToolUse hooks.",
5
5
  "type": "module",
6
6
  "packageManager": "npm@11.12.1",