oma-translation

어떤 스킬인가요?

Translate or revise localized UI strings and prose while preserving

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# Experiment Ledger

Load when comparing an actual hypothesis with a baseline or another approach. Routine implementation, formatting, and every failed check do not require experiment bookkeeping.

## Location and ownership

Use `../runtime/memory-protocol.md` for the configured coordination store. The default is `.agents/state/memories/experiment-ledger-{sessionId}.md`. The coordinator maintains the shared ledger; parallel agents write task/run-scoped results for the coordinator to merge, avoiding concurrent edits to the same table. Reuse an existing experiment artifact when it already carries the evidence.

## Record a comparison

1. State the hypothesis, affected scope, baseline revision, and success criteria before changing behavior.
2. Capture comparable baseline and candidate measurements as described in `quality-score.md`. Preserve required binary checks and raw evidence paths.
3. Record the decision and reason: retain, repair, discard, or inconclusive. A missing or noisy measurement is not a loss. Do not rank unrelated tasks or agents by average score delta.
4. If discarding, remove only changes owned by that experiment after inspecting the diff. Preserve user edits, other agents' work, and useful failure evidence.

Suggested fields, not a parsed schema:

| Experiment / task / run | Hypothesis | Baseline evidence | Candidate evidence | Required checks | Decision and reason | Changed paths |
|---|---|---|---|---|---|---|
| IDs from active run | Specific mechanism | Revision and report | Revision and report | pass / fail / missing | retain / repair / discard / inconclusive | Owned files |

Keep units and comparison criteria beside metric deltas. A scalar composite is optional only when the project already defines and computes it; there is no OMA default formula.

## End of an experiment

Summarize the selected approach, unresolved limits, and evidence. A discarded attempt becomes a lesson only when its cause and reusable prevention are understood (`../core/lessons-learned.md`). Do not generate lessons or modify canonical skills from a numeric threshold.

The ledger records work; it does not grant more retries, spending, commits, or permission to remove workspaces. Those follow the active task budget and `../core/execution-policy.md`.

# Hypothesis Exploration

Load when the user requests alternative approaches, or when the same issue persists after repeated relevant recovery and a different mechanism is worth testing. A failed check count is a prompt to reassess the cause, not an unconditional launch signal. Do not activate for an obvious fix or a noisy metric delta.

## Scope and budget

Use the task's existing aggregate attempt and cost budget. Each hypothesis consumes an attempt; exploration never replenishes retries. For a comparison round, reserve all intended attempts before starting. If the existing workflow requires a multi-candidate round and fewer than two attempts remain, preserve evidence and report the unresolved result instead of starting a partial round. Explicit user, runtime, and workflow limits take precedence; this guide does not add turn quotas or file-count caps.

## Procedure

1. Inspect prior failure evidence. State distinct causal hypotheses and the smallest experiment that distinguishes them. Use only as many alternatives as the uncertainty and budget justify; the active workflow may specify the candidate count.
2. Identify ownership, baseline revision, required checks, comparison metrics, and artifact paths before editing. Include tests and related files needed to evaluate the mechanism; a fixed file limit must not hide impact.
3. Isolate alternatives. In authorized multi-agent work, use separate prepared workspaces and preserve the plan task ID and unique run ID in each result. In sequential work, preserve a baseline and apply only the experiment's scoped diff. Do not use a blanket stash, reset, checkout, or cleanup against a workspace with unrelated changes.
4. Run relevant checks and comparable measurements under `quality-score.md`. Missing evidence remains missing; a candidate with failing required checks cannot win through a higher aggregate score.
5. Select a candidate only when it satisfies the required behavior and comparison criteria. Apply its owned changes to the target, then refresh affected verification on the integrated result. Preserve diagnostic evidence from other candidates; do not delete unrelated work or an active workspace.
6. Record the comparison and decision in `experiment-ledger.md`. If no candidate resolves the issue, report the evidence and remaining limitation. Continue only within the existing recovery budget and authorized scope.

## Workflow integration

`/work`, `/orchestrate`, and `/ultrawork` retain their dispatch, required review, and recovery limits. They call this procedure after reassessing a repeated failure, then re-evaluate the failed gate using actual acceptance evidence. This guide does not start a workflow or delegate work by itself.

Use `../runtime/result-contract.md` for task/run/claim identity and `../core/execution-policy.md` for authorization, clarification, and completion.

# Quality Measurements

Load when the task or active workflow needs a measured baseline or experiment comparison with defined metrics. The mere presence of tests or lint does not activate a scoring phase. Ordinary verification uses the applicable checks directly.

## Preserve independent acceptance gates

Tests, authorization/security requirements, and project acceptance criteria remain independent gates. A performance improvement cannot offset a correctness or security failure. Do not assign default weights, convert checklist completion into a security score, or trigger rollback from an arbitrary grade.

<!-- oma-docs:ignore-start -->
OMA does not implement a loader for `.agents/config/quality-score.yaml` or a universal composite scorer. If a project already provides a scoring command, record its formula, inputs, applicability, and output; do not infer configuration support from a sample path. A project composite may supplement the evidence but cannot waive mandatory checks.
<!-- oma-docs:ignore-end -->

## Measure a comparable baseline

1. Define the behavior, metric, units, direction, scope, and acceptance threshold from the task or project. Use the same command, dataset, environment, and measurement method before and after.
2. Reuse still-current verification artifacts. When new measurements are needed, capture the command's exit status and structured output (JSON, JUnit, SARIF, LCOV, or project equivalent). Do not infer totals from truncated console text.
3. Record the artifact path and revision/run identity with the result. Mark unavailable measurements as missing with a reason; estimates are labeled and excluded from measured comparisons.
4. Compare each applicable measure and check result. For noisy metrics, use the project's sampling/tolerance method; a single timing sample does not prove a regression.
5. Keep a change when it meets required behavior and comparison criteria. Investigate a regression before deciding whether to repair or discard the experiment; preserve unrelated work. Record a material tradeoff when requirements permit it.

For an actual experiment, use `experiment-ledger.md`. Ordinary test passes do not require a ledger row or a new measurement at every phase. Re-measure only affected metrics after relevant changes, failures, or uncertainty.

## Evidence record

Use existing result artifacts or a compact table such as:

| Measure | Baseline | Candidate | Method / evidence | Verdict |
|---|---|---|---|---|
| Required tests | pass | pass | exact command, exit status, report paths | pass |
| Request p95 latency | measured ms | measured ms | same workload, environment, sample method | within target / regression / inconclusive |
| Security finding | finding ID | remediation status | reproduction and verification paths | resolved / unresolved |

Report missing evidence without inventing a score. Authorization, builds, verification, and completion follow `../core/execution-policy.md`.

# Shared prose diagnostics

Load for academic prose audits and translation style reviews, together with the
owning skill's domain rules. Meaning, evidence, required structure, and target-language
conventions take precedence over these style diagnostics.

## Editing and review contract

Read the whole passage and identify its point, audience, and existing voice. Make only
changes that correct a supported defect. Keep useful details, uncertainty, and clear
sentences. Do not invent facts, examples, numbers, opinions, humor, or personality to
make writing seem more human. Reorganize only when the current order impairs understanding.

In review-only mode, name the pattern, quote the affected text, explain the defect,
and suggest a local fix. Do not rewrite the full draft or infer AI authorship from
style. Zero findings is valid. The owning skill controls its domain report format;
an evidence or translation-quality score is not an AI-authorship probability.

Apply domain-specific exceptions; do not enforce word bans or stylistic
preferences as universal rules.

## Common patterns

Target-language grammar and typography remain in the translation resource.
Refer to patterns by heading name, not by position in this file.

### Inflated significance

Replace claims of importance with the supported action, result, or consequence.
Do not describe an ordinary change as a milestone without evidence.

### Superficial analysis

A trailing clause such as `highlighting its importance` needs an actual explanation
or evidence. Remove it when empty; retain substantive causal or analytical content.

### Promotional tone

Remove unearned praise and claims of novelty. Match the evidence and intended register.

### Mannered prose

Prefer a literal statement when metaphor or flourish obscures the meaning. Do not
replace one decorative metaphor with another. The owning skill determines how to
handle an author's intentional figurative language.

### Vague attribution

Identify the available source of a claim. Do not replace a named source with an
anonymous consensus or invent a source to repair an unsupported statement.

### Authority padding

Keep relevant credentials and coverage only when they support a concrete claim.
Remove unsupported prestige claims and publication lists used as praise.

### Generic endings

Remove formulaic optimism and redundant recaps. End with a supported result,
limitation, implication, or next action. Preserve a required conclusion or abstract.

### Vocabulary clustering

Look for clusters of vague or inflated wording, including `delve`, `leverage`,
`foster`, `pivotal`, `seamless`, `tapestry`, and `groundbreaking`. Judge the meaning
in context; a technical term is not defective because it appears on a list.
Language-specific examples and domain thresholds belong to the owning resource.

### Unnecessary verb inflation

Keep ordinary verbs such as `is`, `has`, and `uses` when accurate. Replace them only
when a different verb states a useful distinction supported by the content.

### Mechanical triples

Remove stacked descriptors that repeat praise. Keep three items when each adds
information; list length alone is not a defect.

### Synonym cycling

Use one term for one concept. Do not rotate labels merely to avoid repetition.

### Rhetorical contrasts

State the claim directly when a negative contrast or repeated negation adds only
drama. Retain contrasts that distinguish real alternatives or necessary exclusions.

### Compound adjective stacking

Unpack stacked compound modifiers when they obscure what the subject does.
Keep established technical terms and meaningful distinctions.

### Abstract noun and adjective stacking

Replace vague descriptive clusters with a concrete action or property already
supported by the passage. Do not remove necessary technical precision.

### False ranges

Use a range only when its endpoints define a meaningful scale or scope.

### Decorative bold

Avoid mechanical emphasis. Use formatting that helps the reader locate information.

### Decorative dashes

Express the relationship between clauses with suitable grammar and punctuation.
Do not use dashes as a repeated rhythm device. Domain and locale rules set limits.

### Mechanical punctuation swaps

Replacing a dash with a colon or parentheses does not repair unclear syntax.
Rewrite the relationship when punctuation alone cannot express it.

### Heading case

Follow the document's required heading convention and target-language typography.

### Unnecessary tables

Use tables for information readers need to compare or look up, when the format allows.

### Mini-heading lists

Do not turn short prose into a series of bold labels and explanations without a
reading or reference need.

### Emoji decoration

Do not add emoji as ornament. Preserve content or UI conventions where required.

### Heading warmups

Remove a sentence that merely repeats the heading before the actual content begins.

### Chatbot artifacts

Exclude conversational acknowledgments and offers of further help from deliverable
prose unless they are themselves the requested content or quoted source material.

### Empty metadiscourse

Remove sentences telling readers a point matters when the passage already shows
why. If the explanation is missing, provide existing evidence instead of emphasis.
Keep uncertainty that reflects the evidence or the author's intended meaning.

### Announced exposition

Remove introductory announcements that delay the subject without adding context.
Keep introductions that define scope or help readers follow a necessary transition.

### Unsupported insight claims

Remove claims that the writer alone sees a hidden truth. Present the argument and
its support without asserting that everyone else missed it.

### Boilerplate limitations

Remove generic availability or knowledge disclaimers. Keep actual source limitations
and uncertainty relevant to the claim.

### Filler and indirect verbs

Shorten empty phrases and use direct verbs where meaning survives. Preserve a
qualifier when it carries uncertainty, emphasis, or a necessary distinction.

### Mechanical rhythm

Repair repeated sentence shapes when they impede reading. Preserve clear variation
and an author's characteristic cadence. Do not impose identical paragraph shapes
or insert fragments solely to create variation; domain structure rules still apply.

