oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/_shared/core/session-metrics.md

@@ -0,0 +1,35 @@
+# Session Evidence
+
+Consult this guide for a requested retrospective, a substantive correction, or a review finding worth preserving. Routine work does not need a second log alongside existing progress and result artifacts.
+
+## Record observations, not penalty scores
+
+Do not assign points to questions, corrections, or review judgments. The former Clarification Debt (CD) and Evaluator Accuracy (EA) weights and thresholds are retired; they were prompt instructions, not CLI-computed metrics. Necessary clarification is not a failure, a user changing scope is not an agent error, and a disputed QA finding is not an established false positive.
+
+When useful, record an event with session/task/run identity, an evidence path, observed impact, cause if known, and the action taken. Reuse the existing result or progress artifact. For a separate session summary, use the configured coordination store's `session-metrics-{sessionId}.md` (default `.agents/state/memories/`). Distinguish:
+
+| Observation | Evidence to retain |
+|---|---|
+| Material clarification | Missing decision and how the answer changed dependent work |
+| User scope change | New request and affected acceptance criteria |
+| Agent mistake or rework | Requirement missed, affected behavior, correction, and verification |
+| Blocked action | Exact missing input or authority and independent work completed |
+| Review error or useful finding | Finding, reproduction or counterexample, adjudicated outcome, and impact |
+
+A disputed finding stays unresolved until code, tests, or other evidence settle it. Judge severity by impact and exposure, not diff size. Keep useful catches, false positives, and missed defects separate; do not net them into an agent score or claim an accuracy rate without a defined labeled evaluation set.
+
+## Respond to the cause
+
+Correct the affected work and verify it. Pause only actions dependent on unresolved information or authorization, under `execution-policy.md`. Do not stop a session, trigger another agent, or require an RCA because a counter crossed a threshold.
+
+For repeated failures, a consequential incident, or a user-requested retrospective, record the known cause and prevention evidence using `lessons-learned.md`. An ordinary failed check, including an expected RED test, does not require a separate RCA. Propose durable instruction changes only when evidence supports them; edit canonical definitions within an authorized source-maintenance task.
+
+## Measurements and tooling
+
+- Prefer observed task outcomes, relevant check results, retries, elapsed time, and recorded usage over inferred scores. State the measurement source and limits; progress updates are not a reliable turn counter, and checkpoint counts are not reset counts.
+- `oma stats` reports the CLI's productivity and recorded usage/cost summaries. It does not parse this Markdown into CD or EA scores. Cost estimates are not billing receipts.
+- `oma retro` groups recorded `gate.failed`, `blocker.raised`, and `decision.missing` events into harness suggestions. Those suggestions still need causal review; they do not automatically modify prompts.
+- If the active workflow uses quality measurement or experiments, link the actual artifacts from `../conditional/quality-score.md` and `../conditional/experiment-ledger.md`. Do not fabricate missing measurements or mix them with conversational event counts.
+- For model or prompt comparisons, use `../../oma-skill-creation/resources/prompt-evaluation.md`. Compare equivalent tasks and report correctness, interruptions, latency, and measured cost separately.
+
+Keep existing historical logs as evidence. This guide neither schedules deletion nor imposes a retention deadline.

package/skills/_shared/core/skill-routing.md

