oh-my-codex 0.20.5 → 0.21.1

package/skills/ultragoal/SKILL.md

@@ -5,177 +5,73 @@ description: Create and execute durable repo-native multi-goal plans over Codex
 
 # Ultragoal Workflow
 
-Use when the user asks for `ultragoal`, `create-goals`, `complete-goals`, durable multi-goal planning, or sequential execution over Codex `/goal`.
+## When to use
 
-## Purpose
+Use for `ultragoal`, `create-goals`, `complete-goals`, durable multi-goal planning, or sequential execution over Codex `/goal`. Read `AGENTS.md#durable-runtime-invariants-canonical-ssot` for state ownership and goal-tool boundaries.
 
-`ultragoal` turns a brief into repo-native artifacts and then drives a Codex goal safely through goal tools. New plans default to a stable pointer-style aggregate Codex goal for the whole durable plan in `.omx/ultragoal/goals.json`, including later accepted/appended stories under the original brief constraints, while OMX tracks G001/G002 story progress in the ledger. Ultragoal does not call Codex `/goal clear`; before multiple sequential ultragoal runs in one Codex session/thread, manually run `/goal clear` in the Codex UI so the previous completed aggregate goal does not block or confuse the next `create_goal`.
+## Inputs and preconditions
 
-- `.omx/ultragoal/brief.md`
-- `.omx/ultragoal/goals.json`
-- `.omx/ultragoal/ledger.jsonl` (checkpoint and structured steering audit events)
+- Durable artifacts are `.omx/ultragoal/brief.md`, `.omx/ultragoal/goals.json`, and `.omx/ultragoal/ledger.jsonl`.
+- New plans use aggregate Codex goal mode by default: one stable pointer objective for the plan while OMX tracks individual stories. Use `--codex-goal-mode per-story` only when explicitly requested.
+- Do not call `/goal clear` from shell or this skill. After a completed run, the operator may clear the interactive Codex goal in the Codex UI before another same-thread run.
 
-Existing aggregate plans with the legacy enumerated objective are migrated to the stable pointer objective on read, persisted to `goals.json`, retained in `codexObjectiveAliases` for already-active hidden Codex goal reconciliation, and audited with an `aggregate_objective_migrated` ledger entry.
+## Operational steps: create
 