### Portability test

Check whether a sentence could describe an unrelated subject with only its name
changed. If so, determine whether it adds necessary context or merely generic praise.
Replace empty wording with an available mechanism, observation, consequence, or
example; otherwise remove it where editing scope permits. Never fabricate detail.

### Dramatic reveals and rhetorical questions

Remove a question answered immediately for effect, or a label followed by a colon
that delays a plain claim. Keep real research questions, definitions, labels, and
structural colons when the domain allows them.

### Performative endings and fragments

Remove an unsupported aphorism, decorative metaphor, or sequence of punchy fragments
at the end. Finish on a concrete sentence already supported by the passage. Preserve
intentional source cadence in translation and required academic conclusions.

# API Contracts

This directory owns the optional contract template, not generated API specifications. Reuse the project's existing OpenAPI, schema, or other authoritative contract before creating a parallel Markdown specification.

## When a contract artifact helps

Create or update a contract when a changed API boundary needs coordination between producers and consumers, or the task explicitly requests a specification. A scoped implementation against an existing contract does not require a PM task or a new document.

| Artifact | Location |
|---|---|
| Transient coordination contract | `.agents/results/api-contracts/{domain}.md` |
| Durable project specification, if no existing location applies | `docs/plans/contracts/{domain}.md` |
| Reusable format example | `template.md` in this directory |

Use task/session-specific domain names for independent runs that could otherwise overwrite the same transient file. Follow assigned artifact paths when supplied. Read and write with available file tools; no memory MCP is required.

## Authoring and use

1. Identify the authoritative schema and affected consumers. The assigned API owner can define the contract; PM involvement is useful for unresolved product requirements.
2. Document changed operations: method/path, input fields and validation, success/error schemas, authentication and authorization, and relevant compatibility requirements.
3. Share the contract path with affected assigned agents through the workflow's authorized coordination channel. Resolve incompatible expectations before dependent implementation. A separate approval ceremony is unnecessary when the existing contract and task already settle them.
4. Implement and verify producer/consumer compatibility with applicable schema checks, generated clients, or integration tests. If a contract changes, update its source and affected consumers within scope.

## Completion

The changed boundary is explicit, consumers can use it, and applicable compatibility checks support the result. Include pagination, rate limits, timestamp formats, and migration/deprecation behavior only when relevant. Do not invent JWT authentication, CRUD endpoints, a database, or error codes merely because the template includes an example.

Follow `../execution-policy.md` for authorization and verification. Transient artifacts do not belong in this source directory; durable specifications follow the repository's tracking policy.

# {Domain} API Contract

> Author: {assigned-owner} | Session: {session-id} | Date: {YYYY-MM-DD}

Use only the operations and fields needed by the actual contract. The CRUD, UUID, ownership, and pagination examples below are placeholders, not required architecture.

## Base URL
`/api/{domain}`

## Authentication
{Actual authentication scheme, public operations, and per-operation authorization rules. Preserve the project contract; do not assume JWT.}

---

## Endpoints

### POST /api/{domain}
- **Description**: Create a new {resource}
- **Auth**: Required
- **Request Body**:
  ```json
  {
    "field1": "string (required)",
    "field2": "number (optional, default: 0)"
  }
  ```
- **Response 201**:
  ```json
  {
    "id": "uuid",
    "field1": "string",
    "field2": 0,
    "created_at": "2024-01-01T00:00:00Z"
  }
  ```
- **Errors**: 401, 422

### GET /api/{domain}
- **Description**: List {resources} (paginated)
- **Auth**: Required
- **Query Params**: `page` (default: 1), `size` (default: 20)
- **Response 200**:
  ```json
  {
    "items": [...],
    "total": 100,
    "page": 1,
    "size": 20
  }
  ```

### GET /api/{domain}/{id}
- **Description**: Get single {resource}
- **Auth**: Required
- **Response 200**: Single resource object
- **Errors**: 401, 404

### PATCH /api/{domain}/{id}
- **Description**: Update {resource}
- **Auth**: Required (owner only)
- **Request Body**: Partial update fields
- **Response 200**: Updated resource object
- **Errors**: 401, 403, 404, 422

### DELETE /api/{domain}/{id}
- **Description**: Delete {resource}
- **Auth**: Required (owner only)
- **Response 204**: No content
- **Errors**: 401, 403, 404

---

## Data Models

### {Resource}
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | UUID | auto | Primary key |
| field1 | string | yes | Description |
| field2 | number | no | Default: 0 |
| user_id | UUID | auto | Owner (FK to users) |
| created_at | datetime | auto | ISO 8601 |
| updated_at | datetime | auto | ISO 8601 |

---

## Notes
- Pagination: offset-based (page/size)
- Sorting: `?sort=created_at&order=desc` (optional)
- Filtering: `?field1=value` (optional)

# Clarification Protocol

Apply [Execution Policy](execution-policy.md) before deciding whether to ask.

| Situation | Action |
|-----------|--------|
| Goal and authorization are clear; routine details remain | Use repository conventions, state consequential assumptions, proceed |
| A preference could improve the result | Ask one concise optional question and continue independent work |
| Missing information materially changes correctness or scope | Ask the specific question; pause only the dependent work |
| An action requires authorization not already given | Prepare the reviewable result, explain the action and reason, then ask |

Check prior messages, project configuration, and existing behavior before asking. The presence of tradeoffs, an existing-code conflict, or subjective wording alone is not a blocker. Do not add authentication, a database, or a framework solely because a generic checklist has a default.

## Question transport

- When clarification, a preference, or approval is needed, prefer the runtime's asynchronous user-question tool when available and permitted for that purpose. Otherwise use an available question tool or one concise plain-text question, respecting the runtime's mode and tool restrictions.
- Ask one focused question at a time. For approval, first present the concrete result and explain which action needs authorization and why; the question must be understandable on its own.
- Continue independent, authorized work while an answer is pending. Pause only the work that depends on required information or approval.
- Silence, elapsed time, and a preselected option are not approval. Keep required questions pending until the user explicitly answers; do not repeat an unanswered question through multiple channels.
- For an optional preference, allow a reasonable opportunity to answer, then state an assumption and proceed if necessary. An optional question must not become an approval gate.
- Vendor execution protocols map this policy to tools exposed in the current session; do not assume every vendor provides the same tool name.

Subagents report the exact missing fact and any independent work completed in a structured `blocked` or `partial` result. The coordinator answers from existing context where possible and asks the user only when necessary.

# Common Code Quality Checklist

Use applicable sections for a cross-domain review. Check the changed behavior and affected boundaries; this list does not expand the task or override project checks. Authorization and verification scope follow `execution-policy.md`.

## Correctness and maintenance
- [ ] Behavior matches acceptance criteria and existing contracts.
- [ ] Names and structure follow the project; complexity does not obscure the changed behavior.
- [ ] No required behavior is left as a stub or unresolved task-created TODO. Existing tracked debt does not block unrelated work.
- [ ] Generated artifacts are updated through the project's generator when required.

## Error handling
- [ ] Failure paths propagate to an appropriate handler or error boundary; no swallowed rejection or silent data loss.
- [ ] User-facing errors are actionable without exposing internal or sensitive data.
- [ ] Recovery, cancellation, and cleanup work where the change depends on them.

## Security
- [ ] No secrets in code, logs, error messages, or staged files.
- [ ] Untrusted input is validated and handled safely at SQL, shell, and HTML boundaries.
- [ ] Protected operations enforce authentication and authorization at the relevant trust boundary.

## Verification
- [ ] Tests assert affected behavior and relevant failure or boundary cases.
- [ ] Required project checks pass, or missing evidence and its impact are reported.
- [ ] For changes where automated tests add little value, applicable inspection or static checks support the result.

## Change hygiene
- [ ] Changes stay within scope and preserve unrelated work.
- [ ] When committing is requested, staging follows repository rules, including whether generated artifacts are tracked.

# Context Budget

Keep the context relevant to the current task. Prefer scoped search and reads for large files; read a whole file when its size or the review scope makes that useful. Re-read changed content when needed to verify current behavior.

## Measure actual loading

`bun scripts/measure-skill-context.ts` reports file-size estimates using UTF-8 bytes / 4. It is not an Astra tokenizer or a live usage measurement. The routed tier is the entry skill; resource tiers are comparison scenarios, not instructions to preload those files. Generated vendor aliases are not independent prompt copies.

Measure the assembled prompt separately when changing injection. Include the owning entry, runtime contracts, task instructions, and any references actually supplied. The runtime retains a required entry even if it exceeds its soft budget and reports the overrun. Reduce that entry or select a narrower skill; do not silently drop its contract.

Use `oma skill audit` to find routing overlap and unusually large entries. Counts and thresholds are diagnostics, not proof of task utility. Keep measured summaries current rather than copying fixed claims about which skills exceed a limit.

## During a task

- Process bulk logs, datasets, and manifests through tools; return relevant excerpts, counts, and artifact paths.
- Load one platform or operation at a time. Error playbooks, examples, and experimental protocols remain conditional.
- Record important decisions and remaining work in durable state for long tasks. Do not maintain a separate file-read ledger for a trivial edit.
- Before compaction or a restart, save completed work, remaining acceptance criteria, relevant paths, verification status, and material assumptions.
- Continue from that checkpoint. A turn estimate or elapsed time is not completion and does not require renewed approval.
- Restart an agent only for observed loss of useful context or stalled progress. Preserve its partial result and avoid duplicating a live attempt.

Authorization and completion follow `execution-policy.md`; run/claim identity follows `../runtime/result-contract.md`.

# Context Loading

Read the routed skill once. Its references are an index, not a preload list.

## Selecting context

- Start with the task, acceptance criteria, and the owning skill's SKILL.md.
- Read a supporting document only when its stated trigger applies. Existing project conventions take precedence over starter examples.
- Load execution-protocol.md when its selected operation needs command, schema, or recovery detail; its existence alone is not a trigger.
- Load only the selected framework or platform reference. Generated stack/ files describe the project; variants/ are starter material for /stack-set, not mandatory reading for existing-code edits.
- Consult relevant checklist sections for unresolved verification requirements. Read an error playbook only for the observed failure.
- Read difficulty-guide.md for decomposition decisions, not before every task. Difficulty does not activate extra skills or full checklists.
- Runtime transport, authorization, and result contracts are injected once by CLI dispatch. Native agents read those contracts if not already supplied.

## Conditional shared resources

| Resource | Load when |
|---|---|
| `../conditional/quality-score.md` | The task needs a defined baseline or experiment comparison |
| `../conditional/experiment-ledger.md` | Recording an actual experiment |
| `../conditional/exploration-loop.md` | Repeated recovery fails on the same issue and alternative mechanisms merit testing within budget, or the user requests exploration |
| `common-checklist.md` | A broad cross-domain review needs its applicable checks |
| `context-budget.md` | Managing a long task or diagnosing context overhead |
| `../runtime/memory-protocol.md` | Coordinating agents or resuming durable task state |

## Runtime selection

The graph records references, not permission to load them. The context loader injects the owning entry skill and defers its supporting references. Cross-routes to another specialist do not inject that specialist's body.

Difficulty selects a soft size budget. If the entry skill exceeds it, retain the entry and report the overrun. Do not replace it with smaller unrelated documents. Explicitly requested supporting references are checked against the graph and loaded within the remaining budget; deferred paths remain available for scoped reads.

## Subagent prompts

Pass the task ID, scope, acceptance criteria, material constraints, and relevant artifact paths. Identify the owning skill by path; do not paste its body if the runtime injects it. Pass a reference or guide section only when this task needs it. Preserve injected run/claim identity. Use `prompt-structure.md` when composing an unfamiliar handoff, not as another mandatory preload.

# Task Decomposition