@@ -0,0 +1,39 @@
+# Skill Routing
+
+Use this map when selecting a specialist or coordinating an authorized multi-agent task. Route by the requested outcome and concrete dependencies, not a keyword alone. Choosing a skill does not start a workflow or authorize delegation.
+
+## Context and ownership
+
+The runtime exposes skill names and descriptions for discovery. Read the owning SKILL.md when the task matches its scope or the user invokes it, under the host's skill rules. Load supporting references only when needed (`context-loading.md`). Use one owning specialist for a scoped task; add a handoff only when it supplies a distinct needed capability.
+
+| Requested outcome | Owning skill |
+|---|---|
+| Application API, server auth, service/data access logic | `oma-backend` |
+| Schema, migration design, indexing, query tuning, database operations | `oma-db` |
+| Web components, pages, forms, client state | `oma-frontend` |
+| Mobile screens, widgets, platform integration | `oma-mobile` |
+| System boundaries, architecture tradeoffs, ADR | `oma-architecture` |
+| Diagnose and fix incorrect behavior | `oma-debug` |
+| Review correctness, security, accessibility, performance | `oma-qa` |
+| Visual system, DESIGN.md, redesign direction | `oma-design` |
+| Requested ideation or alternative exploration | `oma-brainstorm` |
+| Requirements, dependencies, acceptance criteria | `oma-pm` |
+| Requested parallel specialist execution | `oma-orchestration` |
+| Requested manual multi-agent coordination | `oma-coordination` |
+| Git branches, commits, merges, repository history | `oma-scm` |
+
+For other domains, select from the installed skill descriptions. Preserve explicit task ownership and vendor/model configuration.
+
+## Dependencies
+
+- Resolve an unsettled architecture or product decision before work that depends on it. Existing decisions do not need to pass through architecture, brainstorming, or PM again.
+- Backend and client work may proceed independently when their shared API contract is usable. If it is missing, settle that boundary with the relevant owners; use `api-contracts/README.md` when a contract artifact is needed.
+- Review can start on a completed, reviewable portion while independent implementation continues. Do not review an unstable artifact as final evidence.
+- A bug found during implementation can be fixed by its owner. Add debug assistance when diagnosis warrants it; there is no required implementation-to-debug chain.
+- For a cross-domain defect, identify the failing contract and responsible owner from evidence. An API mismatch does not automatically mean the backend must change.
+
+## Dispatch and completion
+
+Use `vendor-detection.md` when dispatch details are unresolved. Parallelize only independent work within the authorized task and available runtime. Each dispatched task needs ownership, acceptance criteria, relevant context, and the runtime's result contract.
+
+A difficulty estimate does not impose fixed per-agent turn limits. Respect explicit user/runtime budgets and preserve partial progress when a real limit is reached. Completion and unresolved decisions follow `execution-policy.md`.

package/skills/_shared/core/test-approach.md

@@ -0,0 +1,54 @@
+# Per-Task Test Approach & TDD Evidence
+
+Opt-in, per-task test strategy carried in the PM plan (`plan-{sessionId}.json`).
+PM assigns it (see `oma-pm/resources/execution-protocol.md` Step 3); implementation
+agents honor it; QA and Ultrawork gates verify evidence **only** for tasks marked `tdd`.
+
+## Approaches
+
+| `test_approach` | Meaning | Agent obligation |
+|---|---|---|
+| `tdd` | Deterministic, high-risk behavior (validation, authorization, state transitions, calculations, error handling) | Write and run the focused test **before** the production change (RED), make the minimal change (GREEN), refactor only if needed. Record a `TDD_EVIDENCE` block in the result file. |
+| `test_after` | Automated tests required, but a useful isolated RED state is impractical | Write tests with/after the implementation. No evidence block required. |
+| `not_applicable` | Automated tests inappropriate | Perform the plan's `alternative_verification` and report its outcome. Plan must carry `test_approach_rationale`. |
+
+Tasks without a `test_approach` field behave as today (tests per the agent's
+normal protocol). Refactor tasks never use `tdd` — they keep the
+characterization-test safety net (`oma-refactor`).
+
+## Coverage applicability rule
+
+`test_approach` does not silently waive coverage. Use the project's declared
+baseline, changed-code target, or task-specific risk target when coverage is
+applicable. When it is not, the plan must state risk-focused tests or an
+alternative verification method and its limits. Do not impose a global numeric
+floor on projects that have not defined one.
+
+## TDD_EVIDENCE block format
+
+Append to the task/run-scoped result report, one entry per `tdd` task:
+
+```
+TDD_EVIDENCE:
+- task: task-2
+  test_command: bun test src/services/discount.test.ts
+  red: "expected 400, received 200" (before implementation)
+  green: 12 pass, 0 fail (after implementation)
+```
+
+Requirements (enforced by `oma verify agent <agent>` → "TDD Evidence" check):
+
+1. Block starts with the literal marker `TDD_EVIDENCE:`
+2. Every `tdd` task id from the plan appears in the block
+3. At least one `red:` entry (the observed failure before the change) and one
+   `green:` entry (the passing result after the change)
+
+A task may opt out with `tdd_evidence_required: false` in the plan (e.g., the
+RED state is demonstrated in a linked CI run instead); the rationale belongs in
+the task description.
+
+## Debug parity
+
+Debug regression tests follow the same discipline where feasible: run the
+regression test before applying the fix, record the failing output (RED) and
+the post-fix pass (GREEN) in the bug report / result file.

