oh-my-codex 0.16.2 → 0.16.4

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 (340) hide show
  1. package/Cargo.lock +5 -5
  2. package/Cargo.toml +1 -1
  3. package/README.md +3 -3
  4. package/dist/catalog/__tests__/plugin-bundle-ssot.test.js +9 -0
  5. package/dist/catalog/__tests__/plugin-bundle-ssot.test.js.map +1 -1
  6. package/dist/cli/__tests__/cleanup.test.js +27 -0
  7. package/dist/cli/__tests__/cleanup.test.js.map +1 -1
  8. package/dist/cli/__tests__/codex-plugin-layout.test.js +7 -5
  9. package/dist/cli/__tests__/codex-plugin-layout.test.js.map +1 -1
  10. package/dist/cli/__tests__/doctor-warning-copy.test.js +137 -6
  11. package/dist/cli/__tests__/doctor-warning-copy.test.js.map +1 -1
  12. package/dist/cli/__tests__/index.test.js +303 -4
  13. package/dist/cli/__tests__/index.test.js.map +1 -1
  14. package/dist/cli/__tests__/launch-fallback.test.js +58 -0
  15. package/dist/cli/__tests__/launch-fallback.test.js.map +1 -1
  16. package/dist/cli/__tests__/ralph-goal-mode-contract.test.js +2 -0
  17. package/dist/cli/__tests__/ralph-goal-mode-contract.test.js.map +1 -1
  18. package/dist/cli/__tests__/ralph.test.js +48 -0
  19. package/dist/cli/__tests__/ralph.test.js.map +1 -1
  20. package/dist/cli/__tests__/setup-hooks-shared-ownership.test.js +8 -0
  21. package/dist/cli/__tests__/setup-hooks-shared-ownership.test.js.map +1 -1
  22. package/dist/cli/__tests__/setup-install-mode.test.js +350 -27
  23. package/dist/cli/__tests__/setup-install-mode.test.js.map +1 -1
  24. package/dist/cli/__tests__/setup-refresh.test.js +85 -3
  25. package/dist/cli/__tests__/setup-refresh.test.js.map +1 -1
  26. package/dist/cli/__tests__/setup-scope.test.js +1 -1
  27. package/dist/cli/__tests__/setup-scope.test.js.map +1 -1
  28. package/dist/cli/__tests__/setup-skills-overwrite.test.js +2 -1
  29. package/dist/cli/__tests__/setup-skills-overwrite.test.js.map +1 -1
  30. package/dist/cli/__tests__/team.test.js +269 -0
  31. package/dist/cli/__tests__/team.test.js.map +1 -1
  32. package/dist/cli/__tests__/ultragoal.test.js +69 -0
  33. package/dist/cli/__tests__/ultragoal.test.js.map +1 -1
  34. package/dist/cli/__tests__/uninstall.test.js +90 -6
  35. package/dist/cli/__tests__/uninstall.test.js.map +1 -1
  36. package/dist/cli/__tests__/update.test.js +109 -19
  37. package/dist/cli/__tests__/update.test.js.map +1 -1
  38. package/dist/cli/cleanup.d.ts.map +1 -1
  39. package/dist/cli/cleanup.js +8 -4
  40. package/dist/cli/cleanup.js.map +1 -1
  41. package/dist/cli/codex-feature-probe.d.ts +9 -0
  42. package/dist/cli/codex-feature-probe.d.ts.map +1 -0
  43. package/dist/cli/codex-feature-probe.js +28 -0
  44. package/dist/cli/codex-feature-probe.js.map +1 -0
  45. package/dist/cli/doctor.d.ts +1 -0
  46. package/dist/cli/doctor.d.ts.map +1 -1
  47. package/dist/cli/doctor.js +168 -16
  48. package/dist/cli/doctor.js.map +1 -1
  49. package/dist/cli/index.d.ts +9 -2
  50. package/dist/cli/index.d.ts.map +1 -1
  51. package/dist/cli/index.js +168 -20
  52. package/dist/cli/index.js.map +1 -1
  53. package/dist/cli/mcp-parity.js +8 -8
  54. package/dist/cli/mcp-parity.js.map +1 -1
  55. package/dist/cli/plugin-marketplace.d.ts +3 -0
  56. package/dist/cli/plugin-marketplace.d.ts.map +1 -1
  57. package/dist/cli/plugin-marketplace.js +88 -0
  58. package/dist/cli/plugin-marketplace.js.map +1 -1
  59. package/dist/cli/ralph.d.ts.map +1 -1
  60. package/dist/cli/ralph.js +21 -0
  61. package/dist/cli/ralph.js.map +1 -1
  62. package/dist/cli/setup-preferences.d.ts +4 -0
  63. package/dist/cli/setup-preferences.d.ts.map +1 -1
  64. package/dist/cli/setup-preferences.js +7 -0
  65. package/dist/cli/setup-preferences.js.map +1 -1
  66. package/dist/cli/setup.d.ts +5 -3
  67. package/dist/cli/setup.d.ts.map +1 -1
  68. package/dist/cli/setup.js +177 -43
  69. package/dist/cli/setup.js.map +1 -1
  70. package/dist/cli/team.d.ts.map +1 -1
  71. package/dist/cli/team.js +54 -15
  72. package/dist/cli/team.js.map +1 -1
  73. package/dist/cli/ultragoal.d.ts +1 -1
  74. package/dist/cli/ultragoal.d.ts.map +1 -1
  75. package/dist/cli/ultragoal.js +64 -5
  76. package/dist/cli/ultragoal.js.map +1 -1
  77. package/dist/cli/uninstall.d.ts +2 -0
  78. package/dist/cli/uninstall.d.ts.map +1 -1
  79. package/dist/cli/uninstall.js +76 -5
  80. package/dist/cli/uninstall.js.map +1 -1
  81. package/dist/cli/update.d.ts +10 -2
  82. package/dist/cli/update.d.ts.map +1 -1
  83. package/dist/cli/update.js +99 -5
  84. package/dist/cli/update.js.map +1 -1
  85. package/dist/config/__tests__/codex-feature-flags.test.d.ts +2 -0
  86. package/dist/config/__tests__/codex-feature-flags.test.d.ts.map +1 -0
  87. package/dist/config/__tests__/codex-feature-flags.test.js +35 -0
  88. package/dist/config/__tests__/codex-feature-flags.test.js.map +1 -0
  89. package/dist/config/__tests__/codex-hooks.test.js +188 -4
  90. package/dist/config/__tests__/codex-hooks.test.js.map +1 -1
  91. package/dist/config/__tests__/generator-idempotent.test.js +129 -10
  92. package/dist/config/__tests__/generator-idempotent.test.js.map +1 -1
  93. package/dist/config/__tests__/generator-notify.test.js +148 -7
  94. package/dist/config/__tests__/generator-notify.test.js.map +1 -1
  95. package/dist/config/__tests__/wiki-config-contract.test.js +6 -3
  96. package/dist/config/__tests__/wiki-config-contract.test.js.map +1 -1
  97. package/dist/config/codex-feature-flags.d.ts +21 -0
  98. package/dist/config/codex-feature-flags.d.ts.map +1 -0
  99. package/dist/config/codex-feature-flags.js +56 -0
  100. package/dist/config/codex-feature-flags.js.map +1 -0
  101. package/dist/config/codex-hooks.d.ts +40 -4
  102. package/dist/config/codex-hooks.d.ts.map +1 -1
  103. package/dist/config/codex-hooks.js +204 -18
  104. package/dist/config/codex-hooks.js.map +1 -1
  105. package/dist/config/generator.d.ts +19 -1
  106. package/dist/config/generator.d.ts.map +1 -1
  107. package/dist/config/generator.js +319 -83
  108. package/dist/config/generator.js.map +1 -1
  109. package/dist/config/omx-first-party-mcp.d.ts +3 -1
  110. package/dist/config/omx-first-party-mcp.d.ts.map +1 -1
  111. package/dist/config/omx-first-party-mcp.js +2 -2
  112. package/dist/config/omx-first-party-mcp.js.map +1 -1
  113. package/dist/hooks/__tests__/keyword-detector.test.js +92 -2
  114. package/dist/hooks/__tests__/keyword-detector.test.js.map +1 -1
  115. package/dist/hooks/__tests__/notify-fallback-watcher.test.js +29 -1
  116. package/dist/hooks/__tests__/notify-fallback-watcher.test.js.map +1 -1
  117. package/dist/hooks/__tests__/notify-hook-auto-nudge.test.js +10 -0
  118. package/dist/hooks/__tests__/notify-hook-auto-nudge.test.js.map +1 -1
  119. package/dist/hooks/__tests__/notify-hook-cross-worktree-heartbeat.test.js +1 -0
  120. package/dist/hooks/__tests__/notify-hook-cross-worktree-heartbeat.test.js.map +1 -1
  121. package/dist/hooks/__tests__/notify-hook-non-omx-guard.test.d.ts +2 -0
  122. package/dist/hooks/__tests__/notify-hook-non-omx-guard.test.d.ts.map +1 -0
  123. package/dist/hooks/__tests__/notify-hook-non-omx-guard.test.js +176 -0
  124. package/dist/hooks/__tests__/notify-hook-non-omx-guard.test.js.map +1 -0
  125. package/dist/hooks/__tests__/notify-hook-ralph-resume.test.js +148 -0
  126. package/dist/hooks/__tests__/notify-hook-ralph-resume.test.js.map +1 -1
  127. package/dist/hooks/__tests__/notify-hook-session-scope.test.js +3 -0
  128. package/dist/hooks/__tests__/notify-hook-session-scope.test.js.map +1 -1
  129. package/dist/hooks/__tests__/skill-catalog-hygiene.test.d.ts +2 -0
  130. package/dist/hooks/__tests__/skill-catalog-hygiene.test.d.ts.map +1 -0
  131. package/dist/hooks/__tests__/skill-catalog-hygiene.test.js +84 -0
  132. package/dist/hooks/__tests__/skill-catalog-hygiene.test.js.map +1 -0
  133. package/dist/hooks/__tests__/wiki-docs-contract.test.js +1 -2
  134. package/dist/hooks/__tests__/wiki-docs-contract.test.js.map +1 -1
  135. package/dist/hooks/agents-overlay.js +2 -2
  136. package/dist/hooks/agents-overlay.js.map +1 -1
  137. package/dist/hooks/keyword-detector.d.ts +1 -0
  138. package/dist/hooks/keyword-detector.d.ts.map +1 -1
  139. package/dist/hooks/keyword-detector.js +7 -5
  140. package/dist/hooks/keyword-detector.js.map +1 -1
  141. package/dist/hud/__tests__/state.test.js +164 -0
  142. package/dist/hud/__tests__/state.test.js.map +1 -1
  143. package/dist/hud/state.d.ts.map +1 -1
  144. package/dist/hud/state.js +4 -5
  145. package/dist/hud/state.js.map +1 -1
  146. package/dist/mcp/__tests__/state-paths.test.js +61 -0
  147. package/dist/mcp/__tests__/state-paths.test.js.map +1 -1
  148. package/dist/mcp/__tests__/state-server.test.js +166 -0
  149. package/dist/mcp/__tests__/state-server.test.js.map +1 -1
  150. package/dist/mcp/state-paths.d.ts.map +1 -1
  151. package/dist/mcp/state-paths.js +23 -2
  152. package/dist/mcp/state-paths.js.map +1 -1
  153. package/dist/modes/__tests__/base-session-scope.test.js +22 -0
  154. package/dist/modes/__tests__/base-session-scope.test.js.map +1 -1
  155. package/dist/modes/__tests__/base-tmux-pane.test.js +57 -26
  156. package/dist/modes/__tests__/base-tmux-pane.test.js.map +1 -1
  157. package/dist/modes/base.d.ts.map +1 -1
  158. package/dist/modes/base.js +5 -0
  159. package/dist/modes/base.js.map +1 -1
  160. package/dist/planning/__tests__/approved-execution-lifecycle-matrix.test.d.ts +2 -0
  161. package/dist/planning/__tests__/approved-execution-lifecycle-matrix.test.d.ts.map +1 -0
  162. package/dist/planning/__tests__/approved-execution-lifecycle-matrix.test.js +316 -0
  163. package/dist/planning/__tests__/approved-execution-lifecycle-matrix.test.js.map +1 -0
  164. package/dist/planning/__tests__/approved-launch-hint-lineage-matrix.test.d.ts +2 -0
  165. package/dist/planning/__tests__/approved-launch-hint-lineage-matrix.test.d.ts.map +1 -0
  166. package/dist/planning/__tests__/approved-launch-hint-lineage-matrix.test.js +481 -0
  167. package/dist/planning/__tests__/approved-launch-hint-lineage-matrix.test.js.map +1 -0
  168. package/dist/planning/__tests__/artifacts.test.js +597 -4
  169. package/dist/planning/__tests__/artifacts.test.js.map +1 -1
  170. package/dist/planning/__tests__/context-pack-status.test.js +524 -0
  171. package/dist/planning/__tests__/context-pack-status.test.js.map +1 -1
  172. package/dist/planning/__tests__/markdown-structure.test.d.ts +2 -0
  173. package/dist/planning/__tests__/markdown-structure.test.d.ts.map +1 -0
  174. package/dist/planning/__tests__/markdown-structure.test.js +459 -0
  175. package/dist/planning/__tests__/markdown-structure.test.js.map +1 -0
  176. package/dist/planning/__tests__/ready-context-pack-role-refs.test.d.ts +2 -0
  177. package/dist/planning/__tests__/ready-context-pack-role-refs.test.d.ts.map +1 -0
  178. package/dist/planning/__tests__/ready-context-pack-role-refs.test.js +612 -0
  179. package/dist/planning/__tests__/ready-context-pack-role-refs.test.js.map +1 -0
  180. package/dist/planning/artifacts.d.ts +7 -2
  181. package/dist/planning/artifacts.d.ts.map +1 -1
  182. package/dist/planning/artifacts.js +279 -26
  183. package/dist/planning/artifacts.js.map +1 -1
  184. package/dist/planning/context-pack-status.d.ts +31 -0
  185. package/dist/planning/context-pack-status.d.ts.map +1 -1
  186. package/dist/planning/context-pack-status.js +291 -25
  187. package/dist/planning/context-pack-status.js.map +1 -1
  188. package/dist/planning/markdown-structure.d.ts +20 -0
  189. package/dist/planning/markdown-structure.d.ts.map +1 -0
  190. package/dist/planning/markdown-structure.js +137 -0
  191. package/dist/planning/markdown-structure.js.map +1 -0
  192. package/dist/ralph/__tests__/completion-audit.test.d.ts +2 -0
  193. package/dist/ralph/__tests__/completion-audit.test.d.ts.map +1 -0
  194. package/dist/ralph/__tests__/completion-audit.test.js +121 -0
  195. package/dist/ralph/__tests__/completion-audit.test.js.map +1 -0
  196. package/dist/ralph/completion-audit.d.ts +8 -0
  197. package/dist/ralph/completion-audit.d.ts.map +1 -0
  198. package/dist/ralph/completion-audit.js +99 -0
  199. package/dist/ralph/completion-audit.js.map +1 -0
  200. package/dist/ralph/persistence.d.ts +1 -1
  201. package/dist/ralph/persistence.d.ts.map +1 -1
  202. package/dist/ralph/persistence.js +8 -2
  203. package/dist/ralph/persistence.js.map +1 -1
  204. package/dist/scripts/__tests__/codex-native-hook.test.js +359 -24
  205. package/dist/scripts/__tests__/codex-native-hook.test.js.map +1 -1
  206. package/dist/scripts/__tests__/notify-dispatcher.test.d.ts +2 -0
  207. package/dist/scripts/__tests__/notify-dispatcher.test.d.ts.map +1 -0
  208. package/dist/scripts/__tests__/notify-dispatcher.test.js +126 -0
  209. package/dist/scripts/__tests__/notify-dispatcher.test.js.map +1 -0
  210. package/dist/scripts/codex-native-hook.d.ts.map +1 -1
  211. package/dist/scripts/codex-native-hook.js +142 -76
  212. package/dist/scripts/codex-native-hook.js.map +1 -1
  213. package/dist/scripts/codex-native-pre-post.d.ts.map +1 -1
  214. package/dist/scripts/codex-native-pre-post.js +4 -2
  215. package/dist/scripts/codex-native-pre-post.js.map +1 -1
  216. package/dist/scripts/notify-dispatcher.d.ts +7 -0
  217. package/dist/scripts/notify-dispatcher.d.ts.map +1 -0
  218. package/dist/scripts/notify-dispatcher.js +87 -0
  219. package/dist/scripts/notify-dispatcher.js.map +1 -0
  220. package/dist/scripts/notify-fallback-watcher.js +4 -0
  221. package/dist/scripts/notify-fallback-watcher.js.map +1 -1
  222. package/dist/scripts/notify-hook/ralph-session-resume.d.ts.map +1 -1
  223. package/dist/scripts/notify-hook/ralph-session-resume.js +96 -8
  224. package/dist/scripts/notify-hook/ralph-session-resume.js.map +1 -1
  225. package/dist/scripts/notify-hook/state-io.d.ts.map +1 -1
  226. package/dist/scripts/notify-hook/state-io.js +6 -2
  227. package/dist/scripts/notify-hook/state-io.js.map +1 -1
  228. package/dist/scripts/notify-hook/visual-verdict.js +3 -3
  229. package/dist/scripts/notify-hook/visual-verdict.js.map +1 -1
  230. package/dist/scripts/notify-hook.js +127 -1
  231. package/dist/scripts/notify-hook.js.map +1 -1
  232. package/dist/state/__tests__/workflow-transition.test.js +102 -27
  233. package/dist/state/__tests__/workflow-transition.test.js.map +1 -1
  234. package/dist/state/operations.d.ts.map +1 -1
  235. package/dist/state/operations.js +9 -3
  236. package/dist/state/operations.js.map +1 -1
  237. package/dist/state/skill-active.d.ts +7 -0
  238. package/dist/state/skill-active.d.ts.map +1 -1
  239. package/dist/state/skill-active.js +25 -8
  240. package/dist/state/skill-active.js.map +1 -1
  241. package/dist/state/workflow-transition-reconcile.d.ts +1 -0
  242. package/dist/state/workflow-transition-reconcile.d.ts.map +1 -1
  243. package/dist/state/workflow-transition-reconcile.js +22 -15
  244. package/dist/state/workflow-transition-reconcile.js.map +1 -1
  245. package/dist/state/workflow-transition.js +3 -3
  246. package/dist/state/workflow-transition.js.map +1 -1
  247. package/dist/team/__tests__/approved-execution.test.js +84 -1
  248. package/dist/team/__tests__/approved-execution.test.js.map +1 -1
  249. package/dist/team/__tests__/runtime.test.js +178 -19
  250. package/dist/team/__tests__/runtime.test.js.map +1 -1
  251. package/dist/team/__tests__/scaling.test.js +497 -2
  252. package/dist/team/__tests__/scaling.test.js.map +1 -1
  253. package/dist/team/__tests__/state-root.test.js +1 -1
  254. package/dist/team/__tests__/state-root.test.js.map +1 -1
  255. package/dist/team/__tests__/worker-bootstrap.test.js +45 -0
  256. package/dist/team/__tests__/worker-bootstrap.test.js.map +1 -1
  257. package/dist/team/approved-execution.d.ts +1 -0
  258. package/dist/team/approved-execution.d.ts.map +1 -1
  259. package/dist/team/approved-execution.js +53 -0
  260. package/dist/team/approved-execution.js.map +1 -1
  261. package/dist/team/delivery-log.d.ts.map +1 -1
  262. package/dist/team/delivery-log.js +8 -1
  263. package/dist/team/delivery-log.js.map +1 -1
  264. package/dist/team/runtime.d.ts.map +1 -1
  265. package/dist/team/runtime.js +104 -18
  266. package/dist/team/runtime.js.map +1 -1
  267. package/dist/team/scaling.d.ts.map +1 -1
  268. package/dist/team/scaling.js +43 -0
  269. package/dist/team/scaling.js.map +1 -1
  270. package/dist/team/state/mailbox.d.ts +1 -0
  271. package/dist/team/state/mailbox.d.ts.map +1 -1
  272. package/dist/team/state/mailbox.js +10 -1
  273. package/dist/team/state/mailbox.js.map +1 -1
  274. package/dist/team/state-root.d.ts.map +1 -1
  275. package/dist/team/state-root.js +5 -1
  276. package/dist/team/state-root.js.map +1 -1
  277. package/dist/team/state.d.ts.map +1 -1
  278. package/dist/team/state.js +3 -7
  279. package/dist/team/state.js.map +1 -1
  280. package/dist/team/worker-bootstrap.d.ts +7 -2
  281. package/dist/team/worker-bootstrap.d.ts.map +1 -1
  282. package/dist/team/worker-bootstrap.js +17 -4
  283. package/dist/team/worker-bootstrap.js.map +1 -1
  284. package/dist/ultragoal/__tests__/artifacts.test.js +124 -1
  285. package/dist/ultragoal/__tests__/artifacts.test.js.map +1 -1
  286. package/dist/ultragoal/__tests__/docs-contract.test.js +21 -0
  287. package/dist/ultragoal/__tests__/docs-contract.test.js.map +1 -1
  288. package/dist/ultragoal/artifacts.d.ts +44 -2
  289. package/dist/ultragoal/artifacts.d.ts.map +1 -1
  290. package/dist/ultragoal/artifacts.js +197 -13
  291. package/dist/ultragoal/artifacts.js.map +1 -1
  292. package/dist/wiki/lifecycle.js +1 -1
  293. package/dist/wiki/lifecycle.js.map +1 -1
  294. package/package.json +1 -1
  295. package/plugins/oh-my-codex/.codex-plugin/plugin.json +1 -1
  296. package/plugins/oh-my-codex/.mcp.json +5 -5
  297. package/plugins/oh-my-codex/skills/analyze/SKILL.md +0 -2
  298. package/plugins/oh-my-codex/skills/autopilot/SKILL.md +2 -2
  299. package/plugins/oh-my-codex/skills/code-review/SKILL.md +1 -3
  300. package/plugins/oh-my-codex/skills/deep-interview/SKILL.md +5 -7
  301. package/plugins/oh-my-codex/skills/doctor/SKILL.md +2 -2
  302. package/plugins/oh-my-codex/skills/omx-setup/SKILL.md +3 -3
  303. package/plugins/oh-my-codex/skills/pipeline/SKILL.md +3 -3
  304. package/plugins/oh-my-codex/skills/plan/SKILL.md +3 -6
  305. package/plugins/oh-my-codex/skills/ralph/SKILL.md +9 -10
  306. package/plugins/oh-my-codex/skills/ultragoal/SKILL.md +36 -3
  307. package/plugins/oh-my-codex/skills/ultraqa/SKILL.md +21 -24
  308. package/plugins/oh-my-codex/skills/ultrawork/SKILL.md +8 -8
  309. package/plugins/oh-my-codex/skills/wiki/SKILL.md +13 -13
  310. package/skills/analyze/SKILL.md +0 -2
  311. package/skills/ask-claude/SKILL.md +5 -3
  312. package/skills/ask-gemini/SKILL.md +5 -3
  313. package/skills/autopilot/SKILL.md +2 -2
  314. package/skills/code-review/SKILL.md +1 -3
  315. package/skills/deep-interview/SKILL.md +5 -7
  316. package/skills/doctor/SKILL.md +2 -2
  317. package/skills/ecomode/SKILL.md +105 -1
  318. package/skills/frontend-ui-ux/SKILL.md +4 -26
  319. package/skills/git-master/SKILL.md +2 -4
  320. package/skills/omx-setup/SKILL.md +3 -3
  321. package/skills/pipeline/SKILL.md +3 -3
  322. package/skills/plan/SKILL.md +3 -6
  323. package/skills/ralph/SKILL.md +9 -10
  324. package/skills/swarm/SKILL.md +5 -3
  325. package/skills/tdd/SKILL.md +95 -1
  326. package/skills/ultragoal/SKILL.md +36 -3
  327. package/skills/ultraqa/SKILL.md +21 -24
  328. package/skills/ultrawork/SKILL.md +8 -8
  329. package/skills/web-clone/SKILL.md +348 -1
  330. package/skills/wiki/SKILL.md +13 -13
  331. package/src/scripts/__tests__/codex-native-hook.test.ts +389 -24
  332. package/src/scripts/__tests__/notify-dispatcher.test.ts +153 -0
  333. package/src/scripts/codex-native-hook.ts +168 -64
  334. package/src/scripts/codex-native-pre-post.ts +4 -1
  335. package/src/scripts/notify-dispatcher.ts +113 -0
  336. package/src/scripts/notify-fallback-watcher.ts +6 -2
  337. package/src/scripts/notify-hook/ralph-session-resume.ts +117 -8
  338. package/src/scripts/notify-hook/state-io.ts +4 -2
  339. package/src/scripts/notify-hook/visual-verdict.ts +3 -3
  340. package/src/scripts/notify-hook.ts +119 -1