Use this guide when scope or dependencies make the execution approach unclear. Routine changes do not need a difficulty report or a separate planning phase.

## Choose the amount of planning

| Task characteristics | Approach |
|---|---|
| Clear change following an existing pattern | Inspect the affected behavior, implement, and run relevant checks |
| Several coupled changes or a material design choice | Identify dependencies and acceptance criteria; resolve the choice before dependent edits |
| Multiple independently verifiable outcomes or uncertain boundaries | Break work into deliverables, each with its own implementation and verification |

File counts and estimated turns are hints, not gates. Many repetitive file edits can be straightforward; a one-line authorization change can need careful regression testing. The CLI's Simple/Medium/Complex classifier selects a context size budget; it does not prescribe review depth or activate other agents.

## Decompose around behavior

- Use as many deliverables as dependencies require, without a fixed sprint count or turn quota.
- Keep tests and error handling with the behavior they verify. For authentication plus CRUD, verify authentication with its endpoints before integrating and testing protected CRUD paths.
- Use the project's declared checks and `test-approach.md` where applicable. A broad audit may use relevant sections of `common-checklist.md`; complexity alone does not require every check.
- Delegate only when authorized and when independent work can proceed. Follow `skill-routing.md` for ownership, not a compulsory agent chain.

## Adjust during execution

If new dependencies emerge, update the remaining work and continue within the authorized scope. If the task is simpler than expected, finish without preserving unnecessary phases. For long tasks, checkpoint completed work and remaining evidence as described in `context-budget.md`.

Completion and authorization follow `execution-policy.md`. A turn estimate does not end the task or require renewed approval.

# Execution Policy

This is the shared OMA policy for authorization, clarification, verification, and completion. Workflows define steps; skills define domain methods; vendor protocols define transport. They refer here instead of defining different stop/approval rules. System and developer instructions and the user's current request take precedence over OMA defaults.

## Authorization and clarification

- Carry the user's requested work through implementation. Existing authorization persists; a plan review or proposed fix does not require another approval when that work is already authorized.
- Resolve routine, reversible implementation choices from repository conventions. State material assumptions and continue independent work while a question is pending.
- Ask only for information that changes the outcome or for an action outside the authorized scope. Pause only the dependent action. Before requesting new approval, prepare the concrete result for review.
- Use the [Clarification Protocol](clarification-protocol.md) for question transport: prefer an available asynchronous question tool and keep independent work moving. Never treat silence, elapsed time, or a default selection as approval.
- Do not infer permission to send messages, publish, spend beyond an agreed budget, destroy data, or expand scope. Conversely, do not request that permission again when explicitly granted.
- Never build, compile, bundle, or package software until the user explicitly asks for a build. Type checking without emission and relevant tests do not authorize a build.

## Resource budgets, cancellation, and monitoring

- Before expensive batches, downloads, installations, or long-running subprocesses, record the execution deadline, parallelism, attempt/cost limits, and available host resource limits. Use existing configured limits and a small reversible probe when costs are unknown; preserve the requested scope and do not invent a new approval step.
- Apply one absolute deadline to preparation, installation, execution, retries, and verification, reserving time for shutdown. Propagate the remaining budget to children and retain it across resume; a new process, task ID, or retry does not reset it. CPU, RAM, and storage limits are enforced only where the host or provider supports them. Metadata alone is not enforcement.
- User cancellation takes precedence over completion gates and recovery. Check cancellation and the remaining deadline before every dispatch, review, verification, recovery action, and resumed admission. On cancellation or deadline exhaustion, stop admitting new work, agents, retries, failover, reviews, and verification. Allow only bounded shutdown, termination checks, and an accurate partial handoff. Do not repair a gate or replay work to keep a cancelled run alive.
- Record resources as they are created: run identity, process identity/group, provider or container IDs, and generated file/cache paths. Stop only resources whose ownership is established. Request cancellation through the host API for native agents; use verified process-tree termination for CLI-owned workers. Retain ownership records until termination is confirmed and report any surviving resources or unsupported cancellation capability.
- Stopping computation does not authorize deletion. Preserve logs, results, worktrees, caches, images, volumes, credentials, and user data unless deletion is requested or an explicit retention policy applies. Check shared use before removing a registered resource; never replace scoped cleanup with a global prune or name-only process kill.
- Prefer completion notifications and host-supported waits. When polling is necessary, designate one coordinator, increase the interval within the remaining deadline, and read only changed status or short log tails. Keep cancellation delivery independent of the polling interval; avoid duplicate watchers and repeated unchanged updates.

## Verification and completion

- Verification belongs to the project's local CI and push hooks. Do not run test suites, type checks, linters, or builds on your own initiative; run a check only when the user or the active workflow explicitly requires it.
- Add a regression test with a bug fix. Do not invent implementation-mirroring tests for prose or configuration edits.
- Prefer hermetic tests. A test that needs Docker, containers (including testcontainers), or another external service is a last resort: isolate it in the project's opt-in integration task and keep it out of default hooks and required gates.
- Use the shared [result contract](../runtime/result-contract.md) for agent handoffs. Process exit zero and a Markdown file alone are not verified completion.
- Report completed, partial, blocked, or failed accurately, with remaining work and verification limits. A gate failure means repair evidence/work within the existing scope and retry; it is not automatically a new permission requirement.

Repository check: `cli/platform/execution-policy.test.ts`.

# Lessons Learned

Consult a relevant lesson after an observed failure or when prior evidence matches the current task. This file defines lesson handling; it is not a mandatory startup read or a destination for automatic edits to installed skills.

## Capture a useful lesson

Record a lesson when a repeated failure, consequential incident, or requested retrospective exposes a reusable cause and prevention method. Fix and verify routine failures directly. An expected failing regression test, a clarification question, or an experiment with a lower score does not by itself require an RCA.

Use the configured coordination store's `lessons-{sessionId}.md` (default `.agents/state/memories/`), or link an existing incident/result artifact. Include only information that helps prevent recurrence:

- The affected session/task/run and evidence paths.
- Observed behavior and impact; separate facts from suspected causes.
- Relevant framework version, configuration, or operating conditions.
- The fix and checks that support it.
- The prevention action and when it applies.

If the cause is unknown, say so. Do not invent a lesson merely to close a session. If the user says not to repeat a mistake, apply that correction to ongoing work immediately; record the reusable part without delaying the fix for a template.

## Applying lessons

- Check applicability against the installed version and actual configuration. A fix for one framework or runtime is not a universal rule.
- Review generated migrations against intended schema changes; generator success alone does not establish correctness.
- For integration failures, compare the actual producer and consumer contract: field names, types, authentication, timestamps, and error responses.
- Verify a suspected lifecycle, hydration, or redirect defect with the failing path before prescribing a hook, wrapper, or address substitution.
- Review findings need evidence. A disagreement alone does not establish an error; a separate reviewer does not guarantee correctness. Select runtime checks when the behavior requires them and record any verification limits.

## Promoting and maintaining lessons

Recurring evidence may justify a change to an owning skill, checklist, or project rule. Within an authorized source-maintenance task, prepare the scoped change, preserve exact version/trigger conditions, and verify it. Otherwise retain a proposal in the session artifact; do not mutate installed definitions during an unrelated run.

Read an experiment ledger only when it exists and a result needs analysis. A negative delta is a candidate for investigation, not proof of a reusable lesson. Keep successful and failed cases when comparing a proposed rule. Archive or remove historical lessons only under the repository's retention policy or the user's direction.

Use `session-metrics.md` for optional session evidence and `execution-policy.md` for authorization and completion.

# Task Handoffs

Use this guide when composing a task for another agent or when the requested outcome is unclear. A simple direct request does not need to be rewritten into a template.

Include the information the recipient needs:

| Element | Content |
|---|---|
| Goal | Observable behavior or artifact to change |
| Context | Relevant paths, existing patterns, errors, and prior decisions |
| Constraints | Actual scope, compatibility, ownership, and authorization boundaries |
| Done when | Acceptance criteria and proportionate verification |

Infer routine details from the request and repository. Do not invent constraints or ask the user to fill headings. Ask only about a missing fact that materially changes the result; follow `execution-policy.md` and `clarification-protocol.md`.

For implementation, include affected tests or examples when they clarify the contract. For a bug, describe the failure and expected behavior. For verification, name applicable project checks; a build is included only when explicitly requested by the user.

For dispatched tasks, preserve injected task/run/claim identity and required artifact paths from `../runtime/result-contract.md`. Reference the owning skill rather than pasting instructions already supplied by the runtime. Ownership and dependencies matter more than a decorative report format.

# Quality Principles

Use these principles for implementation and review decisions. Authorization, clarification, verification, and completion follow `execution-policy.md`.

- Establish the requested behavior from the task, repository, and relevant tests. State material assumptions; compare alternatives when an unresolved design choice changes the outcome.
- Prefer an implementation that solves the current problem without speculative features. Preserve useful existing abstractions and project conventions; line count alone is not a reason to rewrite working code.
- Keep edits within the requested scope. Preserve unrelated work and avoid turning an adjacent issue into an unrequested refactor.
- Verify the affected behavior with meaningful evidence. Reproduce bugs before fixing where feasible; use characterization tests for behavior-preserving refactors. Use the project's test approach and relevant static or manual checks when appropriate.
- Report what the evidence supports and what remains unverified. Re-run checks after relevant changes or failures, not to fill a fixed review count.

`test-approach.md` defines the plan's test evidence contract. `common-checklist.md` provides optional cross-domain review prompts.

# 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.

# 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`.

# 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.

# 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`.