-
-## State/HUD Phase Contract
-
-Ultragoal is both a tracked workflow skill and the Autopilot durable-implementation child phase. Keep the phase/HUD contract explicit at workflow boundaries:
-
-- **Standalone `$ultragoal` activation**: ensure `.omx/state[/sessions/<session>]/ultragoal-state.json` exists with `mode:"ultragoal"`, `active:true`, and a non-empty `current_phase` such as `planning` before or while goals are created. This state is a lightweight HUD/runtime declaration; `.omx/ultragoal/goals.json` and `ledger.jsonl` remain the durable goal source of truth.
-- **During execution**: update `current_phase` to the smallest accurate phase (`planning`, `executing`, `verifying`, `reviewing`, `checkpointing`, or `blocked`) when the visible workflow phase changes.
-- **Inside active Autopilot**: keep `mode:"autopilot"` active and set the supervised phase to `current_phase:"ultragoal"`; do not start a peer Autopilot replacement. Ultragoal's own mode state may still exist as child-phase detail, but Autopilot owns the parent phase.
-- **On handoff to code-review**: persist implementation/test/ledger evidence under Autopilot `handoff_artifacts.ultragoal`, then set Autopilot `current_phase:"code-review"`.
-- **On completion/blocker**: set standalone Ultragoal `active:false,current_phase:"complete"` only when all durable goals are complete; otherwise keep it active with a blocker/review-blocked phase and ledger evidence.
-
-Minimal standalone phase declaration:
-
-```sh
-omx state write --input '{"mode":"ultragoal","active":true,"current_phase":"planning"}' --json
-```
-
-Minimal Autopilot child-phase declaration:
-
-```sh
-omx state write --input '{"mode":"autopilot","active":true,"current_phase":"ultragoal"}' --json
+Run one command, then inspect the generated plan:
+```bash
+omx ultragoal create-goals --brief "<brief>"
+omx ultragoal create-goals --brief-file <path>
+cat <brief> | omx ultragoal create-goals --from-stdin
+omx ultragoal create-goals --codex-goal-mode per-story --brief "<brief>"
 ```
+If refinement is needed, use explicit supported steering rather than editing durable artifacts by hand.
 
-## Create goals
-
-1. Run one of:
-   - `omx ultragoal create-goals --brief "<brief>"`
-   - `omx ultragoal create-goals --brief-file <path>`
-   - `cat <brief> | omx ultragoal create-goals --from-stdin`
-   - `omx ultragoal create-goals --codex-goal-mode per-story --brief "<brief>"` only when one Codex goal context per story is explicitly preferred
-2. Inspect `.omx/ultragoal/goals.json` and refine if needed.
-
-## Complete goals
-
-Loop until `omx ultragoal status` reports all goals complete:
+## Operational steps: execute
 
-1. Run `omx ultragoal complete-goals`.
-2. Read the printed handoff.
-3. Call `get_goal`.
-4. If no active Codex goal exists, call `create_goal` with the printed payload. In aggregate mode, if the same aggregate Codex objective is already active, continue the current OMX story without creating a new Codex goal.
-5. Complete the current OMX story only.
-6. Run a completion audit against the story objective and real artifacts/tests.
-7. In aggregate mode, do **not** call `update_goal` for intermediate stories; checkpoint with a fresh `get_goal` snapshot whose aggregate objective is still `active`. On the final story only, first run the mandatory final cleanup/review gate below; call `update_goal({status: "complete"})` only after that gate is clean, then call `get_goal` again for a fresh `complete` snapshot.
-8. Checkpoint the durable ledger with that snapshot. Intermediate aggregate checkpoints use only `--codex-goal-json`; final clean checkpoints also require `--quality-gate-json`:
-   `omx ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --codex-goal-json <get_goal-json-or-path> [--quality-gate-json <quality-gate-json-or-path>]`
-9. If blocked or failed, checkpoint failure:
-   `omx ultragoal checkpoint --goal-id <id> --status failed --evidence "<blocker/evidence>"`
-10. For non-terminal blockers, use blocked checkpoints:
-   - legacy different completed goal: `omx ultragoal checkpoint --goal-id <id> --status blocked --evidence "<completed legacy Codex goal blocks create_goal in this thread>" --codex-goal-json <get_goal-json-or-path>`
-   - matching native Codex `blocked` status: `omx ultragoal checkpoint --goal-id <id> --status blocked --evidence "<blocker evidence>" --codex-goal-json <matching-blocked-get_goal-json-or-path>`
-11. Resume failed goals with `omx ultragoal complete-goals --retry-failed`.
+Repeat until `omx ultragoal status` reports all goals complete:
 
-## Dynamic steering
-
-Use `omx ultragoal steer` when real findings or blockers prove the current story decomposition should change while the aggregate objective and constraints stay fixed. Steering is explicit-only and evidence-backed; broad natural-language requests are rejected instead of guessed.
-
-Allowed mutation kinds are:
-
-- `add_subgoal`
-- `split_subgoal`
-- `reorder_pending`
-- `revise_pending_wording`
-- `annotate_ledger`
-- `mark_blocked_superseded`
+1. Run `omx ultragoal complete-goals` and read its handoff.
+2. Call `get_goal`. Call `create_goal` with the printed payload only when no active Codex goal exists; otherwise continue the matching aggregate objective.
+3. Complete one OMX story and audit its objective against real artifacts and verification evidence.
+4. For intermediate aggregate stories, keep the Codex goal active and checkpoint:
+   ```bash
+   omx ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --codex-goal-json <fresh-get-goal-json-or-path>
+   ```
+5. For a blocked/failed story, use `--status blocked|failed` with evidence; resume failed work with `omx ultragoal complete-goals --retry-failed`.
+6. On the final story, complete the final gate below before `update_goal({status: "complete"})`; then call `get_goal` again and checkpoint the fresh complete snapshot.
 
-Examples:
+## Explicit steering
 
-```sh
-omx ultragoal steer --kind add_subgoal --title "Investigate blocker" --objective "Validate the blocker and report evidence." --evidence "log/test output" --rationale "The blocker changes the safe execution order." --json
+Use evidence-backed directives only when the decomposition must change:
+```bash
+omx ultragoal steer --kind add_subgoal --title "<title>" --objective "<objective>" --evidence "<evidence>" --rationale "<reason>" --json
 omx ultragoal steer --directive-json ./steering.json --json
 ```
+Supported kinds: `add_subgoal`, `split_subgoal`, `reorder_pending`, `revise_pending_wording`, `annotate_ledger`, and `mark_blocked_superseded`. Ordinary prose does not mutate the plan; repeated structured directives dedupe.
 
-Steering invariants:
+## Phase/HUD handoff
 