package/skills/_shared/core/vendor-detection.md

@@ -0,0 +1,52 @@
+# Vendor Detection Protocol
+
+When executing a workflow, determine your runtime environment using this priority order.
+Then resolve the target vendor for each agent from `.agents/oma-config.cue` or `.agents/oma-config.yaml`. Apply project-local configuration overlays. With `model_preset: free`, use `oma agent spawn` so the FreeLLMAPI route is applied. Otherwise explicit `agents:` model overrides take priority. With `model_preset: auto` (the default for new installs), unconfigured agents follow the current runtime's native agent definitions and model settings; do not substitute a fixed vendor preset or inject a model/effort override. When the runtime cannot be detected, use `default_cli` (or `claude` when omitted). Fixed built-in and custom presets continue to resolve model slugs (`<owner>/<slug>`) to their owning vendors. See `web/docs/guide/per-agent-models.md` for details.
+
+Important:
+- Do **not** choose one spawn strategy for the entire workflow based only on the main runtime vendor.
+- Decide per agent:
+  - `current_runtime_vendor`
+  - `target_vendor_for_agent`
+  - whether that exact runtime can invoke that target vendor natively
+- If native invocation is not available for that agent, fall back to `oma agent spawn`.
+
+## Identify the current runtime
+
+Use explicit host identity and runtime configuration first. Inspect the native dispatch capability actually exposed in the session. Shared tool names such as `apply_patch`, an `@` syntax, or a skill-directory path do not uniquely identify a vendor.
+
+If identity or native dispatch is unresolved, use the configured fallback; do not guess that the runtime is Codex or Antigravity from a generic tool. For OpenCode, an explicitly identified session with native `task` can dispatch through it even when `apply_patch` is also available.
+
+## Vendor-Specific Spawn Methods
+
+| Vendor | Spawn Method | Result Handling |
+|:---|:---|:---|
+| Claude Code | `Agent` tool with `.claude/agents/{name}.md` | Return value (foreground) or completion notification (`run_in_background=true`) |
+| OpenCode | Same session: native `task` tool with `subagent_type: {agent-id}` (the only path that shows as a native child task in the active OpenCode GUI/TUI). External fallback: `oma agent spawn`, which creates a temporary primary wrapper that delegates to the `mode: subagent` agent — `opencode run --agent {subagent}` alone is rejected and falls back to the default agent. | Native task return / result file poll |
+| Kilo Code | Same as OpenCode (Kilo is an OpenCode fork): native `task` tool with `subagent_type: {agent-id}` for `.kilo/agents/{name}.md`; external fallback `oma agent spawn` uses the same temporary primary wrapper (`kilo run --agent {subagent}` alone is rejected the same way). Kilo sets `KILO=1` in tool subprocesses. | Native task return / result file poll |
+| Codex CLI | Current-session native dispatch with custom agents in `.codex/agents/{name}.toml` when available, otherwise `oma agent spawn`. A role file without `model` runs on the parent's model; spawn `docs-curator` and `research-explorer` with the fastest model the spawn tool lists as available, and leave `model` unset for other roles and for files that pin one. Never invent a model name. | JSON output |
+| Antigravity | Prefer `oma agent spawn` unless a native role-subagent path is explicitly verified for the target vendor | MCP memory poll |
+| CLI Fallback | `oma agent spawn {agent} {prompt} {session} -w {workspace}` | Result file poll |
+
+## Dispatch Rule
+
+For each agent:
+
+1. Resolve `target_vendor_for_agent` from config
+2. If `target_vendor_for_agent === current_runtime_vendor` and that runtime has a verified native role-subagent path for that vendor, use the vendor variant agent definition
+3. Otherwise, use `oma agent spawn`
+
+Example:
+- Runtime: Claude Code
+- Resolved models: `frontend` → `anthropic/…`, `backend` → `anthropic/…`, `qa` → `openai/…` (owning vendors: claude, claude, codex)
+- Result:
+  - `frontend` -> native Claude subagent
+  - `backend` -> native Claude subagent
+  - `qa` -> external Codex spawn via `oma agent spawn`
+
+### OpenCode specifics
+
+- If `current_runtime_vendor == opencode` and `target_vendor_for_agent == opencode` and the `task` tool exists, use native `task(subagent_type: "<agent-id>")`.
+- Do **not** use `oma agent spawn` for same-session OpenCode subagents — it is an external fallback and will not appear as a native child task in the active OpenCode GUI/TUI.
+- Before using the `oma agent spawn` fallback, confirm that native same-runtime dispatch is genuinely unavailable.
+- Kilo Code follows the same rules with `kilo` in place of `opencode`.