# 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)
```

# 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.

# Translation prose diagnostics

Load this file with `../references/_shared/core/anti-ai-prose.md` and the target
`lang/{code}.md` when reviewing prose in a language without a selected external
style skill. English and Korean use `style-skills.md` instead. Common pattern
definitions live in the shared resource; this file owns fidelity exceptions and
translation-specific rules for the remaining language routes.

A target profile takes precedence for target-language usage; do not borrow a
different language's rules.

## Fidelity exceptions

- Preserve meaning, claims, named sources, qualifiers, emotional force, terminology,
  placeholders, code, links, locale keys, and required document structure.
- Do not add praise, authority, certainty, opinions, jokes, first person, examples,
  numbers, or citations. A portability finding is not permission to invent specifics.
- Do not remove source content merely because a shared diagnostic flags it. In strict
  translation, preserve the claim and intended emphasis in natural target wording;
  flag a source problem separately when material. Deletion or reorganization belongs
  to authorized adaptation or revision, not automatic translation cleanup.
- Classify source figurative language as interpret, substitute,
  or retain. Do not add mannered metaphors, and do not flatten intentional source voice.
- Retain an intentional ending, uncertainty, research
  question, or rhetorical effect when fidelity requires it. Do not intensify it.
- Preserve headings, lists, tables, formatting, and quoted chatbot
  language when they are source content. Do not introduce decorative structure.
- Use the target profile's vocabulary examples. Five or more flagged
  terms in one paragraph prompt contextual review, not automatic substitutions.
- Follow the target profile's dash conventions with at most one per
  paragraph. Reconstruct the clause instead of swapping punctuation;
  compare sibling wording before deciding the target syntax.
- Preserve source cadence where natural. Do not import academic
  sentence-length targets, first-person bans, or paragraph templates.

## Europeanized / Translation-ese Patterns

Patterns where the target text mimics source-language (typically English) grammar
instead of following native structure.

The categories below are shared. **Every example and every fix is
language-specific**, so the working version of each rule lives in
`lang/{code}.md` under "Localizations of shared rules". A profile may also
declare that a category does not apply to its language.

### Unnecessary Connectives

AI over-inserts logical connectives (*therefore, however, additionally,
furthermore, moreover*) where context already implies the relationship. If the
previous sentence already carries the logic, drop the connective and let the
clause boundary do the work.

### Passive Voice Abuse

English uses the passive far more than most target languages. Restructure to
active with an explicit agent unless the target genuinely prefers the passive in
that position, or the agent is unknown or deliberately suppressed.

### Noun Pile-up (Long Modifier Chains)

English stacks modifiers before nouns. Most languages read better when the chain
is broken into shorter clauses.

Rule: 3 or more stacked modifiers before a noun → break into clauses. Some
languages need a tighter threshold; see the profile.

### Over-nominalization

English uses abstract nouns plus a light verb ("conduct an analysis") where most
languages prefer a single verb ("analyze"). Watch for light-verb constructions in
the target and collapse them.

### Awkward Pronoun Insertion

English requires explicit subjects. Pro-drop languages prefer omission when the
subject is clear from context, so calqued pronouns read as stammering.

Rule: if the subject has not changed and is clear from context, omit it. For
targets that are **not** pro-drop, the inverse applies: supply the subject the
source omitted rather than leaving a dangling clause.

### Cleft Sentence Calques

English "It is X that ..." and "What matters is X" structures should not be
calqued. Most languages express the same emphasis with word order or a focus
particle.

### Target-Language Typography and Fragments

Sentence-completion requirements, fragment tolerance by position, quotation
marks, dash glyphs, spacing between scripts, counters, and date and number
formats are entirely language-specific.

There is no shared rule here. See the typography and sentence-completion sections
of `lang/{code}.md`.

---

## Translation checks

Check protected syntax and document structure first. Then use the shared diagnostics
with the fidelity exceptions above, the translation rubric for substantive text,
and the target profile's grammar and typography checks. Report only supported accuracy or
style defects, separate optional preferences, and accept zero findings.

# `<Language>` Target-Language Profile (`<code>`)

Copy this file to `<code>.md` (BCP 47 primary subtag, e.g. `de.md`, `pt.md`,
`vi.md`) to add a profile. Register the code in the routing table in
`../../SKILL.md` under "Language Profile Loading".

A profile exists to hold what the shared files must not: anything that is true
of one target language and false of another. If a rule would apply equally to
every target, put translation-specific guidance in `../anti-ai-patterns.md`.
Put prose diagnostics that also apply to academic writing in
`../../references/_shared/core/anti-ai-prose.md`; refer to patterns by heading name.

Delete every section you have nothing grounded to say about. An empty profile
is better than an invented one, because a wrong rule is followed as confidently
as a right one.

---

## Variant resolution

Only if the language has variants that change script, vocabulary, or
orthography (`pt-BR` vs `pt-PT`, `zh-CN` vs `zh-TW`, `es-ES` vs `es-419`).
State the resolution order and the default, and say what must never be mixed.

## Register

How formality is encoded in this language, and how it maps to `translation_voice`
(`formal` / `balanced` / `interpreter`) from `.agents/oma-config.yaml`.

Cover whatever the language actually forces a choice on: sentence endings,
T-V distinction (`du`/`Sie`, `tu`/`vous`, `tú`/`usted`), honorifics, or
formal/informal verb paradigms. State that the choice is made once per document
and never drifts, and name the exempt positions (headings, table cells).

## `<CODE>`-only rules

Number them `<CODE>-1`, `<CODE>-2`, ... so the self-check and `SKILL.md` can
cite local requirements unambiguously.

Typical categories worth a rule, when the language has one:

- Grammatical agreement the source language lacks (gender, case, number,
  animacy, definiteness)
- Word order constraints (V2, verb-final, clitic placement)
- Constructions that only appear as calques from English
- Typography: quotation marks, dashes, decimal and thousands separators,
  spacing before punctuation, capitalization of headings and nouns
- Date, number, and unit formats
- Orthography standards and the loanword forms machine output gets wrong

Give every rule at least one `bad → good` pair. The examples do more work than
the rule text.

## Localizations of shared rules

Include only patterns that manifest distinctly in this language. Use a descriptive
heading and link to the corresponding heading in the common prose diagnostics or
translation resource. Show the language-specific example beneath that reference.

Common topics include participle phrases, vocabulary, synonym cycling, compound
stacking, dash handling, and translation-ese.

Say explicitly when a shared rule **does not** apply. `en.md` does this for the
em-dash rule, which exists only for CJK targets. Silence gets read as agreement.

## `<Language>` self-check

A flat checklist, one line per rule, each citing its rule ID. It runs after the
shared self-check, before emitting.

## References

Cite sources for adopted rules, with the license when the source is a repository.

# English Target-Language Profile (`en`)

Load this profile when the **target** primary language subtag is `en`, including
`en-US` and `en-GB`. Read it with `../translation-rubric.md` for substantive
content or review. For substantive prose style, follow
`../style-skills.md`.

This profile owns source-to-English grammar and project conventions.

---

## Register

| Voice | Effect |
|---|---|
| `formal` | full sentences, no contractions, third person, no fragments |
| `balanced` | contractions allowed, second person for instructions, fragments in labels and cells |
| `interpreter` | short sentences, direct address, fragments allowed where natural |

Documentation defaults to second-person imperative for instructions ("Run the
migration") and third person for descriptions. Do not drift into first-person
plural ("we recommend") unless the source has an authorial voice.

---

## English-only rules

### EN-1. Articles

CJK sources do not supply English articles. Choose the article from the noun's
meaning and context.

```
Bad:  Run migration before starting server.
Good: Run the migration before starting the server.

Bad:  This is the useful tool for the developers.
Good: This is a useful tool for developers.
```

Rules of thumb: a specific, previously-mentioned, or uniquely-identified thing
takes `the`; a first mention of a countable thing takes `a`/`an`; generic plurals
and uncountables take no article.

### EN-2. Number marking

CJK does not inflect for number. Decide singular or plural for every countable
noun, and make the verb agree.

```
Bad:  The config file are loaded from three location.
Good: The config files are loaded from three locations.
```

### EN-3. Topic-comment to subject-predicate

Korean and Japanese front the topic with `은/는` or `は` and leave the subject
implicit. English needs an explicit subject in the right slot.

```
KO:   이 기능은 캐시를 쓰기 때문에 첫 실행이 느립니다
Bad:  This feature, because it uses cache, first run is slow.
Good: Because this feature uses a cache, the first run is slow.
```

### EN-4. Split long CJK sentences

A single Korean or Japanese sentence often carries three clauses joined by
`~므로`, `~는데`, `〜ため`. Rendering that as one English sentence produces a
run-on. Split at the clause boundaries.

```
Bad:  The scan reads the manifest and because the manifest may be stale it
      re-hashes each file and then reports the drift.
Good: The scan reads the manifest. Because the manifest may be stale, it
      re-hashes each file, then reports the drift.
```

### EN-5. Drop politeness padding

Korean and Japanese business register carries deference that becomes servile or
odd in English.

```
확인 부탁드립니다        → Please review.        (not "I humbly request your kind review")
~해 주시기 바랍니다      → Run ... / Please run ...
ご確認いただけますと幸いです → Please confirm.
参考にしてください       → See ... / For reference, see ...
```

Do not add "kindly", "please be informed", "as per", or "do the needful".

### EN-6. Unpack Sino-Korean and 漢語 nominalizations into verbs

```
검증을 수행합니다      → validates      (not "performs validation")
개선을 진행했습니다    → improved       (not "carried out an improvement")
最適化を実施する       → optimize       (not "implement optimization")
```

### EN-8. Typography

- **Quotes**: straight `"` and `'` in code-adjacent docs and Markdown source.
  Curly quotes only when the publishing pipeline requires them.
- **Headings**: match the case used by sibling headings.
- **Serial comma**: follow sibling files; be consistent within a document.
- **Dates**: `2026-08-20` in tables and logs, `August 20, 2026` in US-audience
  prose, `20 August 2026` for international audiences. Follow siblings.
- **Units**: space between number and unit (`10 MB`, `200 ms`); no space before
  `%` (`40%`).
- **Spelling**: match the project's existing variety (US vs UK); do not mix.

---

## English self-check

- [ ] Every countable noun has a correct article or a deliberate zero article (`EN-1`)
- [ ] Number and subject-verb agreement are correct throughout (`EN-2`)
- [ ] No topic-comment structure left untranslated (`EN-3`)
- [ ] No run-on carried over from a multi-clause CJK sentence (`EN-4`)
- [ ] No politeness padding, "kindly", or "do the needful" (`EN-5`)
- [ ] Nominalizations unpacked into verbs (`EN-6`)
- [ ] Heading case, serial comma, date format, and spelling variety match siblings (`EN-8`)

# Japanese Target-Language Profile (`ja`)

Load this file whenever the **target** language is Japanese. It is read together
with `../translation-rubric.md` for substantive content or review. For prose style
review, also load `../../references/_shared/core/anti-ai-prose.md` (common taxonomy) and
`../anti-ai-patterns.md` (translation exceptions and grammar diagnostics).

- **Localizations** of shared anti-AI patterns.
- **Japanese-only rules** (`JA-1`–`JA-9`).

---

## Register

| Style | Ending | Use for |
|---|---|---|
| です・ます体 (敬体) | `です` / `ます` | user-facing docs, READMEs, release notes, agent reports |
| だ・である体 (常体) | `だ` / `である` | specs, reference docs, academic prose, changelog bodies |

Resolution order:

1. Match the dominant style of sibling files in the same directory.
2. Otherwise map from `translation_voice`: `formal` → です・ます体 with fully
   expanded sentences, `balanced` → です・ます体 for prose and である体 for
   reference tables, `interpreter` → です・ます体 with shorter sentences and
   permitted 体言止め in label positions.

Never mix the two inside one document. Headings and table cells are exempt.

**Honorifics**: use 尊敬語 / 謙譲語 only where the source addresses a person or the
project already does. Avoid 二重敬語 (`お伺いいたします` → `伺います`,
`ご覧になられる` → `ご覧になる`).

---

## Japanese-only rules

### JA-1. 一文一義 — one proposition per sentence

Japanese tolerates long sentences grammatically but reads poorly when a single
sentence carries three or more clauses joined by `〜が`, `〜ため`, `〜ので`. English
compound sentences should be split rather than chained.

```
Bad:  この機能はキャッシュを使用しますが、初回実行時にはキャッシュがないため
      レイテンシが増加しますので、事前にウォームアップを実行してください。
Good: この機能はキャッシュを使用します。初回実行時はキャッシュがないため
      レイテンシが増加します。事前にウォームアップを実行してください。
```

### JA-2. Trim redundant potential and progressive forms

```
〜することができます  → 〜できます
〜を行います          → 〜します
〜という形になります  → 〜です / 〜になります
〜させていただきます  → 〜します   (unless the source is genuinely deferential)
```

### JA-3. 体言止め is positional

Noun-ending sentences are natural in headings, bullet labels, and table cells,
and unnatural in narrative body text. This is the same boundary as Korean
`KO-3`, but Japanese tolerates 体言止め in more list positions.

```
Bad (body):  `ANTHROPIC_API_KEY` の未設定。
Good (body): `ANTHROPIC_API_KEY` は設定されておらず、OAuth で認証します。
Good (cell): 結果: lint 失敗
```

### JA-4. Suffix abstraction overuse (`〜性` / `〜化` / `〜的`)

AI output stacks abstract suffixes where a verb or adjective is natural.

```
可用性の向上を実施します   → より安定して使えるようにします
自動化を行います           → 自動で処理します
構造的な問題               → 構造の問題
```

Keep the suffix when it is established terminology (`可用性`, `冪等性`,
`後方互換性` in technical specs).

### JA-5. Punctuation and script

- **句読点**: `、` and `。` (fullwidth). Never `，` `．` unless the project already
  uses them.