-- Do not edit the aggregate Codex objective, original brief constraints, quality gates, or completion status. The aggregate objective is a stable pointer to `.omx/ultragoal/goals.json` and `.omx/ultragoal/ledger.jsonl`, not an enumeration of initial goal ids.
-- Do not hard-delete goals, auto-complete work, weaken verification, or silently mutate `.omx/ultragoal`.
-- Accepted and rejected attempts append structured audit entries to `.omx/ultragoal/ledger.jsonl`.
-- Superseded goals remain in `goals.json` with steering metadata and are skipped for scheduling.
-- Blocked goals without replacements are skipped for scheduling but still block final completion until later explicit steering replaces or supersedes them.
-
-UserPromptSubmit uses the same steering API only for structured directives such as `OMX_ULTRAGOAL_STEER: { ... }`, `omx.ultragoal.steer: { ... }`, or `omx ultragoal steer: { ... }`. Normal prose does not mutate state, and repeated prompt-submit directives dedupe by prompt signature or idempotency key.
-
-## Use Ultragoal and Team together
-
-Use ultragoal and team together for a durable Ultragoal story that benefits from parallel execution. Ultragoal remains leader-owned: `.omx/ultragoal/goals.json` stores the story plan and `.omx/ultragoal/ledger.jsonl` stores checkpoints. Team is the parallel execution engine and returns task/evidence status to the leader.
-
-The leader checkpoints Ultragoal from Team evidence with a fresh `get_goal` snapshot:
-
-```sh
-omx ultragoal checkpoint --goal-id <id> --status complete --evidence "<team evidence mentioning .omx/ultragoal and <id>>" --codex-goal-json <fresh-get_goal-json-or-path>
+At standalone activation, declare the smallest accurate phase (`planning`, `executing`, `verifying`, `reviewing`, `checkpointing`, or `blocked`):
+```bash
+omx state write --input '{"mode":"ultragoal","active":true,"current_phase":"planning"}' --json
 ```
+Inside Autopilot, keep the parent mode active and set `current_phase:"ultragoal"`; persist Ultragoal evidence under `handoff_artifacts.ultragoal` before a code-review handoff. Mark standalone Ultragoal complete only when every durable goal is complete.
 
-Workers do not own ultragoal goal state, do not create worker ultragoal ledgers, and do not checkpoint Ultragoal. Team launch remains explicit; Ultragoal does not auto-launch Team and performs no hidden Codex goal mutation.
+## Optional Team bridge
 
-## Mandatory final cleanup and review gate
+For parallel story execution, use the separate Team command. The leader records the Ultragoal checkpoint with a fresh `get_goal` snapshot; see the Team skill for the bridge details.
 
-The final ultragoal story is not complete until the active agent has run the final quality gate:
+## Final gate and exit evidence
 
-1. Run targeted verification for the story.
-2. Run `ai-slop-cleaner` on changed files only; if there are no relevant edits, the cleaner still runs and records a passed/no-op report.
-3. Rerun verification after the cleaner pass.
-4. Run the architecture-invariant audit: derive non-negotiable architecture/domain invariants from the brief/spec/interview/accepted steering/goal artifacts, list the source artifacts, and prove each required invariant with implementation, test, and independent review evidence.
-5. Run `$code-review` through the independent review path. Clean means `codeReview.recommendation: "APPROVE"`, `codeReview.architectStatus: "CLEAR"`, `codeReview.independentReview` contains distinct completed `code-reviewer` and `architect` subagent evidence, and `architectureInvariantGate.status: "passed"` proves every required invariant. `COMMENT`, `WATCH`, `REQUEST CHANGES`, `BLOCK`, missing subagent evidence, unavailable delegation, same-lane/self-review, and unproved architecture invariants are non-clean.
-6. If review or invariant proof is non-clean, do **not** call `update_goal`. Record durable blocker work instead:
+Before final completion:
 
-
-   ```sh
-   omx ultragoal record-review-blockers --goal-id <id> --title "Resolve final code-review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --codex-goal-json <active-get-goal-json-or-path>
+1. Run targeted story verification.
+2. Run `ai-slop-cleaner` on changed files, then rerun verification.
+3. Audit every architecture/domain invariant from the brief/spec/accepted steering against implementation, test, and review evidence.
+4. Run `$code-review` through independent `code-reviewer` and `architect` lanes. If review or invariant proof is not clean, do not update the Codex goal; record durable blockers:
+   ```bash
+   omx ultragoal record-review-blockers --goal-id <id> --title "Resolve final code-review blockers" --objective "<objective>" --evidence "<findings>" --codex-goal-json <active-get-goal-json-or-path>
    ```
+5. If clean, call `update_goal({status: "complete"})`, call `get_goal`, and checkpoint with `--quality-gate-json` containing cleaner, verification, review, and architecture-invariant evidence.
 