package/skills/_shared/runtime/memory-protocol.md

@@ -0,0 +1,118 @@
+# Memory Protocol (CLI Mode)
+
+> **Note**: This file documents the default (direct-file) memory protocol. Vendor-specific execution protocols are injected automatically by `oma agent spawn` from `execution-protocols/{vendor}.md`.
+
+When running as a CLI subagent, follow this protocol.
+
+## Tool Reference
+
+Coordination artifacts are read and written as plain files using your native file tools.
+Tool names remain configurable via `mcp.json → memoryConfig.tools`; this file
+memory contract is independent of any code-intelligence provider.
+- `[READ]` → default: `Read`
+- `[WRITE]` → default: `Write`
+- `[EDIT]` → default: `Edit`
+- `[LIST]` → default: directory listing (e.g. `ls` / `list_dir`)
+- `[DELETE]` → default: file delete (e.g. `rm`)
+
+Memory base path is configurable via `memoryConfig.basePath` (default: `.agents/state/memories`). Create the directory if it does not yet exist.
+
+> **CRITICAL**: Do NOT use Serena's MCP `write_memory` / `read_memory` for workflow state or result reports. Use file tools (`Read`/`Write`/`Edit`): session and progress notes go under `{memoryConfig.basePath}/`, and `result-*.md` reports always go under the project-root `.agents/results/`. Create `.agents/results/` if it does not yet exist. Verification gates check these durable files and their receipt bindings.
+
+---
+
+## Path Resolution (CRITICAL)
+
+Use the injected `claimPath` for structured result claims and do not rename or
+move it. Keep existing flat session artifacts for consumer compatibility. Add
+task and run identity to human-readable reports:
+
+```
+{memoryConfig.basePath}/
+  orchestrator-session-{sessionId}.md
+  task-board-{sessionId}.md
+  progress-{agentId}-{taskId}-{runId}-{sessionId}.md
+  lessons-{sessionId}.md
+  experiment-ledger-{sessionId}.md
+
+.agents/results/
+  result-{agentId}-{taskId}-{runId}-{sessionId}.md
+```
+
+`taskId` and `runId` are required for plan-based work. A manual run may use a
+generated local run ID. Never use workspace or agent ID alone as artifact
+identity. Receipts remain in `.agents/state/agent-runs/` and retain their
+existing structured schema. Reports are independent of `memoryConfig.basePath`.
+
+Existing reports under `.agents/state/memories/`, the configured memory base, or `.serena/memories/` remain read fallback until migration. Write new reports only to `.agents/results/`, preserving task/run/session filenames. Do not move structured claims or manually rewrite verification receipts when relocating reports.
+
+## On Start
+
+1. `[READ]("task-board-{sessionId}.md")` to confirm your assigned task
+2. `[WRITE]("progress-{agentId}-{taskId}-{runId}-{sessionId}.md", initial progress entry)` with Turn 1 status
+
+## During Execution
+
+- Every 3-5 turns: `[EDIT]("progress-{agentId}-{taskId}-{runId}-{sessionId}.md")` to append a new turn entry
+- Include: action taken, current status, files created/modified
+
+## On Completion
+
+- `[WRITE](".agents/results/result-{agentId}-{taskId}-{runId}-{sessionId}.md")` with final result including:
+  - Status: `completed`, `partial`, `blocked`, or `failed`
+  - Summary of work done
+  - Files created/modified
+  - Acceptance criteria checklist
+
+## On Failure
+
+- Still create the run-scoped result with an accurate status.
+- Include detailed error description and what remains incomplete
+
+---
+
+## Experiment Tracking (Optional Extension)
+
+When a task compares an actual experiment, use `../conditional/experiment-ledger.md` for recording and `../conditional/quality-score.md` for comparable measurements. Routine verification does not require a ledger.
+
+Use `experiment-ledger-{sessionId}.md` under the configured coordination store. The coordinator merges task/run-scoped agent results into this shared artifact; parallel workers do not append concurrently. Link baseline and candidate evidence, required check results, the decision and reason, and owned paths. No composite score, fixed row layout, or agent ranking is required.
+
+---
+
+## Example with Default Tools (Direct File)
+
+```
+# On Start
+Read(".agents/state/memories/task-board-session-20260405-100835.md")
+Write(".agents/state/memories/progress-backend-task-api-run-01-session-20260405-100835.md", initial_content)
+
+# During Execution
+Edit(".agents/state/memories/progress-backend-task-api-run-01-session-20260405-100835.md", turn_update)
+
+# On Completion
+Write(".agents/results/result-backend-task-api-run-01-session-20260405-100835.md", final_result)
+```
+
+## Example with Custom Tools
+
+If `memoryConfig.tools` is configured differently:
+
+```json
+{
+  "memoryConfig": {
+    "tools": {
+      "read": "fs_read",
+      "write": "fs_write",
+      "edit": "fs_patch"
+    }
+  }
+}
+```
+
+Then use:
+```python
+fs_read("task-board-session-20260405-100835.md")
+fs_write("progress-backend-task-api-run-01-session-20260405-100835.md", initial_content)
+fs_patch("progress-backend-task-api-run-01-session-20260405-100835.md", turn_update)
+fs_write(".agents/results/result-backend-task-api-run-01-session-20260405-100835.md", final_result)
+```