@@ -5,17 +5,15 @@ description: QA cycling workflow - test, verify, fix, repeat until goal met
5
5
 
6
6
  # UltraQA Skill
7
7
 
8
- [ULTRAQA ACTIVATED - AUTONOMOUS QA CYCLING]
9
-
10
- ## Overview
11
-
12
- ## GPT-5.5 Guidance Alignment
8
+ ## Operating Contract
13
9
 
14
- Use the shared workflow guidance pattern: outcome-first framing, concise visible updates for multi-step QA, local overrides for the active workflow branch, validation proportional to risk, explicit stop rules, and automatic continuation for safe reversible steps. Ask only for material, destructive, credentialed, external-production, or preference-dependent branches.
10
+ - Use outcome-first framing with concise, evidence-dense progress and completion reporting.
11
+ - Treat newer user updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints.
12
+ - If the user says `continue`, advance the current verified next step instead of restarting discovery.
15
13
 
16
- You are now in **ULTRAQA** mode - an autonomous QA cycling workflow that runs until your quality goal is met.
14
+ [ULTRAQA ACTIVATED - AUTONOMOUS QA CYCLING]
17
15
 
18
- **Cycle**: qa-tester → architect verification → fix → repeat
16
+ ## Overview
19
17
 
20
18
  ## Goal Parsing
