@polderlabs/bizar-omp 0.2.0 → 0.3.0

package/skills/omp-native-development/assets/tests/native-role-contract.test.ts

@@ -0,0 +1,96 @@
+/** Starter source-coupled native tests: NOT RUN in the skill-creation environment.
+ * Copy into a project with the qualified @oh-my-pi/pi-coding-agent dependency.
+ * Run with Bun. The helpers are native imports, not a duplicate Bizar resolver.
+ * These tests do not create sessions or prove provider/child execution behavior.
+ */
+import { describe, expect, test } from "bun:test";
+import {
+  expandRoleAlias,
+  extractExplicitThinkingSelector,
+  resolveAgentAdvisorSelection,
+  resolveAgentModelSelection,
+  resolveAgentPrewalkPattern,
+  resolveExplicitModelRole,
+} from "@oh-my-pi/pi-coding-agent/config/model-resolver";
+import { Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
+
+function settings() {
+  return Settings.isolated({
+    modelRoles: {
+      default: "fixture/default",
+      task: "fixture/task",
+      bizar_build: "fixture/build",
+      bizar_review: "fixture/review",
+      bizar_outer: "@bizar_review",
+    },
+  });
+}
+
+describe("native Bizar role resolution contracts", () => {
+  test("custom role is expanded while identity survives", () => {
+    expect(resolveAgentModelSelection({ agentModel: "@bizar_build", settings: settings() }))
+      .toEqual({ patterns: ["fixture/build"], role: "bizar_build" });
+  });
+  test("native agent settings override wins over frontmatter", () => {
+    expect(resolveAgentModelSelection({
+      settingsOverride: "@bizar_review", agentModel: "@bizar_build", settings: settings(),
+    })).toEqual({ patterns: ["fixture/review"], role: "bizar_review" });
+  });
+  test("internal request override is distinct from public task schema", () => {
+    expect(resolveAgentModelSelection({
+      requestModel: "@bizar_build", settingsOverride: "@bizar_review", settings: settings(),
+    })).toEqual({ patterns: ["fixture/build"], role: "bizar_build" });
+  });
+  test("empty internal request does not suppress configured override", () => {
+    expect(resolveAgentModelSelection({
+      requestModel: "", settingsOverride: "@bizar_review", settings: settings(),
+    })).toEqual({ patterns: ["fixture/review"], role: "bizar_review" });
+  });
+  test("custom role aliases can chain", () => {
+    expect(resolveAgentModelSelection({ agentModel: "@bizar_outer", settings: settings() }))
+      .toEqual({ patterns: ["fixture/review"], role: "bizar_outer" });
+  });
+  test("legacy aliases preserve role identity", () => {
+    expect(resolveAgentModelSelection({ agentModel: "pi/bizar_build", settings: settings() }))
+      .toEqual({ patterns: ["fixture/build"], role: "bizar_build" });
+  });
+  test("singleton default agent selector inherits active session", () => {
+    expect(resolveAgentModelSelection({
+      agentModel: "@default", activeModelPattern: "fixture/active", settings: settings(),
+    })).toEqual({ patterns: ["fixture/active"], role: undefined });
+  });
+  test("configured task role beats parent fallback for @task agent", () => {
+    expect(resolveAgentModelSelection({
+      agentModel: "@task", activeModelPattern: "fixture/active", settings: settings(),
+    })).toEqual({ patterns: ["fixture/task"], role: "task" });
+  });
+  test("bare model identity is not an explicit role", () => {
+    expect(resolveExplicitModelRole("fixture/build", settings())).toBeUndefined();
+  });
+  test("explicit outer effort selector is recognized by native parser", () => {
+    expect(extractExplicitThinkingSelector("@bizar_review:low", settings())).toBe("low");
+  });
+  test("alias expansion uses configured custom role", () => {
+    expect(expandRoleAlias("@bizar_outer", settings())).toBe("fixture/review");
+  });
+  test("prewalk default is native smol", () => {
+    expect(resolveAgentPrewalkPattern({ agentPrewalk: true })).toBe("@smol");
+  });
+  test("prewalk override can disable frontmatter opt-in", () => {
+    expect(resolveAgentPrewalkPattern({ settingsOverride: "off", agentPrewalk: true })).toBeUndefined();
+  });
+  test("prewalk on retains explicit agent target", () => {
+    expect(resolveAgentPrewalkPattern({ settingsOverride: "on", agentPrewalk: "@bizar_build" }))
+      .toBe("@bizar_build");
+  });
+  test("advisor is absent without opt-in", () => {
+    expect(resolveAgentAdvisorSelection({})).toBeUndefined();
+  });
+  test("advisor settings can disable frontmatter opt-in", () => {
+    expect(resolveAgentAdvisorSelection({ settingsOverride: "off", agentAdvisor: true })).toBeUndefined();
+  });
+  test("advisor on retains explicit agent model pattern", () => {
+    expect(resolveAgentAdvisorSelection({ settingsOverride: "on", agentAdvisor: "@bizar_review" }))
+      .toEqual({ model: "@bizar_review" });
+  });
+});

package/skills/omp-native-development/references/accuracy-and-versioning.md

@@ -0,0 +1,63 @@
+# Accuracy, evidence and version qualification
+
+## Contents
+1. Scope and confidence
+2. Target fingerprint
+3. Evidence hierarchy
+4. Documentation acquisition
+5. Updating the skill
+6. Source references
+
+## Scope and confidence
+
+This is an authored engineering skill plus an exhaustive index of the Markdown files in the pinned upstream `docs/` tree. It is not a complete offline copy of the repository, not an implementation of Bizar, and not an assurance that every documented behavior is correct on every installed release.
+
+The most detailed audit concerns the native integration contracts: agents, model roles, settings, extensions, task execution, isolation, lifecycle and SDK boundaries. Other documentation is indexed for targeted retrieval. The manifest states which documents were reviewed in ranges and which were indexed only. Do not convert navigation coverage into a claim of exhaustive behavioral testing.
+
+Separate five kinds of statement: DOCUMENTED, SOURCE-OBSERVED, TESTED, PROPOSED and UNKNOWN. Documentation describes intended behavior. Source identifies an implementation at a commit. Upstream tests specify expectations but are not proof that those tests passed in the developer's environment. Only an executed test with recorded output earns TESTED.
+
+## Target fingerprint
+
+Research source: `can1357/oh-my-pi@dbf3afad4894bde827d90f965e77b3fe1c5a95e5`.
+Comparison release: `v18.2.4@1c0303b1f2ec515cbf4b44a9a49d68a029531aac`.
+The source main snapshot is ahead of that release and includes TUI-related changes. Both can present a package version of 18.2.4. Therefore compare artifacts/commits, not just a semver string.
+
+Record the installed package name/version, lockfile integrity or binary checksum, source SHA when available, Bun version, OS/architecture, execution mode, profile, agent directory, cwd, project settings and overlays. Include which facts are unavailable. Do not assert an installed binary's source commit solely because its version matches a Git tag.
+
+The package's Bun minimum and the monorepo's package-manager/build requirement are different surfaces. Re-read the target package manifest and root toolchain configuration rather than treating one minimum as universal.
+
+Pin the published package in the developing project. Qualify the release build first when that is the deployment target. Run a separate canary for upstream main; never silently replace production dependencies with main to make a test pass.
+
+## Evidence hierarchy
+
+For a concrete behavior, use the target's runtime observations and relevant tests, exported types, implementation callsites, and exact documentation together. None can be mechanically substituted for all others. A declared callback with no callsite is not a functioning integration seam. A wildcard export that permits importing an internal class is not a maintenance guarantee.
+
+Prefer immutable repository links with line anchors. Record the file's Git blob SHA or digest where practical. Compare documentation with the actual installed code when they disagree. Preserve a short discrepancy note and regression case, and label the uncertainty rather than choosing the most convenient interpretation.
+
+Treat public web pages, model catalogs, release notes and endpoint behavior as time-sensitive. Generic pi-mono documentation, tutorial snippets and forks may describe a different API. Use them only as leads; verify against this repository and revision.
+
+For claims beyond these references, retrieve the relevant source instead of extrapolating from a similar tool. When no supporting source or executable environment exists, report UNKNOWN, with the smallest required experiment.
+
+## Documentation acquisition
+
+`source-manifest.json` contains the pinned paths and expected Git blob identities. `omp_docs.py sync` downloads each file from the exact commit or reads Git objects locally. It validates the bytes against Git's blob hashing format and refuses to overwrite a different existing file. A redirect to HTML, truncated content or stale page will fail hash validation instead of entering the corpus as documentation.
+
+The fetcher verifies each selected file. The checked-in manifest covers the root docs Markdown inventory and selected sources; package-local READMEs and additional sources must be retrieved separately as the task requires. It does not crawl random external links or run repository code.
+
+The source manifest stores expected upstream identities obtained from GitHub; these are not claims that full files are already present locally. The complete upstream text was not bundled during skill creation because container network access was unavailable. The online fetch path is provided and tested through controlled mocks, not an actual successful network download in this environment.
+
+Use `verify` after syncing. A partial corpus must be reported as partial. Literal search emits line-numbered hits, not semantic conclusions; read the surrounding definition and caller before implementing.
+
+## Updating the skill
+
+Run `drift --repo PATH` against a local checkout to compare tracked paths at HEAD. This only detects changes/deletions in known files; inspect the tree for newly introduced documents and APIs. Do not interpret zero tracked differences as proof that the entire repository is unchanged.
+
+For an upgrade, create a new target fingerprint, enumerate its complete docs tree, retrieve changed source/test files, re-run affected native tests, revise the claim register and templates, and only then update the pin. Keep the previous pin available for rollback. Never change the manifest SHA alone while retaining old hashes and asserting compatibility.
+
+## Source references
+
+- [Research main ref](https://github.com/can1357/oh-my-pi/commit/dbf3afad4894bde827d90f965e77b3fe1c5a95e5)
+- [Comparison release ref](https://github.com/can1357/oh-my-pi/commit/1c0303b1f2ec515cbf4b44a9a49d68a029531aac)
+- [Package manifest](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/package.json)
+- [SDK contract](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/sdk.md)
+- [Porting and divergence](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/porting-from-pi-mono.md)

package/skills/omp-native-development/references/agent-and-model-roles.md

@@ -0,0 +1,158 @@
+# Native agent and model roles: integration contract
+
+Snapshot: `dbf3afad4894bde827d90f965e77b3fe1c5a95e5`. These are version-bound contracts, not provider recommendations. Read the sources at the end when implementing.
+
+## Contents
+1. Distinguish identities
+2. Built-in and custom model roles
+3. Agent discovery and definitions
+4. Dispatch and model precedence
+5. Alias, inheritance and selector edge cases
+6. Effort and service tiers
+7. Prewalk, advisors and fallback
+8. Configuration ownership and live changes
+9. Skills, tagged models and Vibe
+10. Bizar implementation requirements
+11. Source references
+
+## 1. Distinguish identities
+
+An **agent type** is a discovered definition such as `bizar-reviewer`: its instructions, permitted tools, spawn policy and model selector defaults. A **spawned agent ID** identifies one runtime instance and its artifacts. A **model role** is a settings-backed selector such as `bizar_review`, addressed as `@bizar_review`. A **concrete model** is a provider/model identity chosen after native resolution. **Thinking effort** configures reasoning behavior. A **service tier** configures a provider's service treatment. A **transport** describes how requests reach an endpoint.
+
+Do not use agent names as model names, service tiers as effort levels, or registry IDs as reusable specialist definitions. Do not conflate the bundled `task` agent, the native `task` tool, and the `task` model role merely because they share a word.
+
+## 2. Built-in and custom model roles
+
+The source-defined built-ins at this pin are:
+
+| Role | Native purpose or interpretation |
+| --- | --- |
+| `default` | Default main-session selection |
+| `smol` | Fast/lightweight selection |
+| `slow` | Stronger/thinking selection |
+| `vision` | Vision-oriented selection |
+| `plan` | Architect/planning selection |
+| `commit` | Commit-oriented selection |
+| `tiny` | Online lightweight background work such as titles, memory and classification |
+| `task` | Subtask selection |
+| `advisor` | Advisor selection |
+
+These labels do not themselves guarantee model speed, capability, price, vision, or supported reasoning. Those properties depend on actual resolution and provider behavior. `title` and `designer` are not built-ins in this snapshot; a user could still create custom roles with those names.
+
+Custom roles are supported. `modelRoles`, `cycleOrder`, and `modelTags` can contribute known role IDs to UI metadata. However, a display tag or cycle entry alone is not a concrete model assignment. Resolve the role before using it as a required worker dependency.
+
+The canonical alias is `@role`; `pi/role` is a supported compatibility spelling. `*` selects the default role. Quote aliases in YAML. A role can refer to another role, including an explicit effort suffix. Do not impose the false rule that all native role mappings must point directly to concrete models.
+
+## 3. Agent discovery and definitions
+
+Task agents are read from native `.omp` roots and package `agents/` directories. At this pin, the first exact agent name wins in the following order: nearest project `.omp/agents`, user `.omp/agent/agents`, enabled OMP extension-package agent roots (CLI, project settings, user settings, installed packages), supported Claude marketplace plugin roots, then bundled definitions.
+
+Direct `.claude/agents`, `.codex/agents`, and `.gemini/agents` roots are intentionally not equivalent to native task-agent definitions. Their frontmatter may mean something different. Names are case-sensitive; directory filenames are sorted before deduplication. Project definitions can legitimately shadow package definitions. Diagnose the effective file/source, rather than assuming a bundled Bizar file won.
+
+An agent needs `name` and `description` frontmatter plus a prompt body. Relevant fields include `tools`, `spawns`, prioritized `model`, `thinking-level` or `thinking`, `output`, `blocking`, `autoloadSkills`, `read-summarize`, `prewalk`, and `advisor`. `model` accepts a selector, CSV or an array. `tools` accepts CSV or an array; explicit tools cause `yield` to be added by native parsing.
+
+`spawns` may be a wildcard or a list. A legacy convenience maps missing `spawns` plus a `task` tool to wildcard spawn permission. Avoid inadvertently enabling nested delegation in a worker. Do not describe a tools list as a filesystem sandbox.
+
+Missing/invalid custom definitions can be skipped with warnings. That is why packaging must test discovery of every expected name, not merely check that files exist. Native bundled agents in this snapshot are `scout`, `reviewer`, `security-reviewer`, `task`, and `sonic`.
+
+## 4. Dispatch and model precedence
+
+The model-facing task batch uses this form when batch mode is enabled:
+
+```json
+{
+  "context": "Shared background and references for this batch.",
+  "tasks": [
+    {
+      "agent": "bizar-reviewer",
+      "task": "Review the exact candidate revision and report evidence-backed findings."
+    }
+  ]
+}
+```
+
+Do not add a public `model` field. Select a native agent whose defaults and configured overrides resolve the desired model policy. In batch mode, `agent` belongs to each item, not the batch envelope. The public eval helper must also be checked separately; an internal `StructuredSubagentRequest.model` field is not proof that the model-facing `agent()` helper accepts it.
+
+The ordinary task selection precedence is:
+
+1. `task.agentModelOverrides[exactAgentName]`, when it resolves to nonempty configured patterns.
+2. The agent definition's model selector(s), with native inheritance exceptions.
+3. The parent's active selection, its configured fallback, then the native default lookup as applicable.
+
+The internal shared selector also accepts a higher-priority request override for callers that actually supply that field. Do not expose or emulate this as a fictional public task parameter.
+
+Native task/eval preflight reloads persisted settings and rediscovers agents. Separate create-time descriptions may be cached, so discovery text shown earlier can lag execution-time state. The correct implementation is to preserve the native execution path, not freeze a copy of the picker options in Bizar.
+
+## 5. Alias, inheritance and selector edge cases
+
+The native resolver returns expanded patterns together with the original explicit role. Preserve both. Deriving the role from the final model identity loses information needed by role-based retry fallback.
+
+For source-coupled contract tests, `resolveAgentModelSelection` is the relevant helper; isolate its import behind a pinned test/adapter boundary. Do not duplicate it in Bizar's business logic. Its result includes `patterns` and `role`, and its source selection is made in one operation.
+
+Special inheritance matters. A singleton agent model `default`, `@default`, `*`, or `pi/default` participates in session inheritance rather than necessarily forcing a different globally saved default. A singleton `@task`/`pi/task` uses configured task patterns when present; otherwise native fallback can inherit the session. Replacing these with eagerly resolved strings can change semantics.
+
+Unconfigured `smol` and `slow` can inherit a configured default before their built-in priority lists. `tiny` falls back through `smol`. `advisor` can use explicitly configured `slow`, but when that is absent it uses the corresponding priority route rather than indiscriminately inheriting the primary. This is not a guarantee of a distinct provider or model family; inspect the actual result for independent review.
+
+Explicit effort on an outer role can override inherited role effort. Selectors may contain colon-bearing model IDs and upstream routing. Use native parsing and model metadata, not `split(':')`, `split('@')`, string truncation, or a guessed suffix list.
+
+Native role-cycle handling has fallback behavior; it does not universally throw a cycle error. Bizar's static profile linter deliberately rejects explicit cycles as its own configuration-quality policy. Label that error as Bizar policy rather than misdescribing native behavior.
+
+## 6. Effort and service tiers
+
+When `task.enableEffort` is enabled, a task item can request `lo`, `med`, or `hi`; this surface is absent from the model-facing schema when disabled. The coarse value maps onto the resolved model's supported reasoning ladder and is constrained by `task.maxEffort`. The cap survives retry-fallback switches. Unsupported combinations need a visible error or the documented native fallback for noncontrollable models, not a fabricated effort value.
+
+Agent frontmatter thinking defaults, role suffixes, per-item effort and native auto-thinking are distinct inputs. Exercise their precedence with the target resolver/executor tests. A same-model change in effort can still be a meaningful prewalk transition.
+
+Service tier is independent. `task.agentServiceTierOverrides[exactAgentName]` overrides `tier.subagent` for the documented task/eval route. `inherit` snapshots the parent's live per-family tier map at spawn. The child resolves the concrete value against its final model family. Unsupported families do not inherit unrelated provider settings; same-family and cross-family fallback behavior differ.
+
+Persisted tier state, including an explicitly empty map, matters on revival. Service-tier controls are configuration settings, not native agent frontmatter or task/eval wire fields. Vibe workers use `tier.subagent` rather than this exact task/eval override path at the inspected revision.
+
+Never send `priority` everywhere, assume `high` is a service tier, or use a service tier to select a model. Do not inflate cost estimates by conflating effort with premium service pricing.
+
+## 7. Prewalk, advisors and fallback
+
+`prewalk: true` opts an agent into the native default handoff target `@smol`; a string chooses a target selector. `task.agentPrewalk[name]` can override it with quoted `on`, `off`, or a pattern. The handoff occurs at the native first edit/write boundary. Unavailable targets are skipped by the documented behavior; an exact model-and-effort no-op is skipped, while a same-model effort downgrade is meaningful.
+
+`advisor: true` opts the child into `@advisor`; a string can specify a selector. `task.agentAdvisor[name]` takes precedence. Children default to no advisor unless opted in. Preserve native persistence and cleanup; do not add another background review daemon or accidentally enable advisors in every child.
+
+Distinguish initial prioritized pattern selection, authentication fallback, API-error retry fallback, context promotion and prewalk. They are not one interchangeable fallback list. Native auth-aware resolution can use the parent's model when an intended worker model lacks usable credentials; keyless local providers use a sentinel and must not be mistaken for unauthenticated remote services.
+
+Record actual `resolvedModel`, fallback indicators and subsequent model changes. A required local-only or approved-provider contract must detect a prohibited effective model before execution through a tested admission seam; merely documenting the fallback after sensitive data was sent is insufficient. Do not claim Bizar has such an enforcement seam until the relevant native path is qualified.
+
+Native retry chains may be keyed by the originating role. Context promotion instead consults explicit model metadata and uses temporary switching without rewriting saved role assignments. Gateway retries and OMP retries are separate layers: cap and observe them rather than multiplying unbounded retries.
+
+## 8. Configuration ownership and live changes
+
+Use `modelRoles` in native settings, not a Bizar replacement router. Preserve `task.agentModelOverrides`, role tags, cycle order and native role storage. Ordinary `omp config set/reset` writes global settings; the model selector can save role assignments to project config when `modelRoleStorage: project`. Do not assume a command launched in a repository writes project-local settings.
+
+Global, project, explicit overlays and runtime overrides participate in native precedence. Objects deep-merge; arrays replace. Project settings discovery is cwd-local, unlike nearest-project agent discovery. Profiles and relocated agent directories change the effective global path.
+
+If an operator changes a role during a live session, native subsequent dispatch should reflect the new configuration. Bizar can record a settings revision and require re-admission when reproducibility demands it, but it must not secretly overwrite the operator's change or claim the old plan froze native settings.
+
+## 9. Skills, tagged models and Vibe
+
+A developing agent can specify `autoloadSkills: [omp-native-development]`. Native autoloading refers to the parent's discovered skills. Unknown names are ignored, so validate actual discovery and child injection. Do not assume a YAML entry alone proves this skill reached the child.
+
+Composer-tagged models receive session/branch-local pseudonyms such as `m1`. They use the generic task template, not an arbitrary Bizar specialist. They survive supported session resume behavior but are not global identifiers; rewinding can change their registration. Honor explicit user model tagging without silently replacing the requested model with a specialist default.
+
+Vibe `fast` routes through bundled `sonic`; `good` routes through bundled `task`. Native `task.agentModelOverrides` and role-backed selectors participate. Verify this separately from task/eval service-tier behavior. Do not override those global bundled agents merely to install Bizar's specialist pack.
+
+## 10. Bizar implementation requirements
+
+Ship namespaced agents and an opt-in, merge-only configuration example. The example role graph may alias existing native roles (`bizar_build -> @task`, `bizar_review -> @slow`) without selecting a new vendor. Do not install concrete models, provider endpoints or premium tiers automatically.
+
+Expose requested agent, source definition, requested role, winning selector source, actual model, reasoning, service tier and fallback/prewalk transitions in diagnostics. Mark unavailable details UNKNOWN; never infer OAuth account identities or sensitive metadata from debug logs.
+
+Use static lint for shape/cycles/placeholders, native resolver probes for actual role resolution, and real child execution receipts for effective worker routing. All three layers are necessary. The supplied probes do not by themselves prove the entire integration works.
+
+## 11. Source references
+
+- [Agent definitions, discovery and routing](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/task-agent-discovery.md)
+- [Built-in role definitions](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/src/config/model-roles.ts)
+- [Model selector implementation, including inheritance and role identity](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/src/config/model-resolver.ts#L970-L1570)
+- [Native resolver tests](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/test/model-resolver.test.ts)
+- [Model configuration and authentication](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/models.md)
+- [Settings, role storage, thinking and tiers](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/settings.md)
+- [Task/eval shared policy implementation](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/src/task/structured-subagent.ts)
+- [Retry behavior and settlement](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/non-compaction-retry-policy.md)
+- [Skills and child autoloading](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/skills.md)

package/skills/omp-native-development/references/bizar-integration-contract.md

@@ -0,0 +1,100 @@
+# BizarHarness: agent and model-role integration addendum
+
+Date: 2026-09-17. This extends the BizarHarness OMP-native rewrite plan. All architecture and acceptance requirements here are PROPOSED until implemented and tested. Native behavior references are pinned to `dbf3afad4894bde827d90f965e77b3fe1c5a95e5`.
+
+## Contents
+1. Architectural decision
+2. Semantic agent and model roles
+3. Configuration contract
+4. Dispatch and observation
+5. Effective model changes
+6. Engineering work packages
+7. Release gates
+8. Source references
+
+## 1. Architectural decision
+
+Bizar must be a native OMP extension and workflow/evidence layer. It must not implement a competing model picker, hard-coded gateway router, worker registry, credential store or job lifecycle. OMP owns native resolution and execution. Bizar adds task scope, acceptance criteria, evidence requirements and integration policy.
+
+Agent roles and model roles must remain independently configurable. An operator must be able to change the model behind a specialist without editing its prompt, changing the workflow definition, or bypassing OMP's native override precedence. Installing Bizar must not replace an operator's main model or remap unrelated bundled agents.
+
+The default main OMP session performs coordination. Do not add a mandatory nested coordinator for every prompt. Delegate when specialization, independent review, isolation or useful parallelism justifies it.
+
+## 2. Semantic agent and model roles
+
+Use namespaced specialist definitions and role names. The following is a proposed starting profile, not a native built-in roster:
+
+| Bizar agent | Requested model role | Optional default alias | Purpose |
+| --- | --- | --- | --- |
+| `bizar-researcher` | `@bizar_research` | `@plan` | Evidence-grounded investigation and specification |
+| `bizar-planner` | `@bizar_plan` | `@plan` | Dependencies, scope and acceptance criteria |
+| `bizar-implementer` | `@bizar_build` | `@task` | Focused implementation in the assigned workspace |
+| `bizar-reviewer` | `@bizar_review` | `@slow` | Independent correctness review of exact candidate changes |
+| `bizar-security-reviewer` | `@bizar_security` | `@slow` | Threat- and evidence-driven security review when warranted |
+| `bizar-verifier` | `@bizar_verify` | `@task` | Reproducible verification receipts |
+
+Default aliases intentionally reuse native operator choices. They do not promise a specific capability, speed, cost or independent model family. Let operators assign concrete provider/model selectors through native configuration. A requirement for independent model-family review needs actual resolved-family checks and explicit behavior when no suitable alternative is available.
+
+Keep existing user-specific model tiers as migration inputs, not runtime API assumptions. Legacy Claude aliases can be translated into proposed native mappings during an explicit migration. Do not globally redefine `smol`, `slow`, `task`, `default`, or `advisor` without a requested and displayed configuration change.
+
+## 3. Configuration contract
+
+Ship an example fragment, not an automatically applied replacement configuration. Merge missing Bizar mappings only after inspection and explicit setup. Preserve any existing Bizar mapping and each exact-name `task.agentModelOverrides` entry. Preserve `modelTags`, `cycleOrder`, enabled model scope, disabled providers, role storage, thinking settings, service tiers, prewalk and advisor settings.
+
+Use ordinary native settings for role-to-model selection. Bizar's own configuration should concern workflows, evidence and admission constraints, not a second copy of OMP's model registry. Missing required mappings or conflicting strict constraints produce a clear diagnostic. They must not cause silent fallback to an arbitrarily chosen Bizar model.
+
+Keep project/global/profile behavior explicit. A schema-aware setup process must show the target file, existing value, proposed value and rollback record. Ordinary native settings commands are not a general project-local writer. Test profile relocation, cwd-local project settings and array replacement behavior.
+
+Run static profile lint, then native role resolution, then an actual child routing test. Only the last establishes the model that a spawned specialist really used. The configured role alone is not authoritative evidence of execution.
+
+## 4. Dispatch and observation
+
+Native task payloads identify the specialist by `agent`; do not send nonexistent per-task model fields. Use exact names and inspect which source definition won native discovery. Preserve native parent spawn/depth restrictions and skill autoload behavior.
+
+Record the following when observable from supported interfaces: run/task ID, native spawned ID, agent name and source, settings revision, requested role, winning override source, resolved provider/model, effective reasoning selector, service tier, fallback flags, native job status, output schema, artifact references and final verification outcome. Mark unobservable fields UNKNOWN; do not fabricate them from prompt text.
+
+The settings/profile snapshot must be sanitized. Never persist API keys, OAuth refresh/access tokens, credential commands' output or full request headers into workflow evidence. Do not record provider-family tokens as permanent identifiers when native APIs document them as opaque comparison values.
+
+Native preflight refreshes settings and agent definitions. To require reproducible selection, store an expected configuration revision and re-admit if it changed; do not bypass native refresh by using stale Bizar caches. UI role changes must affect subsequent native dispatch or produce an explicit strict-profile conflict, never be silently ignored.
+
+## 5. Effective model changes
+
+Treat model changes as first-class execution events. Initial role expansion, authentication fallback, per-role API retry fallback, context promotion and prewalk are distinct transitions. Preserve original role identity for fallback chains and final effective identity for evidence.
+
+For ordinary autonomy, allow supported native transitions and make them visible. For an explicit local-only, approved-provider, minimum-context or capability requirement, validate the actual effective target before data leaves the permitted boundary. An after-the-fact log cannot enforce a pre-execution privacy restriction. Until all relevant task/eval paths expose qualified admission, label that strict profile unsupported rather than claim universal enforcement.
+
+Service-tier and thinking changes must also be tracked separately. A provider-family fallback cannot inherit an unrelated family's tier. A prewalk to the same model with different effort is still a meaningful transition. Advisor opt-in must remain opt-in and must survive native resume behavior correctly.
+
+Do not disable native eval/code mode, model switching, prewalk, advisors or tagged-model selection merely because they complicate the harness. Implement parity, explicitly scope a supported profile, or propose a narrow upstream integration seam with tests.
+
+## 6. Engineering work packages
+
+**ROLE-01: Inventory and schema qualification.** Enumerate current Bizar agents and map them to native specialist definitions. Read the exact target's model-role resolver, agent discovery, settings schema and task/eval bridge. Produce an effective-source report and a source-versus-release compatibility decision.
+
+**ROLE-02: Native role profile and discovery.** Add the namespaced agent pack and an opt-in role fragment. Implement merge-only setup and source-aware diagnosis. Test global/project/profile precedence, custom role chains, aliases, agent shadowing and skill discovery.
+
+**ROLE-03: Dispatch adapter.** Keep native task execution and role selection. Isolate any source-coupled imports. Prove access to lifecycle and settled result data without interpreting text acknowledgements as completion. Cover flat/batch, sync/async and the supported eval paths.
+
+**ROLE-04: Selection provenance.** Record requested role and actual model, plus effectful transitions. Expose a read-only route explanation. Do not create a picker that shadows the native model UI. Build an explicit UNKNOWN path for metadata that the host does not expose.
+
+**ROLE-05: Dynamic controls.** Qualify effort caps, prewalk, advisors, role-specific retry fallback, service tiers, provider disabling, context promotion and user-tagged models. Add strict-profile admission only where the relevant pre-execution boundary is proven.
+
+**ROLE-06: Qualification and documentation.** Implement all applicable cases in the validation matrix. Run a mocked provider suite and opt-in live gateway/provider smoke tests. Publish a tested version matrix and regenerate role/agent documentation from canonical definitions rather than maintaining contradictory prose.
+
+## 7. Release gates
+
+A release is not role-native merely because a role string appears in frontmatter. Require evidence that the intended specialist was discovered, the operator override won, the intended role resolved, the real child used the expected target, supported transitions retained provenance, configuration remained unchanged unless explicitly requested, and unsupported combinations failed visibly.
+
+Require task/eval isolation-application parity for managed writers. Require actual settlement before verification/integration. Require stale evidence invalidation after changes. Require cancellation/resume and multi-session tests that demonstrate no model, role or state leakage.
+
+This addendum and its asset templates are design inputs for the developing agent. They do not constitute a implemented Bizar release or successful runtime qualification.
+
+## 8. Source references
+
+- [Native roles and discovery](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/task-agent-discovery.md)
+- [Model-role source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/src/config/model-roles.ts)
+- [Native resolver source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/src/config/model-resolver.ts)
+- [Settings and native role persistence](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/settings.md)
+- [Extension API](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/extensions.md)
+- [Task contract](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/task.md)
+- [Shared subagent policy](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/src/task/structured-subagent.ts)

package/skills/omp-native-development/references/bundle-validation.json

@@ -0,0 +1,54 @@
+{
+  "created": "2026-09-17",
+  "checks": {
+    "skill_frontmatter_and_size": "PASS",
+    "json_and_yaml_syntax": "PASS",
+    "authored_relative_markdown_links": {
+      "status": "PASS",
+      "checked": 17
+    },
+    "source_pin_schema": {
+      "status": "PASS",
+      "upstream_file_bytes_verified_here": false
+    },
+    "agent_template_bindings": {
+      "status": "PASS",
+      "agents": 6,
+      "native_discovery_tested": false
+    },
+    "acceptance_case_manifest": {
+      "status": "PASS",
+      "cases": 59,
+      "executed": 0
+    },
+    "offline_python_tests": {
+      "status": "PASS",
+      "tests": 36,
+      "live_network_tested": false,
+      "local_git_fixture_tested": true
+    },
+    "typescript_syntax_only": {
+      "status": "PASS",
+      "files": 2,
+      "typescript": "5.8.3",
+      "scope": "syntax-only; not native typecheck or execution"
+    },
+    "native_bun_omp_tests": {
+      "status": "NOT_RUN",
+      "reason": "Bun and qualified OMP runtime/dependencies unavailable",
+      "starter_test_cases": 17
+    },
+    "archive_structure_and_crc": {
+      "status": "PASS",
+      "root": "omp-native-development",
+      "files": 33,
+      "unsafe_entries": 0,
+      "bytecode_artifacts": 0
+    }
+  },
+  "limitations": [
+    "No complete upstream raw-text mirror is bundled.",
+    "No live OMP/provider/Bizar workflow was tested.",
+    "Passing syntax and helper utilities is not runtime compatibility."
+  ]
+}

package/skills/omp-native-development/references/developer-handoff.md

@@ -0,0 +1,126 @@
+# Installation and developing-agent handoff
+
+## Contents
+1. Portable use
+2. Native OMP installation
+3. Native developing-agent autoload
+4. Verification commands
+5. Handoff prompt
+6. Do not confuse examples with a release
+
+## 1. Portable use
+
+Give the developing agent the entire `omp-native-development` directory, not just SKILL.md. The entrypoint links the detailed references, source manifest, examples and validation utilities. Other skill-capable coding agents can read the same entrypoint and relative files; their own skill installation location is host-specific.
+
+The skill is passive reference/procedure content. It is not the rebuilt Bizar extension and does not modify OMP on its own. A model can still make mistakes; the skill requires source checks and executable validation instead of declaring its knowledge infallible.
+
+## 2. Native OMP installation
+
+For one project, put the directory at:
+
+```text
+<repository>/.omp/skills/omp-native-development/SKILL.md
+```
+
+Keep `references/`, `scripts/`, `assets/`, and `agents/` inside that same skill directory. Do not add an extra nested grouping layer under `skills/`. If another copy already exists, inspect/backup it before replacing it; do not blindly merge old and new knowledge files.
+
+With native skill commands enabled, invoke:
+
+```text
+/skill:omp-native-development Audit the native agent and model-role integration before implementing the Bizar rewrite.
+```
+
+Alternatively the developing agent can read `skill://omp-native-development`. Native capability/source filters can suppress discovery, so verify the skill appears in the actual session. See the pinned `docs/skills.md` for profile/user roots and filtering rather than guessing a global path.
+
+The ZIP is not an executable plugin package. Do not use a made-up `omp install skill.zip` command.
+
+## 3. Native developing-agent autoload
+
+For an existing native developing-agent definition, merge this field into its own frontmatter:
+
+```yaml
+autoloadSkills:
+  - omp-native-development
+```
+
+Preserve its existing skills. This refers to the parent's discovered list; unknown names are ignored by native autoload. Prove a spawned child received the skill before relying on it.
+
+`assets/native-role-pack/agents/` contains six proposed Bizar agent templates. They are deliberately examples, not automatically activated definitions. Their aliases depend on optional native settings in `config.fragment.yml`. Merge those only during explicit Bizar setup, preserving existing mappings and overrides.
+
+## 4. Verification commands
+
+Run native settings inspection from the intended repository root/profile, NOT from inside this skill directory: cwd influences project settings.
+
+```sh
+# From the intended repository root; inspect/redact exports before sharing them.
+omp config list --json > /tmp/omp-effective-config.json
+python3 .omp/skills/omp-native-development/scripts/audit_role_config.py \
+  /tmp/omp-effective-config.json
+```
+
+For the proposed Bizar profile, add `--required-role bizar_build --required-role bizar_review` after the fragment has actually been merged. Supply `--known-agents PATH.json` only with a JSON array of names from real native discovery; `agent-names.example.json` is a fixture, not discovery evidence.
+
+Run the skill's offline utility tests:
+
+```sh
+python3 -m unittest discover \
+  -s .omp/skills/omp-native-development/scripts -p test_tools.py -v
+```
+
+Populate references from an already available checkout containing the pinned commit:
+
+```sh
+python3 .omp/skills/omp-native-development/scripts/omp_docs.py sync \
+  --repo /absolute/path/to/oh-my-pi \
+  --out /absolute/path/to/omp-reference
+```
+
+Omit `--repo` to fetch exact pinned files over HTTPS. This downloads reference data only, not packages or executables. Verify the resulting corpus with `verify --root PATH`.
+
+In a Bun development project with the version-qualified OMP dependency available, run the supplied native helper tests:
+
+```sh
+bun test .omp/skills/omp-native-development/assets/tests/native-role-contract.test.ts
+```
+
+These are source-coupled starter tests. Adjust only after checking the real target APIs; do not weaken assertions to hide a contract change. The broader acceptance matrix still needs implementation and execution.
+
+The optional `assets/native-role-probe.ts` extension can be loaded explicitly using the target's `-e` support. Its `/omp-role-probe` command reports current-session resolution of requested roles. It does not test agent-specific override precedence or live child execution; complete those separately.
+
+## 5. Handoff prompt
+
+```text
+Read omp-native-development/SKILL.md and follow its source-verification workflow.
+
+You are implementing the BizarHarness OMP-native rewrite. Treat the existing rewrite
+plan as the product design, and references/bizar-integration-contract.md as the
+additional mandatory agent/model-role contract. Neither document proves an API exists.
+
+First fingerprint the exact OMP target and inspect its native agent discovery,
+model-role resolver, settings precedence, extension APIs and task/eval lifecycle.
+Read references/agent-and-model-roles.md before changing routing. Retrieve exact
+primary docs/source through the pinned manifest or the actual target checkout.
+
+Preserve native custom roles, task.agentModelOverrides, model-role storage, tags,
+cycle order, effort, service tiers, prewalk, advisors, native fallback and user
+model selection. Keep requested role and actual effective model separately.
+Never add nonexistent public task parameters or a competing Bizar model router.
+
+Implement source/type tests and the relevant cases in assets/tests/acceptance-matrix.json
+before claiming the integration works. Start with one actual discovered specialist,
+prove its operator override and role routing in a child session, then exercise
+async settlement, capture-only isolation, cancellation/resume and verification.
+
+Do not modify global credentials/configuration, publish, push, deploy, or erase
+legacy state unless explicitly authorized for the implementation task. Distinguish
+DOCUMENTED, SOURCE-OBSERVED, TESTED, PROPOSED and UNKNOWN claims. Report exact tests
+actually run and do not label any unrun check as passing.
+```
+
+Change the first path to the actual location of the skill directory. The prompt must travel with the entire directory or with access to its references.
+
+## 6. Do not confuse examples with a release
+
+The skill is packaged and its offline utilities were tested. The rebuilt Bizar system has not been implemented by this skill-creation task. Native Bun tests, OMP installation/probe behavior, provider connectivity, and full end-to-end integration still require execution in the developer's environment.
+
+Sources: the pinned `docs/skills.md`, `docs/task-agent-discovery.md`, `docs/settings.md`, `docs/extensions.md`, and `docs/cli-reference.md`, linked in the official documentation index.