package/skills/_shared/runtime/result-contract.md

@@ -0,0 +1,64 @@
+# Agent Result Contract
+
+`oma agent spawn` and `oma agent parallel` create a unique run and inject its result path. Use `--task-id` on spawn to match the session plan. A process exiting zero without a valid claim is `partial`, and a failed process is `failed`.
+
+Native agents use the same contract:
+
+1. Define the acceptance contract in the session plan (see below), then run `oma agent begin <agent-id> <task-id> <session-id>` from the project root. Save `runId` and `claimPath` from its JSON output.
+2. Load task references with `oma agent context <agent-id> --difficulty Medium`, perform the task, and execute its pinned checks with `oma agent verify <run-id> --required`. Spawn/parallel already inject this graph-selected context. Individual exact commands can also be recorded with `oma agent verify <run-id> -- <executable> <args...>`. Run checks serially per run. No build unless explicitly requested.
+3. Write the claim file with `status` (`completed`, `partial`, `blocked`, or `failed`), `changedFiles` (relative paths), `unresolved` (descriptions), and `artifacts` (relative paths to reports). A non-executable review may use `verificationSkipped` with a specific reason; it cannot override failed checks.
+4. Native agents call `oma agent finish <run-id> <claim-file>`. Spawned processes leave finalization to the parent. The parent captures the actual exit code.
+
+Example claim:
+
+```json
+{"status":"completed","changedFiles":["src/parser.ts"],"unresolved":[],"artifacts":[".agents/results/result-qa-s1.md",".agents/results/plan-s1.json",".agents/state/memories/session-ultrawork.md"]}
+```
+
+Receipts live in `.agents/state/agent-runs/`. They contain session/task/run IDs, vendor, workspace, timestamps, actual command argv and exit codes, working tree hashes, artifact hashes, unresolved work, and final status. These records prevent accidental reuse of stale evidence; they are local files, not a security boundary against an agent that intentionally edits receipts. Human-readable workflow reports are supplemental files at `.agents/results/result-{agentId}-{taskId}-{runId}-{sessionId}.md` for every dispatch path; the injected claim path and receipt schema remain unchanged. Preserve report filenames. Existing reports under configured coordination memory, `.agents/state/memories/`, or `.serena/memories/` remain read fallback until migration; write new reports only to `.agents/results/`.
+
+The Ralph gate requires QA and REFINE task IDs in a nonempty plan, current successful executable checks, and report/plan/phase artifacts bound to those runs. A waiver alone does not pass this gate. Record a justified REFINE exception as `REFINE skipped: <specific reason>` before QA finalizes its evidence. Old Markdown-only reports remain readable but must be reverified to pass the gate.
+
+Checks cover the Git working tree (HEAD, tracked contents/modes and nonignored untracked files). Generated `.agents/state`, `.agents/results`, and `.serena/memories`, and generated `.opencode/agents/oma-spawn-*.md` / `.kilo/agents/oma-spawn-*.md` wrappers are excluded from the tree hash and artifacts are hashed separately. In an unversioned directory, all files except those generated directories, `.git`, and `node_modules` are covered. External services, ignored dependencies, and malicious receipt tampering require separate controls.
+
+## Artifact storage
+
+- `docs/decisions/`: retained approach proposals, architecture decisions, and ADRs intended for version control; update `docs/decisions/index.md`. `design` names UI work. Read `docs/plans/designs/` and `docs/design-docs/` only as legacy fallback until migration.
+- `docs/plans/work/`: execution plans and technical debt; `docs/plans/contracts/`: adopted API contracts. Keep their existing lifecycle and promotion rules.
+- `.agents/results/`: run-specific reports, research, explanations, and draft contracts. When promoting a selected document into `docs/`, leave its destination in the source report.
+- `.agents/state/`: coordination, resumption, and verification records. State notes link reports instead of holding duplicate report bodies.
+
+If a report is already bound to a verification receipt, preserve its original path and bytes. Create a maintained copy and link it from the documentation index instead of editing or moving the bound report. Migration reports these files as deferred and never rewrites receipts, claims, or frozen plans.
+
+Preview existing files with `oma docs migrate --dry-run --json`; apply the migration with `oma docs migrate`. The report lists moved and rewritten paths, skips, and conflicts.
+
+## Coordination notes
+
+Use native file tools and `memoryConfig.basePath` (default `.agents/state/memories/`) at the project root for optional coordination notes. Read an assigned task board and report progress for long tasks. Use the unique progress names from [Memory Protocol](memory-protocol.md); keep the injected claim path unchanged. Write all `result-*.md` reports in the project-root `.agents/results/`, independently of `memoryConfig.basePath`. Their presence alone does not prove completion. Include unresolved work in the claim even after failure.
+
+Read-only dispatch returns `OMA_RESULT_JSON: {claim}` as one final stdout line. The parent persists that inspection. A `verificationSkipped` inspection remains distinguishable from executable checks and does not pass Ralph.
+
+Repository checks: `cli/state/agent-results.test.ts`, `cli/state/artifact-verifier.test.ts`.
+
+## Acceptance and recovery
+
+Each executable task declares `acceptance_criteria: [{id, description}]` and `required_checks: [{id, criteria: [criterionId], command: [executable, ...args], cwd: "."}]`. Every criterion needs a check. Check IDs and executable/argv/cwd selectors must be unique. The run snapshots this contract. Another command/directory, a removed requirement or an uncovered criterion cannot count as acceptance evidence. Legacy plans without required checks remain readable but need a new contract/run to pass executable completion.
+
+`oma agent verify RUN_ID --affected PATH...` executes tests selected from actual graph references and records outcomes. They count toward acceptance only when matching pinned checks. Use `--required` for all declared checks. Unmatched paths and empty graph test selections fail explicitly.
+
+Optional `inputs` narrows hashing to declared project-relative files/directories and must include all relevant source, tests, configuration and dependency inputs. Missing/deleted inputs change the hash. No globs or symlink traversal are supported. Omit it for whole-tree hashing. The contract is checked independently of scope. Task dependency IDs use the existing `dependencies` array.
+
+`oma agent resume SESSION_ID --dry-run` reports reused, ready, running and blocked tasks. Without `--dry-run`, it retries ready tasks in dependency order, persists outcomes, and revalidates evidence before success. Changed dependencies invalidate dependent reuse even if their own inputs match. Live managed processes and native attempts without liveness evidence are not duplicated.
+
+Automatic replay requires `retry_policy: "safe"` and a prompt/agent in the plan or saved dispatch. The default is `manual`. `--max-attempts` defaults to 3 including the original attempt. A session lease prevents duplicate coordinators and permits recovery after the local owner dies. Mark interrupted native attempts partial/failed through their result contract before resuming. Keep the JSON plan fixed while recovery runs; record progress separately. This resumes tasks, not the model's interrupted conversation.
+
+## Plan lineage and evidence failures
+
+The plan's optional `lineage_id` defaults to its session ID. Keep it stable for the same workflow goal across resumed sessions. A task's optional `goal_id` defaults to its task ID; predeclared alternative task IDs for the same logical work must share it. Plan `max_attempts` defaults to 3 including the original attempt. Direct begin/spawn and resume count all runs for that lineage/goal, including runs without `resumedFrom`. `resume --max-attempts` can lower, but cannot raise, the frozen plan's bound.
+
+First dispatch pins the full plan under `.agents/state/agent-plans/`. Task IDs, prompts, dependencies, checks, scope, and retry limits are immutable. JSON formatting/key order and transport `session_id`/`created` metadata do not change the contract. Progress belongs in coordination notes. Unknown task IDs and dependency cycles fail before dispatch. Contract changes require an explicitly separated new session and lineage; record why the scope changed and preserve the prior run's outcome. Never use a new lineage to evade a retry limit or repair metadata for the same goal. Do not insert tasks that recursively regenerate/review the executing plan.
+
+- `PRODUCT_FAILURE`: executable checks failed, product inputs changed, or product work remains unresolved. Retry only within the shared goal budget.
+- `WORKFLOW_EVIDENCE_FAILURE`: current product checks pass but a claim, artifact binding, or completion metadata is invalid. Automatic resume blocks product replay and returns the run/claim paths. One direct begin/spawn for that existing task may repair metadata within the same attempt budget; the run is marked `evidenceRepair`, and completion rejects product-input changes. Correct claim/report bindings and reverify the pinned checks, without changing the plan or dispatching planners/reviewers. A second evidence repair is rejected. If unresolved, stop with `partial`, distinguish product success from workflow failure, and provide the exact diagnostic and correction needed.
+
+Keep mutable task boards, phase logs, receipts, and repair notes under `.agents/state/`, `.agents/results/`, or `.serena/memories/`, which are excluded from product hashes. They may be bound as separate artifacts only after their final update; a later metadata edit invalidates that binding without making it a product failure. Do not narrow product `inputs` to hide relevant source changes.