21
19
 
@@ -43,10 +41,10 @@ If no structured goal provided, interpret the argument as a custom goal.
43
41
  - `--custom`: Run appropriate command and check for pattern
44
42
  - `--interactive`: Use qa-tester for interactive CLI/service testing:
45
43
  ```
46
- delegate(role="qa-tester", tier="STANDARD", task="TEST:
44
+ Use `/prompts:qa-tester` with:
47
45
  Goal: [describe what to verify]
48
46
  Service: [how to start]
49
- Test cases: [specific scenarios to verify]")
47
+ Test cases: [specific scenarios to verify]
50
48
  ```
51
49
 
52
50
  2. **CHECK RESULT**: Did the goal pass?
@@ -55,18 +53,18 @@ If no structured goal provided, interpret the argument as a custom goal.
55
53
 
56
54
  3. **ARCHITECT DIAGNOSIS**: Spawn architect to analyze failure
57
55
  ```
58
- delegate(role="architect", tier="THOROUGH", task="DIAGNOSE FAILURE:
56
+ Use `/prompts:architect` with:
59
57
  Goal: [goal type]
60
58
  Output: [test/build output]
61
- Provide root cause and specific fix recommendations.")
59
+ Provide root cause and specific fix recommendations.
62
60
  ```
63
61
 