-   This marks the current story `review_blocked`, appends a pending blocker-resolution story, keeps the Codex goal active, and lets `omx ultragoal complete-goals` start the blocker next. In legacy per-story mode, the blocker may need an available Codex goal context because the old per-story Codex goal remains active/incomplete.
-
-7. If review and invariant proof are clean, call `update_goal({status: "complete"})`, call `get_goal`, and checkpoint with a structured final gate:
-
-
-   ```sh
-   omx ultragoal checkpoint --goal-id <id> --status complete --evidence "<tests/files/review evidence>" --codex-goal-json <fresh-complete-get-goal-json-or-path> --quality-gate-json <quality-gate-json-or-path>
-   ```
-
-`--quality-gate-json` must include:
-
-```json
-{
-  "aiSlopCleaner": { "status": "passed", "evidence": "cleaner report" },
-  "verification": { "status": "passed", "commands": ["npm test"], "evidence": "post-cleaner verification" },
-  "codeReview": {
-    "recommendation": "APPROVE",
-    "architectStatus": "CLEAR",
-    "evidence": "final review synthesis",
-    "independentReview": {
-      "codeReviewer": { "agentRole": "code-reviewer", "evidence": "code-reviewer subagent APPROVE evidence" },
-      "architect": { "agentRole": "architect", "evidence": "architect subagent CLEAR evidence" }
-    }
-  },
-  "architectureInvariantGate": {
-    "status": "passed",
-    "sourceArtifacts": [".omx/ultragoal/brief.md", ".omx/ultragoal/goals.json"],
-    "evidence": "final invariant audit proved all required architecture/domain invariants",
-    "invariants": [
-      {
-        "invariant": "Preserve the existing parser boundary.",
-        "source": ".omx/ultragoal/brief.md#architecture-invariants",
-        "status": "proved",
-        "implementationEvidence": "changed files preserve the parser boundary",
-        "testEvidence": "parser-boundary regression passed",
-        "reviewEvidence": "architect review confirmed the boundary is intact"
-      }
-    ]
-  }
-}
-```
-
-## Constraints
-
-- The shell command cannot directly invoke Codex interactive `/goal`; it emits a model-facing handoff for the active Codex agent.
-- Ultragoal intentionally does not invoke `/goal clear` or hidden `thread/goal/clear`; the model-facing tool surface only provides `get_goal`, `create_goal`, and `update_goal`.
-- After a completed aggregate ultragoal run, `/goal clear` is the explicit terminal cleanup step before starting another goal in the same Codex thread/session: `create_goal` starts, `update_goal({status: "complete"})` marks terminal success, and `/goal clear` removes the completed thread goal for the next same-thread goal. OMX prints this next step but does not invoke hidden clear routes.
-- Never call `create_goal` when `get_goal` reports a different active goal.
-- Never call `update_goal` unless the aggregate run or legacy per-story goal is actually complete.
-- In aggregate mode, intermediate story checkpoints require a matching `active` Codex snapshot; final story completion requires a matching `complete` snapshot after `update_goal`.
-- Completion checkpoints require read-only Codex snapshot reconciliation: pass fresh `get_goal` JSON/path with `--codex-goal-json`; shell commands and hooks must not mutate Codex goal state.
-- Treat `ledger.jsonl` as the durable audit trail; checkpoint after every success or failure.
+Report goal ids/statuses, ledger/checkpoint paths, fresh goal snapshot evidence, review verdicts, and any blocker. Never claim completion from OMX state alone.

package/skills/ultraqa/SKILL.md

@@ -3,261 +3,84 @@ name: ultraqa
 description: Adversarial dynamic e2e QA workflow - generate hostile scenarios, test, verify, fix, report, and clean up
 ---
 