package/skills/_shared/ui-interaction-quality.md

@@ -0,0 +1,133 @@
+# UI Interaction Quality
+
+Load the relevant sections when changing motion, input feedback, or rendered
+web-component behavior. Static document corrections do not require this resource.
+Follow existing project conventions; native implementation uses `oma-mobile`.
+
+## Decide what the interaction needs
+
+`oma-design` owns the intended behavior and its effect on the user:
+
+- Name the purpose: acknowledge input, show a state change, explain a spatial
+  relationship, preserve continuity, or support an explicitly requested effect.
+  Keep a direct state change when motion adds no useful information.
+- Consider how often the interaction occurs and whether it blocks the next
+  action. Repeated work and keyboard-driven workflows need prompt, unobstructed
+  feedback; occasional explanatory moments can support more expression.
+- Keep content stable while the user reads, compares, selects, or acts on it.
+  Decorative movement must not compete with task information or conceal state.
+- Define the reduced-motion result with the behavior. Preserve essential state,
+  feedback, and control when movement is reduced or removed.
+- Reuse the approved project direction, motion tokens, and component behavior.
+  Specify the affected states and acceptance criteria rather than imposing a new
+  timing scale, spring table, or page-wide motion quota.
+
+Use the supplied brief and inspected UI to make these decisions. Ask only about
+a material unresolved choice. An audit returns findings within its read-only
+scope; an implementation request proceeds under the existing authorization.
+
+## Implement within the current stack
+
+`oma-frontend` owns the implementation. First inspect the component primitives,
+existing motion mechanisms, tokens, and affected lifecycle. Extend a suitable
+existing mechanism before adding a second one.
+
+| Mechanism | Relevant use |
+|---|---|
+| CSS transitions or animations | Stylesheet-driven changes and predetermined motion that need no additional controller |
+| Web Animations API | Browser-native imperative playback, cancellation, or sequencing where it fits the required behavior |
+| Project-selected Motion integration | Supported spring, layout, entry/exit, or gesture behavior in the project's current component architecture |
+| Existing or selected GSAP integration | Its timelines, scroll coordination, or plugins when those capabilities are part of the task |
+
+This table identifies capabilities, not an automatic dependency choice. A fade
+does not justify installing an engine. Preserve the project's framework,
+component library, styling, state, and dependency policy.
+
+### State and interruption
+
+An interaction may reverse, repeat, or be cancelled before a transition ends.
+Continue from the currently displayed position and velocity where appropriate,
+rather than resetting to an obsolete starting frame. Keep one owner for each
+animated property and cancel or supersede stale work.
+
+Keep semantic state authoritative. A visual exit must not leave a hidden control
+active, preserve stale content after reopening, or lose the intended focus
+destination. Use the existing component's state and lifecycle contracts instead
+of adding an independent animation state machine without a demonstrated need.
+
+In React, keep continuous visual values outside component render state when they
+do not change the UI's meaning. Use the existing controller, motion values, or
+refs for those updates. Commit meaningful state changes through the normal React
+model; do not force a render for every animation frame or pointer sample merely
+to move an element.
+
+### Press, focus, hover, and touch
+
+- Give prompt press feedback through the project's control primitives. Feedback
+  on pointer-down is distinct from committing an action: preserve cancellation,
+  click/activation semantics, and keyboard behavior.
+- Keep focus visible and stable through transitions. Exercise keyboard entry,
+  activation, dismissal, and return focus where the component supports them.
+- Gate hover-only decoration by input capability. Keep essential information
+  and actions available to touch and keyboard users; support mixed input devices
+  without assuming a screen width or user-agent identifies the input method.
+- Preserve zoom, browser scrolling, and text interaction. Scope gesture handling
+  and selection restrictions to the control that needs them.
+- Verify pending, disabled, success, and failure feedback where those states
+  exist. Appearance alone must not substitute for the component's actual state.
+
+### Component lifetime
+
+Tie controllers, frames, listeners, observers, timers, and subscriptions to the
+component lifetime. Use the incumbent integration's cleanup mechanisms; cancel
+obsolete work on unmount or replacement. Check repeated mount/unmount and rapid
+open/close for duplicate handlers, stale callbacks, and continuing animations.
+Pause nonessential continuous work when the surface is inactive when appropriate.
+
+## Diagnose performance from evidence
+
+Reproduce the affected interaction with representative content and concurrent
+work. Inspect browser profiling, renders, layout, paint, and compositing as the
+symptom requires. Compare frame work with the actual target device's budget;
+do not infer smoothness from a library name or a desktop screenshot.
+
+Transforms and opacity often avoid layout work, but acceleration depends on the
+actual property, browser, controller, and content. Check costly descendants,
+inherited custom-property updates, effects, and large layers before choosing a
+fix. Add layer promotion or `will-change` only for an observed need, then verify
+the effect and resource cost.
+
+Measure the affected case before and after a proposed performance fix. Record
+the browser/device, content, steps, relevant trace or observation, and remaining
+limits. Emulation and code inspection can support findings; they do not prove
+behavior on an untested physical device.
+
+## Exercise realistic content and states
+
+Use fixtures at the component's real data boundary and container size. Derive
+limits from the schema, API, validation, and supported product behavior. Mark an
+unknown limit as unknown; use plausible stress data without inventing product
+claims or introducing real personal data into a fixture.
+
+Select cases relevant to the affected UI:
+
+- Long and short names, unbroken identifiers, translated labels, CJK text and
+  mixed scripts. Check glyph fallback, line breaking, wrapping, and readable
+  control labels with the project's actual fonts and supported languages.
+- Empty, single-item, and realistic large collections; absent optional fields,
+  unavailable images, and the number/date formats the product supports.
+- Loading, failure, retry, disabled and successful states; repeated activation,
+  cancellation, reopening, and interruption while content or layout changes.
+- Supported narrow containers, zoom/text enlargement, themes, directionality,
+  and input modes. Include keyboard, touch, safe-area, or software-keyboard
+  behavior when the changed surface depends on them.
+
+Keep meaning and essential values accessible when space is tight. Use the
+project's existing wrapping, disclosure, scrolling, or truncation conventions
+according to the data's purpose. An optional debug fixture or prototype stays
+outside production flows unless the task explicitly includes it.
+
+Report what was exercised and observed, including the component/state, content,
+viewport or input, and result. Separate rendered findings from code-only
+inferences and unrun checks. Keep fixes within the authorized scope and repeat
+the affected checks after a change.