64
62
  4. **FIX ISSUES**: Apply architect's recommendations
65
63
  ```
66
- delegate(role="executor", tier="STANDARD", task="FIX:
64
+ Use `/prompts:executor` with:
67
65
  Issue: [architect diagnosis]
68
66
  Files: [affected files]
69
- Apply the fix precisely as recommended.")
67
+ Apply the fix precisely as recommended.
70
68
  ```
71
69
 
72
70
  5. **REPEAT**: Go back to step 1
@@ -95,20 +93,19 @@ Output progress each cycle:
95
93
 
96
94
  ## State Tracking
97
95
 
98
- Use `omx_state` MCP tools for UltraQA lifecycle state.
96
+ Use the CLI-first state surface (`omx state ... --json`) for UltraQA lifecycle state. If explicit MCP compatibility tools are already available, equivalent `omx_state` calls are optional compatibility, not the default.
99
97
 
100
98
  - **On start**:
101
- `state_write({mode: "ultraqa", active: true, current_phase: "qa", iteration: 1, started_at: "<now>"})`
99
+ `omx state write --input '{"mode":"ultraqa","active":true,"current_phase":"qa","iteration":1,"started_at":"<now>"}' --json`
102
100
  - **On each cycle**:
103
- `state_write({mode: "ultraqa", current_phase: "qa", iteration: <cycle>})`
101
+ `omx state write --input '{"mode":"ultraqa","current_phase":"qa","iteration":<cycle>}' --json`
104
102
  - **On diagnose/fix transitions**:
105
- `state_write({mode: "ultraqa", current_phase: "diagnose"})`
106
- `state_write({mode: "ultraqa", current_phase: "fix"})`
103
+ `omx state write --input '{"mode":"ultraqa","current_phase":"diagnose"}' --json`
104
+ `omx state write --input '{"mode":"ultraqa","current_phase":"fix"}' --json`
107
105
  - **On completion**:
108
- `state_write({mode: "ultraqa", active: false, current_phase: "complete", completed_at: "<now>"})`
106
+ `omx state write --input '{"mode":"ultraqa","active":false,"current_phase":"complete","completed_at":"<now>"}' --json`
109
107
  - **For resume detection**:
110
- `state_read({mode: "ultraqa"})`
111
-
108
+ `omx state read --input '{"mode":"ultraqa"}' --json`
112
109
 
113
110
  ## Scenario Examples
114
111
 
@@ -134,9 +131,9 @@ User can cancel with `/cancel` which clears the state file.
134
131
 
135
132
  When goal is met OR max cycles reached OR exiting early, run `$cancel` or call:
136
133
 
137
- `state_clear({mode: "ultraqa"})`
134
+ `omx state clear --input '{"mode":"ultraqa"}' --json`
138
135
 
139
- Use MCP state cleanup rather than deleting files directly.
136
+ Use CLI state cleanup rather than deleting files directly.
140
137
 
141
138
  ---
142
139
 
@@ -81,16 +81,16 @@ Sequential task execution wastes time when tasks are independent. Ultrawork keep
81
81
 
82
82
  ## State Management
83
83
 
84
- Use `omx_state` MCP tools for ultrawork lifecycle state.
84
+ Use the CLI-first state surface (`omx state ... --json`) for ultrawork lifecycle state. If explicit MCP compatibility tools are already available, equivalent `omx_state` calls are optional compatibility, not the default.
85
85
 
86
86
  - **On start**:
87
- `state_write({mode: "ultrawork", active: true, reinforcement_count: 1, started_at: "<now>"})`
87
+ `omx state write --input '{"mode":"ultrawork","active":true,"reinforcement_count":1,"started_at":"<now>"}' --json`
88
88
  - **On each reinforcement/loop step**:
89
- `state_write({mode: "ultrawork", reinforcement_count: <current>})`
89
+ `omx state write --input '{"mode":"ultrawork","reinforcement_count":<current>}' --json`
90
90
  - **On completion**:
91
- `state_write({mode: "ultrawork", active: false})`
91
+ `omx state write --input '{"mode":"ultrawork","active":false}' --json`
92
92
  - **On cancellation/cleanup**:
93
- run `$cancel` (which should call `state_clear(mode="ultrawork")`)
93
+ run `$cancel` (which should call `omx state clear --input '{"mode":"ultrawork"}' --json`)
94
94
 
95
95
  <Examples>
96
96
  <Good>
@@ -105,7 +105,7 @@ Direct-tool lane:
105
105
  - update `skills/ultrawork/SKILL.md`
106
106
 
107
107
  Background evidence lane:
108
- - delegate(role="test-engineer", tier="STANDARD", task="Map which hook tests cover ultrawork activation messaging", model="...")
108
+ - use /prompts:test-engineer for this scoped task
109
109
  ```
110
110
  Why good: Context is grounded first, acceptance criteria are explicit, and the direct-tool lane runs alongside a bounded evidence lane.
111
111
  </Good>
@@ -122,8 +122,8 @@ Why good: Shared-file work stays local; independent evidence work fans out.
122
122
  <Bad>
123
123
  Parallelizing before the task is grounded:
124
124
  ```