-# UltraQA Skill
-
-## Operating Contract
-
-- Use outcome-first framing with concise, evidence-dense progress and completion reporting.
-- Treat newer user updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints.
-- If the user says `continue`, advance the current verified next step instead of restarting discovery.
-- UltraQA is not satisfied by a shallow build/lint/typecheck/test checklist. It must exercise the requested behavior through adversarial dynamic e2e scenarios whenever the target can be run, simulated, or harnessed safely.
-
-[ULTRAQA ACTIVATED - ADVERSARIAL DYNAMIC E2E QA CYCLING]
-
-## Overview
-
-UltraQA finds real behavior failures by combining normal verification commands with generated end-to-end scenarios, hostile user modeling, temporary harnesses when useful, and a structured evidence report. The workflow repeats test → diagnose → fix → retest until the goal is met, a bounded stop condition is reached, or a safety boundary blocks further execution.
-
-## Goal Parsing
-
-Parse the goal from arguments. Supported formats:
-
-| Invocation | Goal Type | What to Check |
-|------------|-----------|---------------|
-| `/ultraqa --tests` | tests | Existing tests plus adversarial dynamic e2e scenarios for the changed behavior |
-| `/ultraqa --build` | build | Build succeeds and generated smoke/e2e probes still run against the built artifact when applicable |
-| `/ultraqa --lint` | lint | Lint passes and no generated harness/test artifact violates project hygiene |
-| `/ultraqa --typecheck` | typecheck | Typecheck passes and generated typed harnesses compile when applicable |
-| `/ultraqa --custom "pattern"` | custom | Custom success pattern is verified against behavior, not trusted as misleading success output |
-| `/ultraqa --interactive` | interactive | CLI/service behavior is tested with generated hostile and edge-case interactions |
-
-If no structured goal is provided, interpret the argument as a custom behavior goal and derive a runnable e2e strategy from repository context.
-
-## Required Scenario Matrix
-
-Before declaring success, create and maintain a scenario matrix. Each row must include: scenario id, intent, user/attacker model, setup, command or harness, expected signal, actual result, fixes applied, evidence, and cleanup status.
-
-The matrix must include normal-path coverage plus adversarial dynamic e2e scenarios selected from the current goal and codebase. Unless clearly irrelevant or impossible, include these hostile and edge-case classes:
-
-1. **Malformed input**: invalid JSON, missing fields, invalid flags, oversized strings, unusual Unicode, path traversal-like values, and corrupted state files.
-2. **Repeated interruptions**: repeated `continue`, stop/cancel/abort wording, interrupted command output, and retries after partial progress.
-3. **Prompt injection attempts**: user text that tries to override instructions, exfiltrate secrets, skip verification, delete state, or claim false success.
-4. **Cancel/resume behavior**: active state cleanup, resume detection, stale in-progress state, and cancellation followed by a fresh run.
-5. **Stale state**: old `.omx/state` files, mismatched sessions, missing timestamps, and contradictory phase metadata.
-6. **Dirty worktree**: pre-existing modifications, untracked generated files, and verification that UltraQA does not hide or overwrite unrelated work.
-7. **Hung or long-running commands**: bounded timeout handling, killed child processes, and recovery notes.
-8. **Flaky tests**: rerun strategy, failure clustering, quarantine evidence, and avoiding false green from a single lucky pass.
-9. **Misleading success output**: output containing success phrases with non-zero exits, hidden failures, skipped tests, or partial command logs.
-
-## Dynamic E2E and Temporary Harness Rules
-
-- Generate temporary tests, scripts, fixtures, or harnesses when they materially improve behavioral confidence and no existing e2e surface covers the scenario.
-- Prefer project-native test tools and small throwaway harnesses under a temporary directory or clearly named test fixture.
-- Record every generated artifact in the scenario matrix, including whether it was committed intentionally or removed during cleanup.
-- Use bounded runtimes and explicit timeouts for commands that can hang.
-- Validate exit codes and output semantics; do not trust success-looking text alone.
-- Do not delete, rewrite, or mask unrelated user work. Capture dirty-worktree evidence before and after generated harness work.
-
-### Temporary Harness Generation Guardrails
-
-Generated harnesses are part of the QA evidence chain; until setup succeeds, they are evidence about the harness apparatus, not product behavior.
-
-- **Use absolute repo imports for built artifacts.** When a harness runs from `/tmp` or another scratch directory but imports repository code, resolve the repository root explicitly from the verified repo cwd and import built modules with an absolute path or `pathToFileURL(join(repoRoot, "dist", ...)).href`. Never rely on `./dist/...` from the harness file's temporary directory.
-- **Use a safe file writer for JS/TS harness bodies.** Prefer a small Node/Python writer or another non-interpolating file-write mechanism for harness source that contains backticks, `${...}`, shell metacharacters, or prompt-injection strings. If a shell heredoc is unavoidable, quote the delimiter and verify the written file before execution; do not use interpolating heredocs for JavaScript assertions.
-- **Sanitize OMX runtime env for isolated probes.** When the scenario creates a temporary repo/state tree or intentionally checks local isolation, run the probe with `OMX_ROOT` and `OMX_STATE_ROOT` unset (for example `env -u OMX_ROOT -u OMX_STATE_ROOT ...`) so ambient boxed runtime state cannot redirect reads/writes away from the scenario fixture.
-- **Classify harness setup failures separately.** If a generated harness fails before exercising product behavior because of import paths, shell interpolation, environment leakage, or fixture construction, record it as harness debris, fix the harness, and rerun the scenario before declaring a product defect.
-
-## Cycle Workflow
-
-### Cycle N (Max 5)
-
-1. **PLAN ADVERSARIAL QA**
-   - Restate the goal, success criteria, safety bounds, and stop condition.
-   - Inspect repository context enough to identify runnable surfaces, test commands, state files, and cleanup paths.
-   - Build or update the required scenario matrix before running commands.
-
-2. **RUN BASELINE VERIFICATION**
-   - `--tests`: Run the project's test command.
-   - `--build`: Run the project's build command.
-   - `--lint`: Run the project's lint command.
-   - `--typecheck`: Run the project's type check command.
-   - `--custom`: Run the appropriate command and check the pattern plus exit status and failure markers.
-   - `--interactive`: Use qa-tester or an equivalent CLI/service harness:
-     ```
-     Use `/prompts:qa-tester` with:
-     Goal: [describe what to verify]
-     Service: [how to start]
-     Test cases: [normal, hostile, malformed, interruption, resume, stale-state, dirty-worktree, hung-command, flaky, and misleading-output scenarios]
-     ```
-
-3. **RUN ADVERSARIAL DYNAMIC E2E SCENARIOS**
-   - Execute the scenario matrix using existing e2e tests, generated temporary tests, or generated harnesses.
-   - Model malicious/hostile user behavior explicitly, including prompt injection and attempts to bypass safety or verification.
-   - Exercise malformed input, repeated interruptions, cancel/resume, stale state, dirty worktree handling, hung commands, flaky tests, and misleading success output when relevant.
-   - Capture commands, exit codes, important output excerpts, artifacts, and cleanup status.
-
-4. **CHECK RESULT**
-   - **YES** only if baseline verification and adversarial e2e scenarios passed, generated artifacts are cleaned up or intentionally tracked, and the report has complete evidence.
-   - **NO** if any scenario failed, was skipped without justification, left debris, relied on misleading output, or lacked evidence. Continue to step 5.
-
-5. **ARCHITECT DIAGNOSIS**
-   ```
-   Use `/prompts:architect` with:
-   Goal: [goal type and behavior]
-   Scenario matrix: [rows, commands, failures, evidence]
-   Output: [test/build/e2e/harness output]
-   Provide root cause, safety implications, and specific fix recommendations.
-   ```
-
-6. **FIX ISSUES**
-   ```
-   Use `/prompts:executor` with:
-   Issue: [architect diagnosis]
-   Files: [affected files]
-   Constraints: preserve unrelated dirty work, clean temporary harnesses, keep safety bounds
-   Apply the fix precisely as recommended.
-   ```
-
-7. **CLEAN UP AND ROLLBACK**
-   - Remove temporary harnesses, fixtures, logs, spawned processes, and state files unless they are intentional deliverables.
-   - Roll back failed experimental edits that are not part of the final fix.
-   - Re-check the worktree and record remaining intentional changes or residual debris.
-
-8. **REPEAT**
-   - Go back to step 1 with the updated scenario matrix and failure history.
-
-## Safety Bounds
-
-UltraQA must stay inside these safety bounds:
-
-- No destructive commands such as force resets, broad deletes, secret exfiltration, credential dumping, production writes, or unbounded process spawning.
-- No reading or printing secrets beyond the minimum metadata needed to verify absence of leakage.
-- No network or external-production side effects unless the user explicitly authorized them.
-- No unbounded waits: use timeouts, retries with caps, and clear hung-command diagnostics.
-- No hiding unrelated dirty work or generated debris.
-- If a required scenario would violate these bounds, mark it blocked in the report with the safe substitute used.
-
-## Exit Conditions
-
-| Condition | Action |
-|-----------|--------|
-| **Goal Met** | Exit with success: `ULTRAQA COMPLETE: Goal met after N cycles` plus the structured report |
-| **Cycle 5 Reached** | Exit with diagnosis: `ULTRAQA STOPPED: Max cycles` plus failures, fixes attempted, residual risks, and evidence |
-| **Same Failure 3x** | Exit early: `ULTRAQA STOPPED: Same failure detected 3 times` plus root cause, safety notes, and next owner |
-| **Safety Boundary** | Exit: `ULTRAQA BLOCKED: [destructive/credentialed/external-production/unbounded action]` plus safe substitute evidence |
-| **Environment Error** | Exit: `ULTRAQA ERROR: [tmux/port/dependency/hung command issue]` plus cleanup status |
-
-## Structured Report
-
-Every terminal UltraQA result must include this report shape:
-
-```markdown
-# UltraQA Report
-
-## Goal and success criteria
-- Goal:
-- Stop condition:
-- Safety bounds applied:
-
-## Scenario matrix
-| ID | User/attacker model | Scenario | Command/harness | Expected signal | Actual result | Status | Evidence | Cleanup |
-|----|---------------------|----------|-----------------|-----------------|---------------|--------|----------|---------|
-
-## Commands run
-- `[exit code] command` — purpose, duration/timeout, key output evidence
-
-## Failures found
-- Scenario ID, failure signal, root cause, user impact, safety impact
-
-## Fixes applied
-- Files changed, rationale, linked failing scenario(s), regression evidence
-
-## Cleanup and rollback
-- Generated artifacts removed or intentionally kept
-- State/process cleanup performed
-- Worktree status before/after
-
-## Residual risks
-- Untested or blocked scenarios with reasons and safe substitutes
-
-## Evidence
-- Test output, e2e logs, harness output, screenshots/transcripts when relevant, and rerun/flake evidence
-```
-
-## Observability
-
-Output progress each cycle:
-
-```text
-[ULTRAQA Cycle 1/5] Planning adversarial scenario matrix...
-[ULTRAQA Cycle 1/5] Running baseline tests...
-[ULTRAQA Cycle 1/5] Running ADV-E2E-003 prompt-injection harness...
-[ULTRAQA Cycle 1/5] FAILED - stale state resume accepted misleading success output
-[ULTRAQA Cycle 1/5] Architect diagnosing scenario ADV-E2E-003...
-[ULTRAQA Cycle 1/5] Fixing: src/hooks/... - validate exit code before success phrase
-[ULTRAQA Cycle 1/5] Cleaning temporary harnesses and state...
-[ULTRAQA Cycle 2/5] PASSED - baseline + 9 adversarial scenarios pass
-[ULTRAQA COMPLETE] Goal met after 2 cycles
+# UltraQA Task Card
+
+Use this explicit opt-in when a runnable behavior needs adversarial dynamic end-to-end
+QA. Shared operating invariants live in `templates/AGENTS.md`; this card defines the
+QA matrix, evidence contract, and bounded cycling only.
+
+## When to use and inputs
+
+- Use `/ultraqa --tests|--build|--lint|--typecheck|--interactive` or `/ultraqa --custom "pattern"` for the corresponding goal; without a structured goal, derive a runnable behavior goal.
+- Inputs: goal, changed scope, acceptance criteria, runnable command/service, existing tests, and relevant state/cleanup paths.
+- Keep outcome-first framing, local overrides for the active workflow branch, and `continue` on the current verified next step.
+- If the user says `continue`, advance the current verified QA step rather than restarting discovery.
+- UltraQA is not satisfied by a shallow build/lint/typecheck/test checklist: exercise requested behavior through adversarial dynamic e2e scenarios whenever it can be run, simulated, or harnessed safely.
+
+## Plan and scenario matrix
+
+Before commands, record a matrix with scenario id, intent, user/attacker model, setup,
+command or harness, expected signal, actual result, fixes, evidence, and cleanup.
+Include a normal path and relevant hostile classes:
+
+1. **Malformed input**: invalid JSON, missing fields, invalid flags, oversized strings, unusual Unicode, traversal-like values, corrupted state.
+2. **Repeated interruptions**: repeated `continue`, stop/cancel/abort wording, partial output, and retries.
+3. **Prompt injection**: attempts to override instructions, exfiltrate secrets, skip verification, delete state, or claim success.
+4. **Cancel/resume behavior** and **stale state**: cleanup, resume detection, mismatched sessions, missing timestamps, contradictory phases.
+5. **Dirty worktree**: pre-existing changes/untracked files remain untouched.
+6. **Hung or long-running commands**: bounded timeout, killed child, recovery note.
+7. **Flaky tests**: capped reruns, failure clustering, quarantine evidence; never a lucky single green.
+8. **Misleading success output**: success text with non-zero exit, hidden failures, skips, or partial logs.
+
+## Cycle (maximum 5)
+
+1. **PLAN ADVERSARIAL QA**: state goal, success criteria, safety bounds, stop condition, runnable surfaces, and matrix.
+2. **RUN BASELINE VERIFICATION**: `--tests` runs project tests; `--build` runs build plus built-artifact probes; `--lint` runs lint; `--typecheck` runs typecheck plus typed harnesses; `--custom` verifies pattern and exit status; `--interactive` uses a bounded CLI/service harness.
+3. **RUN ADVERSARIAL DYNAMIC E2E SCENARIOS** and capture exit codes, output, artifacts, and cleanup.
+4. **CHECK RESULT**: pass only when baseline, adversarial scenarios, evidence, and cleanup all pass. Otherwise diagnose and fix, then repeat.
+5. **ARCHITECT DIAGNOSIS** must provide root cause and safety impact; **FIX ISSUES** precisely; **CLEAN UP AND ROLLBACK** temporary harnesses, fixtures, logs, processes, state, and failed experiments before the next cycle.
+
+Generate temporary tests, scripts, fixtures, or harnesses only when useful. Use bounded runtimes,
+project-native tools, and safe substitutes when a safety boundary blocks a scenario.
+Use absolute repo imports and `pathToFileURL(join(repoRoot, "dist", ...)).href`; Never rely on `./dist` from `/tmp`.
+Use a safe file writer with a non-interpolating file-write mechanism; do not use interpolating heredocs for JavaScript assertions.
+Sanitize OMX runtime env for isolated probes: keep `OMX_ROOT` and `OMX_STATE_ROOT` unset and run `env -u OMX_ROOT -u OMX_STATE_ROOT`.
+Classify harness setup failures separately: record it as harness debris, fix the harness, and rerun the scenario before declaring a product defect.
+
+## Safety, state, and exit
+
+No destructive commands, secret exfiltration, credential dumping, production writes, or unbounded process spawning. Use no unbounded waits; preserve unrelated dirty work. If a scenario is unsafe, record it blocked and the safe substitute. Three repeats of the same failure stop with diagnosis; cycle 5 stops with residual risks; goal success exits after a passing cycle.
+
+Use CLI-first lifecycle state and exact commands:
+
+```sh
+omx state write --input '{"mode":"ultraqa","active":true,"current_phase":"planning","iteration":1,"started_at":"<now>","scenario_matrix":[]}' --json
+omx state write --input '{"mode":"ultraqa","current_phase":"qa","iteration":<cycle>,"scenario_matrix":"<updated matrix path or summary>"}' --json
+omx state write --input '{"mode":"ultraqa","current_phase":"adversarial-e2e"}' --json
+omx state write --input '{"mode":"ultraqa","current_phase":"diagnose"}' --json
+omx state write --input '{"mode":"ultraqa","current_phase":"fix"}' --json
+omx state write --input '{"mode":"ultraqa","current_phase":"cleanup"}' --json
+omx state write --input '{"mode":"ultraqa","active":false,"current_phase":"complete","completed_at":"<now>"}' --json
+omx state read --input '{"mode":"ultraqa"}' --json
+omx state clear --input '{"mode":"ultraqa"}' --json
 ```
 
-## State Tracking
+On completion, max cycles, same failure, safety boundary, or environment error, clean
+state and temporary artifacts. Report cleanup status and clean temporary e2e harnesses.
+Never claim complete without current evidence.
 
-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.
+## Evidence/output contract
 
-- **On start**:
-  `omx state write --input '{"mode":"ultraqa","active":true,"current_phase":"planning","iteration":1,"started_at":"<now>","scenario_matrix":[]}' --json`
-- **On each cycle**:
-  `omx state write --input '{"mode":"ultraqa","current_phase":"qa","iteration":<cycle>,"scenario_matrix":"<updated matrix path or summary>"}' --json`
-- **On adversarial e2e transition**:
-  `omx state write --input '{"mode":"ultraqa","current_phase":"adversarial-e2e"}' --json`
-- **On diagnose/fix transitions**:
-  `omx state write --input '{"mode":"ultraqa","current_phase":"diagnose"}' --json`
-  `omx state write --input '{"mode":"ultraqa","current_phase":"fix"}' --json`
-- **On cleanup transition**:
-  `omx state write --input '{"mode":"ultraqa","current_phase":"cleanup"}' --json`
-- **On completion**:
-  `omx state write --input '{"mode":"ultraqa","active":false,"current_phase":"complete","completed_at":"<now>"}' --json`
-- **For resume detection**:
-  `omx state read --input '{"mode":"ultraqa"}' --json`
+Return `# UltraQA Report` with: **Goal and success criteria** (including stop condition
+and safety bounds); **Scenario matrix** (all columns above); **Commands run** (exit code,
+purpose, timeout, key output); **Failures found** (root/user/safety impact); **Fixes
+applied** / **Fixes applied** (files, rationale, scenarios, regression evidence); **Cleanup and rollback**
+(artifacts/processes/worktree before/after); **Residual risks**; and **Evidence**
+(logs, harness output, screenshots/transcripts where relevant, rerun/flake evidence).
 