- **Brackets**: `「」` for quotation, `『』` for titles and nested quotation,
  fullwidth `（）` for asides in Japanese text, halfwidth `()` around ASCII-only
  content such as `(CLI)`.
- **Em dash**: `—` is not Japanese typography. Restructure, or use `。` to split.
  Do not swap it for `：` and stop there (the mechanical punctuation swaps guidance).
- **中黒**: `・` for coordinating loanword nouns (`インストール・設定`).
- **Spacing**: follow the project convention for a space between Japanese and
  ASCII runs. Read three sibling files before choosing; do not switch mid-file.
- **波ダッシュ**: `〜` for ranges (`3〜5 件`), not `~`.

### JA-6. 長音符 policy

`サーバー` vs `サーバ`, `コンピューター` vs `コンピュータ`. Both conventions are in
active use. Match the project's existing files; if none exist, use the JIS-style
long form (`サーバー`) for user-facing docs.

### JA-7. カタカナ vs 漢語

Do not romanize a concept the project already writes in 漢語, and do not force a
kanji compound where the loanword is the industry standard.

```
デプロイ  keep (not 配備)
ロールバック keep (not 巻き戻し)
認証 keep (not オーセンティケーション)
検証 keep (not バリデーション) — unless the codebase uses バリデーション
```

Consistency with the project's existing translations decides.

### JA-8. Avoid 二重否定 and hedge stacking

```
Bad:  対応していないわけではありません
Good: 対応しています / 一部だけ対応しています

Bad:  可能性があるかもしれません
Good: 可能性があります
```

### JA-9. Numbers, dates, units

- Dates: `2026年8月20日` in prose, `2026-08-20` in tables and logs.
- Numerals: halfwidth (`5 件`, `12,000`), not `５件`.
- Percent: `40%` with no space.
- Counters must match the noun (`件`, `個`, `台`, `回`, `つ`).

---

## Localizations of shared rules

### `-ing` participle phrases