125
- delegate(role="executor", tier="STANDARD", task="Implement whatever seems necessary", model="...")
126
- delegate(role="test-engineer", tier="STANDARD", task="Figure out how to test it later", model="...")
125
+ use /prompts:executor for this scoped task
126
+ use /prompts:test-engineer for this scoped task
127
127
  ```
128
128
  Why bad: No context snapshot, no pass/fail target, and delegation starts before the work is shaped.
129
129
  </Bad>
@@ -7,4 +7,351 @@ description: Web Clone deprecated shim
7
7
 
8
8
  Hard-deprecated. Do not invoke or route this skill. Use `$visual-ralph` directly for live-URL visual implementation and visual QA workflows.
9
9
 
10
- Task: {{ARGUMENTS}}
10
+ <Do_Not_Use_When>
11
+ - User only has screenshot references without a live URL — use `$visual-verdict` directly
12
+ - User wants to modify, redesign, or "improve" the site — use standard implementation flow
13
+ - Target requires authentication, payment flows, or backend API parity — out of scope for v1
14
+ - Multi-page / multi-route deep cloning — v1 handles single-page scope only
15
+ </Do_Not_Use_When>
16
+
17
+ <Scope_Limits>
18
+ **v1 scope**: Single page clone of the provided URL.
19
+
20
+ Included:
21
+ - Layout structure (header, nav, content areas, sidebar, footer)
22
+ - Typography (font families, sizes, weights, line heights)
23
+ - Colors, spacing, borders, border-radius
24
+ - Core interactions: navigation links, buttons, form elements, dropdowns, modals, toggles
25
+ - Responsive hints from the extracted layout (flexbox/grid patterns)
26
+
27
+ Excluded:
28
+ - Backend API integration or data fetching
29
+ - Authentication flows or protected content
30
+ - Dynamic/personalized content (user-specific data)
31
+ - Multi-page crawling or route graph cloning
32
+ - Third-party widget functionality (maps, embeds, chat widgets)
33
+ - Image/asset replication (use placeholders for external images)
34
+
35
+ **Legal notice**: Only clone sites you own or have explicit permission to replicate. Respect copyright and trademarks.
36
+ </Scope_Limits>
37
+
38
+ <Prerequisites>
39
+ Playwright MCP server must be available for browser automation.
40
+
41
+ 2. If no browser tools are found, instruct the user:
42
+ ```
43
+ Playwright MCP is required. Configure it:
44
+ codex mcp add playwright npx "@playwright/mcp@latest"
45
+ ```
46
+ 3. Required tools: `browser_navigate`, `browser_snapshot`, `browser_take_screenshot`, `browser_evaluate`, `browser_wait_for`. Optional: `browser_click`, `browser_network_requests`.
47
+ </Prerequisites>
48
+
49
+ <Inputs>
50
+ - `target_url` (required): The URL to clone
51
+ - `output_dir` (optional, default: current working directory): Where to generate the clone project
52
+ - `tech_stack` (optional, inferred from project context): HTML/CSS/JS, React, Vue, Svelte, etc.
53
+ </Inputs>
54
+
55
+ <Tool_Usage>
56
+ - If no browser tools are found, stop immediately and instruct the user to configure Playwright MCP.
57
+ - Use `browser_snapshot` (accessibility tree) for structural understanding — it is far more token-efficient than screenshots.
58
+ - Use `browser_take_screenshot` only when visual verification is needed (Pass 1 baseline, Pass 4 comparison).
59
+ - Use `browser_evaluate` for DOM/style extraction — pass the scripts from this skill EXACTLY as written (do not modify them).
60
+ - If running within ralph, use `state_write` / `state_read` for web-clone state persistence between iterations.
61
+ - Skip Codex consultation for straightforward extraction; use it only if verification repeatedly fails on the same issue.
62
+ </Tool_Usage>
63
+
64
+ <State_Management>
65
+ Persist extraction and progress data so the pipeline can resume if interrupted.
66
+
67
+ - **After Pass 1 completes**: Write extraction summary to `.omx/state/{scope}/web-clone-extraction.json` containing:
68
+ - `target_url`, `extracted_at` timestamp
69
+ - `screenshot_path` (path to `target-full.png`)
70
+ - `landmark_count` (number of nav, main, footer, form elements)
71
+ - `interactive_count` (number of detected interactive elements)
72
+ - `extraction_size_kb` (approximate size of DOM extraction data)
73
+ - **After each Pass 4 verification**: Append the composite verdict to `.omx/state/{scope}/web-clone-verdicts.json`.
74
+ - **When running within ralph**: Also persist the `visual` portion of the composite verdict to `.omx/state/{scope}/ralph-progress.json` for ralph compatibility, mapping `visual.score` → top-level `score` and `visual.verdict` → top-level `verdict`.
75
+ - **On completion or failure**: Write final status with `completed_at` or `failed_at` timestamp.
76
+ </State_Management>
77
+
78
+ <Context_Budget>
79
+ Pass 1 extraction can produce very large data. Apply these limits proactively:
80
+
81
+ - **DOM tree**: If the serialized JSON exceeds ~30KB, reduce `depth` parameter from 8 to 4 and re-extract. Focus on top-level structure.
82
+ - **Accessibility snapshot**: If it exceeds ~20KB, this is normal for complex pages. Summarize key landmarks rather than keeping the full tree.
83
+ - **Interactive elements**: Cap at 50 elements. If more exist, keep only visible ones (`isVisible: true`).
84
+ - **Total extraction context**: Aim for under 60KB combined. If exceeded, prioritize: screenshot > accessibility snapshot > interactive elements > DOM styles.
85
+ - **Image tokens**: Full-page screenshots are expensive. Take one baseline in Pass 1 and one comparison in Pass 4. Do not take screenshots between iterations unless debugging a specific region.
86
+ </Context_Budget>
87
+
88
+ <Steps>
89
+
90
+ ## Pass 1 — Extract
91
+
92
+ Capture the target page's structure, styles, interactions, and visual baseline.
93
+
94
+ 1. **Navigate**: `browser_navigate` to `target_url`.
95
+ 2. **Wait for render**: `browser_wait_for` with appropriate condition (network idle or timeout of 5s) to ensure full render including lazy-loaded content.
96
+ 3. **Accessibility snapshot**: `browser_snapshot` — captures the semantic tree (roles, names, values, interactive states). This is your primary structural reference.
97
+ 4. **Full-page screenshot**: `browser_take_screenshot` with `fullPage: true` — save as reference baseline `target-full.png`.
98
+ 5. **DOM + computed styles**: `browser_evaluate` with the following script. **COPY THIS SCRIPT EXACTLY — do not modify it**:
99
+ ```javascript
100
+ (() => {
101
+ const walk = (el, depth = 0) => {
102
+ if (depth > 8 || !el.tagName) return null;
103
+ const cs = window.getComputedStyle(el);
104
+ return {
105
+ tag: el.tagName.toLowerCase(),
106
+ id: el.id || undefined,
107
+ classes: [...el.classList].slice(0, 5),
108
+ styles: {
109
+ display: cs.display, position: cs.position,
110
+ width: cs.width, height: cs.height,
111
+ padding: cs.padding, margin: cs.margin,
112
+ fontSize: cs.fontSize, fontFamily: cs.fontFamily,
113
+ fontWeight: cs.fontWeight, lineHeight: cs.lineHeight,
114
+ color: cs.color, backgroundColor: cs.backgroundColor,
115
+ border: cs.border, borderRadius: cs.borderRadius,
116
+ flexDirection: cs.flexDirection, justifyContent: cs.justifyContent,
117
+ alignItems: cs.alignItems, gap: cs.gap,
118
+ gridTemplateColumns: cs.gridTemplateColumns,
119
+ },
120
+ text: el.childNodes.length === 1 && el.childNodes[0].nodeType === 3
121
+ ? el.textContent?.trim().slice(0, 100) : undefined,
122
+ children: [...el.children].map(c => walk(c, depth + 1)).filter(Boolean),
123
+ };
124
+ };
125
+ return walk(document.body);
126
+ })()
127
+ ```
128
+ 6. **Interactive elements**: `browser_evaluate` to catalog all interactable elements. **COPY THIS SCRIPT EXACTLY — do not modify it**:
129
+ ```javascript
130
+ (() => {
131
+ const results = [];
132
+ document.querySelectorAll(
133
+ 'button, a[href], input, select, textarea, [role="button"], ' +
134
+ '[onclick], [aria-haspopup], [aria-expanded], details, dialog'
135
+ ).forEach(el => {
136
+ results.push({
137
+ tag: el.tagName.toLowerCase(),
138
+ type: el.type || el.getAttribute('role') || 'interactive',
139
+ text: (el.textContent || '').trim().slice(0, 80),
140
+ href: el.href || undefined,
141
+ ariaLabel: el.getAttribute('aria-label') || undefined,
142
+ isVisible: el.offsetParent !== null,
143
+ });
144
+ });
145
+ return results;
146
+ })()
147
+ ```
148
+ 7. **Network patterns** (optional): `browser_network_requests` — note XHR/fetch calls for reference. Do not attempt to replicate backends.
149
+
150
+ Keep all extraction results in working memory for Pass 2.
151
+
152
+ ## Pass 2 — Build Plan
153
+
154
+ Analyze extraction results and decompose into a component plan.
155
+
156
+ 1. **Identify page regions**: From DOM tree + accessibility snapshot, identify major sections:
157
+ - Navigation bar / header
158
+ - Hero / banner section
159
+ - Main content area(s)
160
+ - Sidebar (if present)
161
+ - Footer
162
+ - Overlay elements (modals, drawers)
163
+
164
+ 2. **Map components**: For each region, define:
165
+ - Component name and responsibility
166
+ - Key style properties (from computed styles)
167
+ - Content summary (headings, text, images)
168
+ - Child components if nested
169
+
170
+ 3. **Create interaction map**: From interactive elements list:
171
+ - Navigation links → anchor tags with `href`
172
+ - Form elements → proper `<form>` with inputs, labels, validation
173
+ - Buttons → click handlers (toggle, submit, navigate)
174
+ - Dropdowns/modals → show/hide toggle with transitions
175
+ - Accordions/tabs → state-based visibility
176
+
177
+ 4. **Extract design tokens**: Identify recurring values:
178
+ - Color palette (primary, secondary, background, text colors)
179
+ - Font stack (families, size scale, weight scale)
180
+ - Spacing scale (padding/margin patterns)
181
+ - Border radius values
182
+
183
+ 5. **Define file structure**:
184
+ ```
185
+ {output_dir}/
186
+ ├── index.html (or App.tsx / App.vue)
187
+ ├── styles/
188
+ │ ├── globals.css (reset + tokens)
189
+ │ └── components.css (or scoped styles)
190
+ ├── scripts/
191
+ │ └── interactions.js (toggle, modal, dropdown logic)
192
+ └── assets/ (placeholder images)
193
+ ```
194
+ Adapt to `tech_stack` if specified (React components, Vue SFCs, etc.).
195
+
196
+ ## Pass 3 — Generate Clone
197
+
198
+ Implement the clone from the plan. Work component-by-component.
199
+
200
+ 1. **Scaffold**: Create the directory structure and base files.
201
+ 2. **Design tokens first**: Implement CSS custom properties or Tailwind config from extracted tokens.
202
+ 3. **Layout shell**: Build the page-level layout matching the original's flexbox/grid structure.
203
+ 4. **Components**: Implement each region top-down:
204
+ - Match DOM structure from extraction (semantic tags, landmark roles)
205
+ - Apply computed styles — prioritize layout properties, then typography, then decorative
206
+ - Use actual extracted text content; use placeholder `<img>` for external images
207
+ 5. **Interactions**: Wire up detected behaviors:
208
+ - Navigation: working `<a>` tags (to `#` anchors or stubs for v1)
209
+ - Forms: proper structure with `<label>`, input types, placeholder text
210
+ - Toggles: JavaScript for dropdowns, modals, accordions
211
+ - Hover/focus states: CSS transitions matching original behavior
212
+ 6. **Responsive**: If the original uses responsive breakpoints (detectable from media queries in computed styles or from viewport behavior), add basic responsive rules.
213
+
214
+ ## Pass 4 — Verify
215
+
216
+ Compare the clone against the original across three dimensions.
217
+
218
+ 1. **Serve the clone**: Start a local server for the generated project:
219
+ ```bash
220
+ npx serve {output_dir} -l 3456 --no-clipboard
221
+ ```
222
+ If `npx serve` is unavailable, fall back to: `python3 -m http.server 3456 -d {output_dir}`.
223
+ The clone will be accessible at `http://localhost:3456`.
224
+ 2. **Visual verification**:
225
+ - Navigate to the clone with Playwright: `browser_navigate` to clone URL.
226
+ - Take full-page screenshot of clone.
227
+ - Run `$visual-verdict` with: `reference_images=["target-full.png"]`, `generated_screenshot="clone-full.png"`, `category_hint="web-clone"`.
228
+ - The visual portion of the verdict feeds directly into the composite verdict below.
229
+ - Visual pass threshold: **score >= 85**.
230
+
231
+ 3. **Structural verification**: Compare landmark counts:
232
+ - Count `<nav>`, `<main>`, `<footer>`, `<form>`, `<button>`, `<a>` in both original and clone.
233
+ - Structure passes when all major landmarks exist (missing landmarks = fail).
234
+
235
+ 4. **Functional spot-check**: Test 2–3 detected interactions via Playwright:
236
+ - Click a navigation link → verify URL change or scroll behavior
237
+ - Toggle a dropdown/modal → verify visibility change
238
+ - Interact with a form field → verify it accepts input
239
+ - Use `browser_click` and `browser_snapshot` to verify state changes.
240
+
241
+ 5. **Emit composite verdict**:
242
+
243
+ ```json
244
+ {
245
+ "visual": {
246
+ "score": 82,
247
+ "verdict": "revise",
248
+ "category_match": true,
249
+ "differences": ["Header spacing tighter than original"],
250
+ "suggestions": ["Increase nav gap to 24px"]
251
+ },
252
+ "functional": {
253
+ "tested": 3,
254
+ "passed": 2,
255
+ "failures": ["Dropdown does not open on click"]
256
+ },
257
+ "structure": {
258
+ "landmark_match": true,
259
+ "missing": [],
260
+ "extra": []
261
+ },
262
+ "overall_verdict": "revise",
263
+ "priority_fixes": [
264
+ "Fix dropdown toggle interaction",
265
+ "Increase header nav spacing"
266
+ ]
267
+ }
268
+ ```
269
+
270
+ ## Pass 5 — Iterate
271
+
272
+ Fix highest-impact issues and re-verify.
273
+
274
+ 1. **Prioritize fixes** by impact: layout > interactions > spacing > typography > colors.
275
+ 2. **Apply targeted edits**: Fix only the issues listed in `priority_fixes`. Do not refactor working code.
276
+ 3. **Re-verify**: Repeat Pass 4.
277
+ 4. **Loop**: Continue until `overall_verdict` is `pass` OR max **5 iterations** reached.
278
+ 5. **Final report**: Summarize what was successfully cloned, any remaining differences, and elements that could not be replicated.
279
+
280
+ </Steps>
281
+
282
+ <Output_Contract>
283
+ After each verification pass, emit a **composite web-clone verdict** JSON:
284
+
285
+ ```json
286
+ {
287
+ "visual": {
288
+ "score": 0,
289
+ "verdict": "revise",
290
+ "category_match": false,
291
+ "differences": ["..."],
292
+ "suggestions": ["..."],
293
+ "reasoning": "short explanation"
294
+ },
295
+ "functional": {
296
+ "tested": 0,
297
+ "passed": 0,
298
+ "failures": ["..."]
299
+ },
300
+ "structure": {
301
+ "landmark_match": false,
302
+ "missing": ["..."],
303
+ "extra": ["..."]
304
+ },
305
+ "overall_verdict": "revise",
306
+ "priority_fixes": ["..."]
307
+ }
308
+ ```
309
+
310
+ Rules:
311
+ - `visual` follows the `VisualVerdict` shape from `$visual-verdict`
312
+ - `functional.tested/passed` are counts; `failures` list specific interaction failures
313
+ - `structure.landmark_match` is `true` when all major HTML landmarks (nav, main, footer, forms) are present
314
+ - `overall_verdict`: `pass` when visual.score >= 85 AND functional.failures is empty AND structure.landmark_match is true
315
+ - `priority_fixes`: ordered by impact, drives the next iteration
316
+ </Output_Contract>
317
+
318
+ <Iteration_Thresholds>
319
+ - **Visual pass**: score >= 85
320
+ - **Functional pass**: zero failures on tested interactions
321
+ - **Structure pass**: all major landmarks present
322
+ - **Overall pass**: all three dimensions pass
323
+ - **Max iterations**: 5 (report best achieved result if threshold not met)
324
+ </Iteration_Thresholds>
325
+
326
+ <Error_Handling>
327
+ - **Playwright MCP unavailable**: Stop. Instruct user to configure it. Do not attempt to clone without browser tools.
328
+ - **Page fails to load**: Report the URL and HTTP status. Suggest the user verify the URL is accessible.
329
+ - **browser_evaluate returns empty**: The page may use heavy client-side rendering. Wait longer (`browser_wait_for` with extended timeout) and retry once.
330
+ - **Visual score stuck below threshold after 3 iterations**: Report the current state as best-effort. List the unresolved differences for the user.
331
+ - **Extraction data too large for context**: Truncate deep DOM branches (depth > 6). Focus on top-level structure and defer nested details to iteration fixes.
332
+ </Error_Handling>
333
+
334
+ <Example>
335
+ **User**: "Clone https://news.ycombinator.com"
336
+
337
+ **Pass 1**: Navigate to HN. Extract: table-based layout, orange (#ff6600) nav bar, story list with links + points + comments, footer. Screenshot saved.
338
+
339
+ **Pass 2**: Regions: nav bar (logo + links), story table (30 rows × title + meta), footer. Tokens: orange #ff6600, gray #828282, Verdana font, 10pt base. Interaction map: story links (external), comment links, "more" pagination.
340
+
341
+ **Pass 3**: Generate index.html with HN-style table layout, CSS matching extracted colors/fonts, working `<a>` tags for stories.
342
+
343
+ **Pass 4**: Visual score=78 (font size off, spacing between stories too tight). Functional 2/2 (links work). Structure match=true.
344
+
345
+ **Pass 5 iteration 1**: Fix font to Verdana 10pt, increase row padding → score=88. Functional 2/2. Structure match. → `overall_verdict: pass`. Done.
346
+ </Example>
347
+
348
+ <Final_Checklist>
349
+ - [ ] Pass 1 extraction completed and summarized (screenshot + accessibility tree + DOM styles + interactions)
350
+ - [ ] Pass 2 component plan created with file structure
351
+ - [ ] Pass 3 clone generated and files written to `output_dir`
352
+ - [ ] Clone serves locally without errors
353
+ - [ ] Pass 4 composite verdict emitted with all three dimensions
354
+ - [ ] `overall_verdict` is `pass`, or max 5 iterations reached with best-effort report
355
+ - [ ] When in ralph: visual verdict persisted to `ralph-progress.json`
356
+ - [ ] Extraction summary persisted to `web-clone-extraction.json`
357
+ </Final_Checklist>
@@ -11,31 +11,31 @@ Persistent, self-maintained markdown knowledge base for project and session know
11
11
  ## Operations
12
12
 
13
13
  ### Ingest
14
- ```text
15
- wiki_ingest({ title: "Auth Architecture", content: "...", tags: ["auth", "architecture"], category: "architecture" })
14
+ ```bash
15
+ omx wiki wiki_ingest --input '{"title":"Auth Architecture","content":"...","tags":["auth","architecture"],"category":"architecture"}' --json
16
16
  ```
17
17
 
18
18
  ### Query
19
- ```text
20
- wiki_query({ query: "authentication", tags: ["auth"], category: "architecture" })
19
+ ```bash
20
+ omx wiki wiki_query --input '{"query":"authentication","tags":["auth"],"category":"architecture"}' --json
21
21
  ```
22
22
 
23
23
  ### Lint
24
- ```text
25
- wiki_lint()
24
+ ```bash
25
+ omx wiki wiki_lint --json
26
26
  ```
27
27
 
28
28
  ### Quick Add
29
- ```text
30
- wiki_add({ title: "Page Title", content: "...", tags: ["tag1"], category: "decision" })
29
+ ```bash
30
+ omx wiki wiki_add --input '{"title":"Page Title","content":"...","tags":["tag1"],"category":"decision"}' --json
31
31
  ```
32
32
 
33
33
  ### List / Read / Delete
34
- ```text
35
- wiki_list()
36
- wiki_read({ page: "auth-architecture" })
37
- wiki_delete({ page: "outdated-page" })
38
- wiki_refresh()
34
+ ```bash
35
+ omx wiki wiki_list --json
36
+ omx wiki wiki_read --input '{"page":"auth-architecture"}' --json
37
+ omx wiki wiki_delete --input '{"page":"outdated-page"}' --json
38
+ omx wiki wiki_refresh --json
39
39
  ```
40
40
 
41
41
  ## Categories