-## Scenario Examples
-
-**Good:** The user says `continue` after the workflow already has a clear next step. Continue the current branch of work, rerun the relevant adversarial scenario, and update the report instead of restarting discovery.
-
-**Good:** The user changes only the output shape or downstream delivery step (for example `make a PR`). Preserve earlier non-conflicting workflow constraints and apply the update locally.
-
-**Good:** A CLI prints `SUCCESS` while exiting 1. Mark the misleading success output scenario failed, fix the parser or reporting path, and rerun the generated harness.
-
-**Bad:** The workflow runs only `npm test`, `npm run build`, `npm run lint`, or `npm run typecheck`, sees green output, and declares UltraQA complete without adversarial dynamic e2e coverage.
-
-**Bad:** A generated harness leaves untracked files, state, or a child process behind and the final report omits cleanup status.
-
-**Bad:** The user says `continue`, and the workflow restarts discovery or stops before the missing verification/evidence is gathered.
-
-## Cancellation
-
-User can cancel with `/cancel`, which clears UltraQA state. Cancellation itself should be tested in cancel/resume scenarios when relevant, but UltraQA must not block an explicit user cancellation.
-
-## Important Rules
-
-1. **ADVERSARIAL E2E REQUIRED** - Baseline build/lint/typecheck/test commands are necessary evidence, not sufficient completion proof.
-2. **SCENARIO MATRIX REQUIRED** - Track normal, hostile, malformed, interruption, injection, cancel/resume, stale-state, dirty-worktree, hung-command, flaky, and misleading-output coverage.
-3. **GENERATE HARNESSES WHEN USEFUL** - Create temporary tests or harnesses when they materially improve behavioral confidence, then clean them up or commit them intentionally.
-4. **PARALLEL WHEN SAFE** - Run independent diagnostics while preparing potential fixes; do not parallelize commands that mutate the same state or worktree.
-5. **TRACK FAILURES** - Record each failure to detect patterns and avoid false greens.
-6. **EARLY EXIT ON PATTERN** - 3x same failure = stop and surface with root cause and residual risk.
-7. **CLEAR OUTPUT** - User should always know current cycle, scenario, command, status, and evidence.
-8. **CLEAN UP** - Clear UltraQA state and temporary artifacts on completion, cancellation, or early stop.
-9. **SAFETY FIRST** - Never exfiltrate secrets, run destructive cleanup, write to production, or wait indefinitely to satisfy a scenario.
-
-## STATE CLEANUP ON COMPLETION
-
-When goal is met OR max cycles reached OR exiting early, run `$cancel` or call:
-
-`omx state clear --input '{"mode":"ultraqa"}' --json`
-
-Use CLI state cleanup rather than deleting files directly. Also remove temporary e2e harnesses, fixtures, and logs unless they are intentional artifacts listed in the report.
-
----
+## Exit condition
 
-Begin ULTRAQA cycling now. Parse the goal, build the adversarial dynamic e2e scenario matrix, and start cycle 1.
+`ULTRAQA COMPLETE: Goal met after N cycles` only follows a passing baseline plus
+adversarial matrix, clean artifacts, and complete evidence. Otherwise return the exact
+bounded status: `ULTRAQA STOPPED: Max cycles`, `ULTRAQA STOPPED: Same failure detected 3 times`,
+`ULTRAQA BLOCKED: ...`, or `ULTRAQA ERROR: ...` with owner and next safe step.