See [Superficial analysis](../../references/_shared/core/anti-ai-prose.md#superficial-analysis).

```
EN:   The update improves performance, ensuring a seamless experience
Bad:  このアップデートはパフォーマンスを向上させ、シームレスな体験を保証します
Good: このアップデートでパフォーマンスが改善され、より快適に使えます
```

### AI vocabulary overuse

See [Vocabulary clustering](../../references/_shared/core/anti-ai-prose.md#vocabulary-clustering).

| Watch | Prefer |
|---|---|
| また (sentence-initial, repeated) | restructure or drop |
| 重要な / 不可欠な | only when the source emphasizes |
| 活用する | 使う, 利用する |
| さまざまな | usually delete |
| 〜を通じて | restructure the clause |
| 最適化する / 最大化する | match the source's intensity |

### rule of three

See [Mechanical triples](../../references/_shared/core/anti-ai-prose.md#mechanical-triples).

```
EN:   a fast, reliable, and intuitive experience
Bad:  高速で、信頼性が高く、直感的な体験
Good: 速く、信頼性が高く、直感的な体験
```

Preserve every source quality. A real three-item list is valid when all three carry meaning.

### synonym cycling

See [Synonym cycling](../../references/_shared/core/anti-ai-prose.md#synonym-cycling).

If `ユーザー` is right, use `ユーザー` throughout. Do not rotate through
`利用者`, `使用者`, `エンドユーザー`.

### compound stacking

See [Compound adjective stacking](../../references/_shared/core/anti-ai-prose.md#compound-adjective-stacking) and [Abstract noun and adjective stacking](../../references/_shared/core/anti-ai-prose.md#abstract-noun-and-adjective-stacking).

```
Bad:  AI 搭載のクラウドベースのエンタープライズグレードのソリューション
Good: クラウド上で動くエンタープライズグレードの AI ソリューション
```

### mechanical punctuation swap

See [Mechanical punctuation swaps](../../references/_shared/core/anti-ai-prose.md#mechanical-punctuation-swaps).

```
Source: Documentation drift checks — broken refs and diff-affected docs
Lazy:   ドキュメントドリフトチェック：壊れた参照と diff 影響ドキュメント
Better: 参照の整合性チェックと、変更の影響を受けるドキュメントの特定
```

### unnecessary connectives

See [Unnecessary Connectives](../anti-ai-patterns.md#unnecessary-connectives).

```
Bad:  パフォーマンスが向上しました。したがって、ユーザー体験が良くなりました。
Good: パフォーマンスが向上し、ユーザー体験も良くなりました。
```

Watch したがって, しかしながら, さらに, また, その結果.

### passive voice

See [Passive Voice Abuse](../anti-ai-patterns.md#passive-voice-abuse).

```
Bad:  この機能はチームによって開発されました
Good: チームがこの機能を開発しました
```

### noun pile-up

See [Noun Pile-up (Long Modifier Chains)](../anti-ai-patterns.md#noun-pile-up-long-modifier-chains).

```
Bad:  AI ベースのクラウド対応リアルタイムデータ監視システム
Good: AI を使ってクラウド上でデータをリアルタイムに監視するシステム
```

### over-nominalization

See [Over-nominalization](../anti-ai-patterns.md#over-nominalization).

```
議論を行いました → 議論しました
改善を実施する   → 改善する
検討を進める     → 検討する
```

### forced pronouns

See [Awkward Pronoun Insertion](../anti-ai-patterns.md#awkward-pronoun-insertion).

```
Bad:  私たちはこの機能をリリースし、私たちは良い反応を得ました
Good: この機能をリリースしたところ、反応は良好でした
```

Japanese omits subjects freely. Insert `私たち` only when the actor genuinely
changes or contrast requires it.

### cleft calques

See [Cleft Sentence Calques](../anti-ai-patterns.md#cleft-sentence-calques).

```
Bad:  重要なのはユーザー体験であるということです
Good: ユーザー体験が重要です
```

---

## Japanese self-check

- [ ] One style throughout; no です・ます / である mixing
- [ ] No sentence chaining three or more clauses (`JA-1`)
- [ ] No `〜することができます` / `〜を行います` redundancy (`JA-2`)
- [ ] No 体言止め in narrative body text (`JA-3`)
- [ ] No stacked `〜性` / `〜化` / `〜的` where a verb works (`JA-4`)
- [ ] `、` `。` used; no `—`; no curly quotes (`JA-5`)
- [ ] 長音符 and カタカナ / 漢語 choices match sibling files (`JA-6`, `JA-7`)
- [ ] No 二重否定 or stacked hedges (`JA-8`)
- [ ] No 二重敬語
- [ ] Halfwidth numerals with correct counters (`JA-9`)

# Korean Target-Language Profile (`ko`)

Load this profile when the **target** primary language subtag is `ko`, including
`ko-KR`. Read it with `../translation-rubric.md` for substantive content or
review. For substantive prose style, follow `../style-skills.md`.

This profile owns Korean grammar, register, and project conventions.

All examples are illustrative pairs in `bad → good` form. Do not translate the
rule text itself into the output.

---

## Register

Korean forces a sentence-ending choice on every sentence. Pick once per
document and never drift.

| Style | Ending | Use for |
|---|---|---|
| 합니다체 | `-습니다` / `-ㅂ니다` | reports, user-facing docs, release notes, agent output |
| 해요체 | `-어요` / `-아요` | conversational UI, onboarding microcopy, casual product voice |
| 한다체 (평서체) | `-다` / `-이다` | reference docs, specs, academic prose, changelog bodies |

Resolution order:

1. Match the dominant ending of sibling files in the same directory.
2. If no siblings exist, map from `translation_voice` in `.agents/oma-config.yaml`:
   `formal` → 합니다체, `balanced` → 합니다체 for prose and 한다체 for reference
   tables, `interpreter` → 합니다체 with shorter sentences and permitted
   label-position fragments.
3. If the source is dialogue or subtitle content, follow the speaker relationship
   in the source rather than the file convention.

Never mix 합니다체 with 한다체 inside one document. Headings and table cells are
exempt because they carry no ending at all.

**Honorific target**: raise the listener (`-시-`, `-께서`, 공손 어휘) only when the
source addresses a person directly or the project already does so. Do not add
`사용자님`-class honorifics to documentation that addresses a generic reader.

---

## Korean-only rules

### KO-1. Do not drop particles or endings

Compressed agent Korean drops 조사 and 어미 to save tokens, which strips out the
grammatical relations that carry the meaning. Restore them. Use 부사, 보조사,
선어말어미, and 보조 용언 actively rather than treating them as optional padding.

```
이 결정은 이후 중요 정책이 갈리는 자리. 컨텍스트 압축 전 신중 반영한다.
→ 이 결정은 이후 중요한 정책에 지속적으로 영향을 주기 때문에, 컨텍스트가
  압축되기 전에 신중히 반영합니다.
```

This is a restoration of grammar, not an addition of meaning. It must not
introduce facts, opinions, or emphasis that the source does not carry.

### KO-2. Genitive `의` chains hide dropped sentence elements

`의` linking two or more nouns is a diagnostic signal, not merely a style
preference: the predicate and the particles that belong in that position have
been deleted. Two `의` in one noun phrase is a hard flag; three is a block.

```
사본의 문구는 작업의 상황을
→ 사본에 기재된 문구는 작업이 진행되는 상황을

지출 비용 추론 용도의 토큰 카운트 함수의 오류 상황에서
→ 지출한 비용을 추론하는 토큰 카운트 함수에 오류가 발생하면
```

Also delete `의` that entered as a calque of Japanese `の` or English `of` where
Korean would use no particle at all: `최대의 성능` → `최대 성능`,
`두 개의 파일` → `파일 두 개`.

A genitive chain can hide a dropped predicate even when it has fewer than three
modifiers.

### KO-3. Finish the sentence

End body sentences with a predicate and a final ending. Three failure shapes:

| Shape | Bad | Good |
|---|---|---|
| Noun ending | `lint 실패.` | `lint가 실패했습니다.` |
| Adverbial ending | `설정 파일을 읽지 못한 채로.` | `설정 파일을 읽지 못한 채로 종료했습니다.` |
| Connective ending | `캐시를 비우고 다시 실행했으며,` | `캐시를 비우고 다시 실행했습니다.` |

Exempt positions: headings, list items that act as labels, table cells, and
`key: value` pairs. `결과: lint 실패` is correct; a bare `lint 실패.` sitting in a
paragraph is not.

**Trailing negation calque**: English tacks short negation fragments onto a
sentence end (`..., no guessing`). Calquing this produces `..., 추측 없이`, which
is a noun fragment in Korean body text.

```
선택된 항목에서 옵션이 나옵니다, 추측 없이.
→ 선택된 항목에서 바로 옵션을 가져오므로 사용자가 추측할 필요가 없습니다.
```

### KO-4. Sino-Korean vocabulary is not the problem; bare Sino-Korean nouns are

Keep precise Sino-Korean terms and supply the particles and inflections they
need. A bare Sino-Korean noun with no particle or verb ending can hide the action.

```
지출 비용 추론 용도의 토큰 카운트 함수의 오류 상황에서   (no particles, relations unclear)
쓴 비용을 구하는 토큰 카운트 함수에 문제가 생기면        (over-nativized, imprecise)
→ 지출한 비용을 추론하는 토큰 카운트 함수에 오류가 발생하면
```

`발생하면`, `추론하는`, `지출한` are all Sino-Korean and all correct, because each
carries an ending.

### KO-5. No noun-pinned verbs

Pinning a verb into Korean as a bare noun, whether an English loanword or a
stiff Sino-Korean noun, reads as jargon.

```
skill을 로드              → skill을 불러옵니다
프로젝트에 시드           → 프로젝트에 심습니다
`<HARD-GATE>` 발동        → `<HARD-GATE>`가 걸렸습니다
마이그레이션 진행         → 마이그레이션을 실행했습니다
```

### KO-6. No figurative substitution for plain vocabulary

Do not introduce figurative Korean vocabulary when the source uses a plain noun
or verb. It changes the meaning.

```
분석의 플로우      → 분석의 흐름
코드로 박는 자리    → 코드에 명시하는 위치
요청을 수신합니다   → 요청을 받습니다
테스트를 태웁니다   → 테스트를 실행합니다
```

Keep expressions that are already established idiom in the field and would sound
stilted if flattened (`병목`, `롤백`, `핫픽스`).

### KO-8. Korean translation-ese constructions

| Pattern | Bad | Good |
|---|---|---|
| 이중 피동 | `보여집니다`, `불려집니다`, `되어집니다` | `보입니다`, `불립니다`, `됩니다` |
| `~에 대한` overuse | `설정에 대한 검토를 했습니다` | `설정을 검토했습니다` |
| `~에 있어서` (JA `における`) | `배포에 있어서 중요한 것은` | `배포에서 중요한 점은` |
| `~로부터` (JA `から`) | `서버로부터 응답을 받았습니다` | `서버에서 응답을 받았습니다` |
| `~에 의해` (EN passive) | `팀에 의해 개발되었습니다` | `팀이 개발했습니다` |
| `~적(的)` stacking | `구조적, 기능적 개선` | `구조와 기능을 개선` |
| `~들` plural forcing | `파일들을 모두 삭제했습니다` | `파일을 모두 삭제했습니다` |
| `~하는 것이 가능하다` | `재시도하는 것이 가능합니다` | `재시도할 수 있습니다` |
| `~화(化)` nominalizing | `자동화를 진행합니다` | `자동으로 처리합니다` |

Korean marks plurality with quantifiers and context. Use `들` only when the
plural reading would otherwise be lost.

### KO-9. Typography and spacing

- **Inline code + particle**: no space between a backtick span and the particle
  that follows. `` `prompt` 로 `` → `` `prompt`로 ``.
- **Counters**: no space between numeral and counter. `5 개` → `5개`, `3 번째` →
  `3번째`. Units keep a space: `10 MB`, `200 ms`.
- **Em dash**: reconstruct the clause in Korean body prose rather than replacing
  the dash with another punctuation mark.
- **Quotes**: straight `"` and `'`, or `「」` only when the project already uses
  them. Do not emit curly quotes.
- **Parentheses**: halfwidth `()` with no leading space when attached to a term:
  `하네스(harness)`.
- **Ellipsis**: `...` rather than `…` unless the source file already uses `…`.
- **Middle dot**: `·` for tight coordination in headings (`설치·설정`), commas in
  body text.

### KO-10. Loanword orthography (외래어 표기법)

Use the standard form. Frequent misspellings in machine output:

```
컨텐츠 → 콘텐츠      메세지 → 메시지      데이타 → 데이터
윈도우즈 → 윈도우    타겟 → 타깃          레퍼런스 → 레퍼런스 (ok)
쉐이더 → 셰이더      플래폼 → 플랫폼      비지니스 → 비즈니스
어플리케이션 → 애플리케이션              스케쥴 → 스케줄
```

When the project's existing translations consistently use a non-standard form,
follow the project and note the conflict once.

### KO-11. Numbers, dates, units

- Dates: `2026년 8월 20일` in prose, `2026-08-20` in tables and logs.
- Ranges: `3~5개` in prose, `3-5` inside code or config values.
- Large numbers: comma grouping (`12,000`), and `만`/`억` only when the source
  uses a comparable scale word.
- Percent: `40%` with no space.

### KO-12. Subagent and multi-hop Korean

When Korean text will be consumed by another agent rather than by a person
(subagent prompts, intermediate result files, handoff summaries), apply `KO-1`
through `KO-3` before handing it off. Quality loss compounds at every hop in
`orchestrate`, `ultrawork`, and `ralph`, and a dropped particle in a stage-1
prompt becomes a wrong decision in stage 3.

Internal status keywords, workflow markers, and log levels stay in English per
`.agents/rules/i18n-guide.md`.

---

## Korean self-check

Check source-to-Korean grammar and project conventions before delivery.

- [ ] One sentence-ending style throughout; no 합니다체 / 한다체 mixing
- [ ] No dropped 조사 or 어미 in body text (`KO-1`)
- [ ] No noun phrase with two or more chained `의` (`KO-2`)
- [ ] No body sentence ending in a noun, adverbial, or connective (`KO-3`)
- [ ] No bare Sino-Korean or loanword noun standing in for a verb (`KO-4`, `KO-5`)
- [ ] No invented figurative vocabulary where the source was plain (`KO-6`)
- [ ] No 이중 피동, `~에 대한`, `~에 있어서`, `~들` forcing (`KO-8`)
- [ ] No space between inline code and its particle; no space in `5개` (`KO-9`)
- [ ] No `—`, no curly quotes (`KO-9`)
- [ ] Loanwords follow 외래어 표기법 or the project's established forms (`KO-10`)
- [ ] Korean handed to another agent passes `KO-1`–`KO-3` (`KO-12`)

# Chinese Target-Language Profile (`zh`)

Load this file whenever the **target** language is Chinese. It is read together
with `../translation-rubric.md` for substantive content or review. For prose style
review, also load `../../references/_shared/core/anti-ai-prose.md` (common taxonomy) and
`../anti-ai-patterns.md` (translation exceptions and grammar diagnostics).

- **Localizations** of shared anti-AI patterns.
- **Chinese-only rules** (`ZH-1`–`ZH-9`).

---

## Variant resolution (do this first)

`zh` is not a single target. Resolve the variant before translating a single
string, because script, vocabulary, and punctuation all diverge.

| Locale | Script | Region vocabulary |
|---|---|---|
| `zh-CN` / `zh-Hans` | 简体 | 软件, 网络, 程序, 服务器, 内存, 视频 |
| `zh-TW` / `zh-Hant-TW` | 繁體 | 軟體, 網路, 程式, 伺服器, 記憶體, 影片 |
| `zh-HK` / `zh-Hant-HK` | 繁體 | mostly TW vocabulary, HK-specific terms where established |

Resolution order: explicit locale in the file path or user request → dominant
script of sibling files → ask. If bare `zh` is requested with no signal, default
to `zh-CN` and say so once in the output notes. Never mix scripts in one file,
and never convert 简体 to 繁體 by character substitution alone: the vocabulary
must be converted too (`软件` → `軟體`, not `軟件`).

## Register

Chinese has no obligatory sentence-ending register system, so consistency lives
in vocabulary and sentence length instead.

| Voice | Effect |
|---|---|
| `formal` | 书面语, full sentences, 您 for the reader, no fragments |
| `balanced` | 书面语 in prose, fragments allowed in table cells and labels |
| `interpreter` | shorter clauses, 你 acceptable in product UI, spoken cadence |

Use `您` in enterprise and formal docs, `你` in developer-facing and product UI
when the project already does. Do not switch mid-document.

---

## Chinese-only rules

### ZH-1. `的` overuse (的的不休)

Chinese drops `的` far more readily than English drops `of`. Two `的` in one
noun phrase is a flag; three is a block.

```
Bad:  这是一个用于处理用户的请求的高性能的服务
Good: 这是处理用户请求的高性能服务

Bad:  系统的性能的提升
Good: 系统性能提升
```

Drop `的` between a monosyllabic modifier and its noun (`红花`, not `红的花`),
and after established compounds (`用户体验`, not `用户的体验`).

### ZH-2. `一个` as an indefinite article calque

English `a/an` has no Chinese equivalent. Insert a measure word only when the
count matters.

```
Bad:  这是一个强大的工具
Good: 这是强大的工具 / 这个工具很强大
```

### ZH-3. `们` plural forcing

Chinese marks plurality with context and quantifiers. `们` attaches only to
human nouns, and even then only when the plural reading would be lost.

```
Bad:  删除所有的文件们
Good: 删除所有文件
```

### ZH-4. Empty verbs (`进行` / `做出` / `实施` / `予以`)

```
进行了讨论 → 讨论了
做出了改进 → 改进了
实施优化   → 优化
予以处理   → 处理
```

### ZH-5. `关于` / `对于` overuse

```
Bad:  关于配置的检查已经完成
Good: 配置检查已完成

Bad:  对于这个问题，我们进行了修复
Good: 我们修复了这个问题
```

### ZH-6. Long pre-nominal modifiers

Chinese places modifiers before the noun, so English relative clauses pile up
into unreadable strings. Split into separate clauses or use a 把 / 被 pivot.

```
Bad:  基于 AI 的支持云端部署的实时数据监控系统
Good: 一套用 AI 在云端做实时数据监控的系统
```

Rule: more than about 12 characters of pre-nominal modifier → restructure.

### ZH-7. Punctuation and spacing

- **Fullwidth punctuation**: `，` `。` `、` `：` `；` `？` `！`. Never halfwidth in
  Chinese body text.
- **Enumeration comma**: `、` between list items inside a sentence, `，` between
  clauses. These are not interchangeable.
- **Quotes**: `“”` and `‘’` for `zh-CN`, `「」` and `『』` for `zh-TW` / `zh-HK`.
  This is the one target where curly quotes are correct; the shared curly-quote
  check must not strip them.
- **Brackets**: fullwidth `（）` around Chinese content, halfwidth `()` around
  ASCII-only content.
- **Em dash**: Chinese uses `——` (double-width, two ems) for a genuine break,
  which is not the same mark as `—`. Prefer restructuring; do not carry the
  English `—` through.
- **Latin spacing**: follow the project convention for a space between Chinese
  and ASCII runs. Read three sibling files before choosing; do not switch
  mid-file.
- **Ellipsis**: `……` (six dots, two characters), not `...`.

### ZH-8. Abstract suffix overuse (`性` / `化` / `度`)

```
提高了系统的可用性和稳定性 → 系统更稳定、更少出问题
进行自动化处理             → 自动处理
```

Keep the suffix when it is established terminology (`可用性`, `幂等性`,
`向后兼容性`).

### ZH-9. Numbers, dates, units

- Dates: `2026年8月20日` in prose, `2026-08-20` in tables and logs.
- Numerals: halfwidth (`5 个`, `12,000`).
- Percent: `40%` with no space.
- Ranges: `3~5 个` or `3 到 5 个`; do not use `—`.
- Measure words must match the noun (`个`, `台`, `条`, `项`, `次`).

---

## Localizations of shared rules

### `-ing` participle phrases

See [Superficial analysis](../../references/_shared/core/anti-ai-prose.md#superficial-analysis).

```
EN:   The update improves performance, ensuring a seamless experience
Bad:  这次更新提升了性能，确保了无缝的体验
Good: 这次更新提升了性能，用起来更顺畅
```

### AI vocabulary overuse

See [Vocabulary clustering](../../references/_shared/core/anti-ai-prose.md#vocabulary-clustering).

| Watch | Prefer |
|---|---|
| 此外 / 另外 (sentence-initial, repeated) | restructure or drop |
| 关键的 / 至关重要的 | only when the source emphasizes |
| 利用 | 用, 使用 |
| 各种各样的 | usually delete |
| 通过...来 | restructure the clause |
| 优化 / 最大化 | match the source's intensity |

### rule of three

See [Mechanical triples](../../references/_shared/core/anti-ai-prose.md#mechanical-triples).

```
EN:   a fast, reliable, and intuitive experience
Bad:  快速的、可靠的、直观的体验
Good: 快速、可靠且直观的体验
```

Preserve every source quality. A real three-item list is valid when all three carry meaning.

### synonym cycling

See [Synonym cycling](../../references/_shared/core/anti-ai-prose.md#synonym-cycling).

If `用户` is right, use `用户` throughout. Do not rotate through `使用者`,
`客户`, `终端用户`.

### compound stacking

See [Compound adjective stacking](../../references/_shared/core/anti-ai-prose.md#compound-adjective-stacking) and [Abstract noun and adjective stacking](../../references/_shared/core/anti-ai-prose.md#abstract-noun-and-adjective-stacking).

```
Bad:  一个 AI 驱动的、基于云的、企业级的解决方案
Good: 一套跑在云上的企业级 AI 方案
```

### mechanical punctuation swap

See [Mechanical punctuation swaps](../../references/_shared/core/anti-ai-prose.md#mechanical-punctuation-swaps).

```
Source: Documentation drift checks — broken refs and diff-affected docs
Lazy:   文档漂移检查：损坏的引用和受 diff 影响的文档
Better: 检查引用是否失效，并找出受改动影响的文档
```

### unnecessary connectives

See [Unnecessary Connectives](../anti-ai-patterns.md#unnecessary-connectives).

```
Bad:  性能提升了。因此，用户体验变好了。
Good: 性能提升了，用户体验也跟着变好。
```

Watch 因此, 然而, 此外, 另外, 同时, 综上所述.

### passive voice

See [Passive Voice Abuse](../anti-ai-patterns.md#passive-voice-abuse).

```
Bad:  这个功能被团队开发了
Good: 团队开发了这个功能
```

`被` is correct when the outcome is adverse or the agent is genuinely unknown
(`文件被删除了`). It is wrong as a blanket rendering of English passive.

### noun pile-up

See [Noun Pile-up (Long Modifier Chains)](../anti-ai-patterns.md#noun-pile-up-long-modifier-chains).

See `ZH-6`.

### over-nominalization

See [Over-nominalization](../anti-ai-patterns.md#over-nominalization).

See `ZH-4`.

### forced pronouns

See [Awkward Pronoun Insertion](../anti-ai-patterns.md#awkward-pronoun-insertion).

```
Bad:  我们推出了这个功能，我们得到了好的反馈
Good: 推出这个功能后，反馈不错
```

### cleft calques

See [Cleft Sentence Calques](../anti-ai-patterns.md#cleft-sentence-calques).

```
Bad:  重要的是用户体验
Good: 用户体验重要
```

---

## Chinese self-check

- [ ] Variant resolved (`zh-CN` / `zh-TW` / `zh-HK`); script and vocabulary both
      converted, never script alone
- [ ] No noun phrase with two or more `的` (`ZH-1`)
- [ ] No `一个` inserted as an article (`ZH-2`)
- [ ] No `们` on non-human or contextually plural nouns (`ZH-3`)
- [ ] No `进行` / `做出` / `实施` empty verbs (`ZH-4`)
- [ ] No `关于` / `对于` sentence openers that add nothing (`ZH-5`)
- [ ] No pre-nominal modifier longer than about 12 characters (`ZH-6`)
- [ ] Fullwidth punctuation; `、` vs `，` used correctly; `……` not `...` (`ZH-7`)
- [ ] Quote style matches the variant; curly quotes preserved for `zh-CN`
- [ ] No English `—` carried through (`ZH-7`)
- [ ] `被` used only for adverse or agentless outcomes (shared `20`)

# Selected prose-style skills

Use after drafting substantive translated prose or when reviewing its style.
Select from the **target** BCP 47 primary language subtag, case-insensitively.
Source language and English code snippets do not select this route. Short
independent UI strings retain the lightweight path in the owning SKILL.md.

| Target | Skill | Upstream |
|---|---|---|
| `en`, including `en-US` and `en-GB` | `humanizer` | [blader/humanizer](https://github.com/blader/humanizer) |
| `ko`, including `ko-KR` | `humanize-korean` | [epoko77-ai/im-not-ai](https://github.com/epoko77-ai/im-not-ai) |

## Resolve and load

1. Look up the selected skill in the runtime's skill catalog and read its actual
   SKILL.md in full. Confirm the entry corresponds to the listed upstream. A
   namespaced catalog entry is acceptable. Reuse an installed bundle or an
   existing upstream checkout; do not infer a path from a skill name.
2. Load the upstream references required by the selected mode from that bundle.
   OMA owns the translation boundary below, not a copy of either pattern catalog.
3. If the selected skill is absent, use the Skills CLI through Bun to load its
   instructions and supporting files into a temporary directory:

   ```bash
   bunx skills use blader/humanizer@humanizer
   ```

   For Korean on Codex, select its runtime-specific entry explicitly:

   ```bash
   bunx skills use https://github.com/epoko77-ai/im-not-ai/tree/main/codex/skills/humanize-korean
   ```

   Read the generated prompt and its supporting-files directory. Omit `--agent`:
   the current executor consumes the instructions. That flag launches another
   interactive agent; it does not choose a Korean package variant. These commands
   load instructions; the executor still performs the requested style pass.
   Reuse the resolved content for the session.
4. Korean execution requires references, role contracts and runnable Python
   scripts. Resolve the matching package from upstream's
   [installation guide](https://github.com/epoko77-ai/im-not-ai/blob/main/INSTALL.md):

   | Runtime | Entry relative to the upstream checkout |
   |---|---|
   | Codex | `codex/skills/humanize-korean/SKILL.md` |
   | Claude Code | `skills/humanize-korean/SKILL.md` |
   | GitHub Copilot | `copilot/skills/humanize-korean/SKILL.md` |
   | Gemini | Follow upstream's `GEMINI.md` extension contract |

   For other Skills CLI loads, use the exact GitHub subpath of the matching
   SKILL.md directory. A repository-wide name selector can choose a different
   runtime variant. Do not assume Claude-specific dispatch or Codex gates are
   available in an unsupported runtime.

   Check supporting files and script indirections before executing. A file that
   exists can still be a launcher depending on paths outside the temporary
   bundle. The current Codex package's launchers call scripts in the original
   repository root; copying those launchers alone does not preserve that root.
   See the upstream [launcher](https://github.com/epoko77-ai/im-not-ai/blob/main/codex/skills/humanize-korean/scripts/prepare_monolith_input.py).

   If the loaded bundle is incomplete, reuse a complete upstream checkout or a
   self-contained installation produced by upstream's installer. When neither
   exists, set `STYLE_SKILL_CHECKOUT` to a new writable task-cache or scratch
   location and fetch the complete repository:

   ```bash
   git clone --depth 1 https://github.com/epoko77-ai/im-not-ai.git "$STYLE_SKILL_CHECKOUT"
   ```

   Load the runtime entry and dependencies from that checkout, resolving symlinks
   to physical paths. This is a fallback for missing execution resources, not a
   requirement to bypass Skills CLI loading.
5. If retrieval, a supported runtime contract, or required resources are unavailable,
   complete the supported translation checks and state that the selected style
   pass was unavailable. Do not claim upstream execution or fall back to another
   language's pattern catalog. Keep upstream files outside OMA-managed definitions.

## Execute within the translation boundary

- **English:** apply Humanizer's embedded mode to the translated draft. Keep its
  pattern definitions and rewrite procedure upstream. Return the owning
  translation task's requested output, without Humanizer's default draft/critique
  wrapper.
- **Korean:** run the matching upstream contract, including its routing, role
  references and deterministic gates. Put input copies and intermediate artifacts
  in a writable scratch working directory. Missing or failing gates are not a
  verified style pass; preserve the safe draft and report the limit. Keep gate
  diagnostics and runtime banners out of translated document content. After the
  gates, use the final prose body as the candidate translation; retain upstream
  summary blocks and gate evidence in scratch rather than the delivered content.
- **Fidelity:** preserve source claims, qualifications, names, numbers, citations,
  emotional force, glossary terms and intended voice. Upstream permissions to add
  reactions, delete content or reorganize a document do not expand this task's
  scope. Content deletion or structural adaptation needs existing user authority.
- **Protected content:** pass editable prose as data. Preserve placeholders, locale
  keys, code, commands, paths, links, headings, table/list structure and untouched
  diff-sync sections. Recheck these against the source after the style pass.
- **Review:** keep proposed rewrites in scratch or memory and return supported
  findings. Do not edit source or target files. Accept zero findings.
- **Execution:** respect the current host's authorization, budgets, tool limits and
  language profile. Reuse bundles; do not reinstall, refresh or launch another
  interactive coding agent for each translation. Persistent installation follows
  the upstream guide and the already authorized scope. Keep the resolved bundle
  fixed for the run and record its revision or version when available.

# Translation Quality Rubric

5 criteria, each scored on a 10-point scale. Total 50 points.

**This file is language-neutral.** Criterion 1 (Naturalness) and criterion 3
(Register) can only be scored against the target language's own conventions, so
score them with `lang/{code}.md` open. A draft that passes every red flag here
and fails its language profile's self-check is not a passing translation.

## Criteria

### 1. Naturalness (10 pts)
Does it read like it was originally written in the target language?

| Score | Description |
|-------|-------------|
| 9-10 | Native speaker cannot tell it's a translation |
| 7-8 | Reads naturally with minor awkwardness |
| 5-6 | Understandable but clearly "translated" |
| 3-4 | Awkward phrasing, unnatural word order |
| 1-2 | Word-for-word translation, painful to read |

Red flags:
- Source language word order leaking through
- Unnatural particles or prepositions
- Overly long sentences that should be split
- Pronouns handled against the target's pro-drop behavior
- Europeanized patterns: unnecessary connectives, passive voice abuse, noun pile-up, over-nominalization, cleft sentence calques
- Any rule in the target's language profile marked as a block-level failure

### 2. Accuracy (10 pts)
Is the meaning fully preserved?

| Score | Description |
|-------|-------------|
| 9-10 | Meaning, nuance, and intent fully preserved |
| 7-8 | Core meaning preserved, minor nuance loss |
| 5-6 | Main idea correct but some details lost |
| 3-4 | Partial meaning distortion |
| 1-2 | Meaning significantly changed or wrong |

Red flags:
- Added meaning not in source
- Omitted important qualifiers
- Reversed logic (negation errors)
- Hallucinated content
- Emotional connotations flattened (e.g., "alarming" rendered as a neutral "surprising" rather than something that carries concern)
- Figurative language translated literally when the image doesn't work in target language

### 3. Register Consistency (10 pts)
Does the tone match the configured register throughout?

The register system itself is language-specific (sentence endings, T-V
distinction, honorific paradigms, or none of these). Read the "Register" section
of `lang/{code}.md` before scoring this criterion.

| Score | Description |
|-------|-------------|
| 9-10 | Perfect register match, consistent throughout |
| 7-8 | Mostly consistent with rare slips |
| 5-6 | Noticeable register shifts |
| 3-4 | Inconsistent: mixes formal and casual |
| 1-2 | Wrong register entirely |

Red flags:
- Register drift between the opening and the closing of a document
- Mixing two register systems that the target treats as mutually exclusive
- Formal vocabulary in casual context or vice versa
- Honorific or politeness level that the source does not support

### 4. Terminology (10 pts)
Are domain terms consistent and correct?

| Score | Description |
|-------|-------------|
| 9-10 | All glossary terms applied, consistent throughout |
| 7-8 | Glossary followed with 1-2 misses |
| 5-6 | Some terms inconsistent across strings |
| 3-4 | Multiple glossary violations |
| 1-2 | Glossary ignored |

Red flags:
- Same source term translated differently in same batch
- Glossary term overridden without justification
- Technical term translated when it should stay in English

### 5. Technical Integrity (10 pts)
Are placeholders, formatting, and structure preserved?

| Score | Description |
|-------|-------------|
| 9-10 | All placeholders, tags, and structure intact |
| 7-8 | Intact with minor formatting differences |
| 5-6 | One placeholder or tag issue |
| 3-4 | Multiple broken placeholders |
| 1-2 | Structure significantly damaged |

Red flags:
- Modified or deleted `{variables}`
- Broken HTML/markdown tags
- Changed JSON/YAML key names
- Added or removed line breaks that affect rendering

## Scoring Guide

| Total | Grade | Action |
|-------|-------|--------|
| 45-50 | Excellent | Ship as-is |
| 38-44 | Good | Minor polish recommended |
| 30-37 | Acceptable | Review flagged items before shipping |
| 20-29 | Needs work | Re-translate problem sections |
| < 20 | Reject | Full re-translation required |

## Quick Self-Check (for translator)

Before submitting, verify:
- [ ] Read the full translation aloud: does it flow?
- [ ] Glossary terms are consistent across all strings
- [ ] Register matches config from start to finish
- [ ] All placeholders survived intact
- [ ] No source language word order leaking through
- [ ] Emotional connotations preserved (not flattened into neutral words)
- [ ] Figurative language handled naturally (interpret/substitute/retain, not literal calques)
- [ ] No Europeanized patterns (passive voice, noun pile-up, forced pronouns, unnecessary connectives)
- [ ] Translator's notes are concise, accurate, and calibrated to target audience
- [ ] The target language's own self-check in `lang/{code}.md` passed

---
name: oma-translation
description: Translate or revise localized UI strings and prose while preserving
  meaning, terminology, placeholders, and structure.
---

# Translation - Context-Aware Localization

## Scheduling

### Goal
Translate, review, or adapt multilingual content faithfully and naturally while preserving the
parts that must remain exact: placeholders, code, links, formatting, terminology, and file
structure.

### Intent signature
- Translate, localize, review a translation, adapt copy, or create a glossary/style guide.
- Update target-language files after the source changed.

### When to use
- UI strings, error messages, locale files, documentation, reports, marketing copy, and prose.
- Review of existing translations for accuracy, register, terminology, or naturalness.

### When NOT to use
- i18n infrastructure, locale registration, or key extraction -> use the relevant development skill.
- Date/pluralization APIs or other code-level localization -> use the owning code-domain skill.

### Expected inputs
- Source text, target language or locale, content type, and requested output mode.
- Existing locale files, glossary, surrounding context, and optional author sample.
- Placeholder and formatting constraints when the source is structured.

### Expected outputs
- Natural target-language text or evidence-backed review findings.
- Exact preservation of placeholders, code spans, links, headings, list structure, and locale keys.
- Translator notes only for meaningful ambiguity or necessary cultural explanation.

### Dependencies
- Target profile: `resources/lang/{code}.md`, if one exists.
- `resources/translation-rubric.md` for substantive content or review.
- Selected external prose-style skills for English and Korean; loading and execution
  are defined in `resources/style-skills.md`.
- Shared prose diagnostics and translation exceptions for other target languages.
- Existing siblings and glossary when translating into a project.

### Control-flow features
- Branches by UI batch versus prose, profile availability, locale variant, ambiguity, and review mode.
- Loads only the target profile and references required for the content type.
- Edits files only when the user asked for file changes.

## Structural Flow

### Entry
1. Identify source, target locale, content type, and whether this is translate, review, or diff-sync.
2. Preserve exact tokens first: placeholders, code, URLs, keys, and structural markers.
3. Load the target profile if available; read sibling translations when the target is in a project.

### Scenes
1. **PREPARE**: Resolve locale, output mode, target audience, and protected syntax.
2. **ACQUIRE**: Read the target profile, relevant siblings, glossary, and source context. Select the substantive prose-style route in the canonical workflow; keep short independent UI strings on the lightweight path.
3. **REASON**: Determine meaning, register, terminology, cultural references, and any ambiguity. Decide whether an idiom should be interpreted, substituted, or retained.
4. **ACT**: Write natural target-language text. Match established project patterns without adding meaning, opinion, or personality.
5. **VERIFY**: Check protected syntax and structure. For substantive text, check meaning, terminology, register, and target-language naturalness against the rubric.
6. **FINALIZE**: Return the requested text, patch, or review with only supported findings.

### Transitions
- A profile exists -> load it; its target-language rules take precedence over shared guidance.
- A locale variant is required -> resolve it before drafting.
- No profile exists -> use shared guidance and note that limit once; do not borrow another language's rules.
- A short independent UI string with established siblings -> use protected-syntax and sibling checks; the full prose review is optional.
- Long prose, documentation, marketing copy, mixed tables/code, or review mode -> use the rubric.
- Ambiguous meaning that changes the result -> ask one targeted question or flag the choice.
- Diff-sync -> modify only source-touched equivalents, located by headings and surrounding context, not line number.

### Failure and recovery
| Failure | Recovery |
|---|---|
| Missing target context | Use the source register and state the assumption, unless the ambiguity changes meaning |
| Conflicting literal wording and project convention | Follow the established target convention and explain a material difference |
| Placeholder or structure mismatch | Revise before emitting or applying a patch |
| Missing profile | Use shared guidance and identify the coverage limit once |
| Unclear cultural reference | Add a concise note only when the target audience needs it |
| Selected external style skill unavailable | Complete supported translation checks and report the unavailable style pass; do not substitute another language's style skill or claim it ran |

### Exit
- Success: the text is faithful, natural, structurally safe, and checked in proportion to content risk.
- Partial: unresolved ambiguity, missing context, or an unavailable selected style pass
  is stated without inventing an answer or claiming that pass ran.

### Language profile loading

Resolve the BCP 47 primary subtag and load one matching profile when present:

| Target | Profile |
|---|---|
| Korean | `resources/lang/ko.md` |
| Japanese | `resources/lang/ja.md` |
| Chinese | `resources/lang/zh.md`; resolve the declared variant |
| English | `resources/lang/en.md` |
| Other | no profile; use shared guidance |

Profiles define typography, register, and target-language checks. Shared guidance explains common
risks. A profile wins if they conflict. Add a new profile from `resources/lang/_template.md` only
when the task is to extend this skill.

### Translation method

1. Read for meaning, intended effect, domain terms, and protected syntax. Identify figurative
   wording as **interpret**, **substitute**, or **retain**. Do not add a new metaphor or remove an
   intentional one without a reason.
2. Choose register from the source, target audience, and sibling translations. Apply
   `translation_voice` from `.agents/oma-config.yaml` only as a rhythm/formality preference:
   `formal`, `balanced` (default), or `interpreter`. It never overrides meaning or target norms.
3. Reconstruct in the target language. Change word order, split or merge sentences, and omit
   implied subjects only when the target language calls for it.
4. Preserve author style only where it belongs: prose, dialogue, adaptation, or explicitly
   user-authored documentation. Match observable rhythm and diction, never add facts, stance,
   jokes, first person, or stronger emotion.

### Verification

Always check:

- Every placeholder, code span, identifier, URL, and locale key is unchanged.
- Headings, links, table rows, list nesting, and code blocks retain their structure.
- The target follows its profile's typography and register rules.
- Existing siblings are matched when they establish terminology or UI style.

For substantive content and review mode, also check the rubric: meaning, naturalness,
terminology, register, cultural fit, and emotional force. Apply the selected target-language
style route while preserving intentional source style and content.

### Review mode

Review from evidence, not from an expectation that every draft is machine-translated. Record zero
findings when no material defect is confirmed. Separate:

- **Accuracy or safety defects**: changed meaning, broken placeholder, incorrect term, or wrong register.
- **Supported style findings**: a concrete target-language issue with a reason and proposed fix.
- **Preferences**: optional alternatives that do not make the existing translation wrong.

Do not rewrite a sound translation merely to produce findings.

### Batch and diff-sync work

For batches, read the complete set first, translate values only, and maintain one terminology and
register decision. Verify placeholders and key structure across the set.

For diff-sync, map each source hunk by heading and surrounding context. Touch only the affected
target section; leave unrelated text byte-identical. State updated sections, skipped cosmetic
hunks, and material terminology decisions.

### Output formats

For a single text, present the translation and brief notes for ambiguities or adaptations. For
files, preserve the input format and modify only requested values. For review, show the original,
the suggested revision only when warranted, and the evidence for each finding.

## Logical Operations

### Actions
| Action | SSL primitive | Evidence |
|---|---|---|
| Resolve locale and mode | `SELECT` | User request and file context |
| Read profile and siblings conditionally | `READ` | Target profile, glossary, nearby translations |
| Protect syntax and structure | `VALIDATE` | Source tokens and structural markers |
| Infer meaning and register | `INFER` | Source, audience, project convention |
| Translate or revise | `WRITE` | Target text or requested file patch |
| Review substantive content | `VALIDATE` | Rubric and concrete findings |
| Report result and limits | `NOTIFY` | Translation, patch, or review |

### Tools and instruments
- Native search/read for local source and sibling translations.
- Configured `code_intelligence` capability when available for code-context navigation; native
  search/read when it is unavailable or times out.
- Target profile, rubric, selected prose-style implementation, and language-template
  resources as selected by the canonical workflow.

### Canonical workflow path
1. Resolve target locale and protect exact syntax.
2. Load the one applicable language profile and relevant siblings; load the rubric for substantive
   content or review. For substantive prose, select by the **target** BCP 47 primary subtag:
   - `en` (including regional variants): load `resources/style-skills.md` and resolve `humanizer`.
   - `ko` (including regional variants): load that resource and resolve `humanize-korean`.
   - Other languages: load `references/_shared/core/anti-ai-prose.md` with
     `resources/anti-ai-patterns.md` and the target profile.
   Short independent UI strings with established siblings need protected-syntax and
   sibling checks; they do not require an external prose-style pass.
3. Infer meaning, register, terminology, and figurative-language handling.
4. Draft in natural target order and project style.
5. Apply the selected style implementation to the draft, preserving review-only mode
   and translation fidelity. Then verify exact syntax, terminology, source claims,
   structure and diff-sync scope, and check substantive content against the rubric.
6. Emit the requested translation, patch, or evidence-backed review. State a missing-profile or
   context limitation when material.

### Resource scope
| Scope | Resource target |
|---|---|
| `LOCAL_FS` | Source/target files, glossaries, language profiles |
| `CODEBASE` | Sibling translations and code context |
| `PROCESS` | Syntax checks and selected external-skill acquisition or local gates |
| `NETWORK` | Upstream style-skill retrieval when not already available |
| `MEMORY` | Locale, terminology, register, protected syntax, unresolved ambiguity |

### Effects and side effects
- Produces translated text or review findings.
- Changes locale/docs files only when explicitly requested.
- Retains source structure, identifiers, and placeholders.
- May retrieve a missing selected style-skill bundle; reuses installed or cached
  instructions. Upstream intermediate files stay in a writable scratch workspace.

### Guardrails
1. Preserve meaning, protected syntax, and file structure before stylistic preference.
2. Do not invent facts, opinions, emotional emphasis, examples, citations, or personality.
3. Do not use a different language's profile as a substitute.
4. Do not change untouched sections during diff-sync.
5. Do not claim completion of a check that the available source cannot support.

## References

- Translation rubric: `resources/translation-rubric.md` (load for substantive content or review)
- Selected style skills: `resources/style-skills.md` (English or Korean substantive prose)
- Common prose diagnostics: `references/_shared/core/anti-ai-prose.md` (other target languages, with translation exceptions when prose style needs review)
- Translation exceptions and grammar diagnostics: `resources/anti-ai-patterns.md` (other target languages, with common diagnostics when prose style needs review)
- Target profiles: `resources/lang/{ko,ja,zh,en}.md` (load one matching profile)
- Profile template: `resources/lang/_template.md` (only when adding a profile)
- Shared context loading: `references/_shared/core/context-loading.md`
- Shared quality principles: `references/_shared/core/quality-principles.md`