From 1e5454a06fed6dfdd477d06934932712c0b8694d Mon Sep 17 00:00:00 2001
From: Arjun Pramanik <capybearista@gmail.com>
Date: Fri, 25 Sep 2026 03:55:07 -0400
Subject: [PATCH 01/10] docs(auto-advisor): add DECISIONS.md

---
 docs/DECISIONS.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 docs/DECISIONS.md

diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
new file mode 100644
index 0000000..e606047
--- /dev/null
+++ b/docs/DECISIONS.md
@@ -0,0 +1,103 @@
+# Decisions
+
+This ledger records durable repository and product decisions. Small decisions live here directly; larger architectural decisions link to standalone ADRs under [`docs/decisions/`](./decisions/).
+
+## D-001 — Auto Advisor uses a dual-path architecture
+
+**Status:** Accepted  
+**Scope:** `@capybearista/opencode-auto-advisor`  
+**ADR:** [ADR-0001](./decisions/0001-dual-path-auto-advisor.md)
+
+Explicit Executor-triggered consultation and experimental automatic routing converge on one fresh, stateless Advisor service that receives the actual relevant Executor context.
+
+---
+
+## D-002 — Automatic routing is experimental in v1
+
+**Status:** Accepted  
+**Scope:** Auto Advisor automatic routing  
+**ADR:** [ADR-0002](./decisions/0002-experimental-automatic-routing.md)
+
+Automatic routing ships behind `off | observe | active` modes. `off` is the default; `observe` requires telemetry; `active` remains experimental.
+
+---
+
+## D-003 — Automatic advice uses system-role context in v1
+
+**Status:** Accepted  
+**Scope:** Auto Advisor advice delivery  
+**ADR:** [ADR-0003](./decisions/0003-automatic-advice-delivery.md)
+
+Explicit consultation returns a genuine tool result. Automatic consultation uses system-role context through `session.context`, with plugin-managed same-turn lifetime, until OpenCode exposes a suitable native durable instruction API to plugins.
+
+---
+
+## D-004 — The explicit Advisor tool accepts no arguments
+
+**Status:** Accepted  
+**Scope:** Auto Advisor public tool API
+
+The Executor invokes `advisor()` with an empty object input. The plugin owns context collection; the Executor does not pass a question or context summary.
+
+---
+
+## D-005 — An Advisor model must be configured
+
+**Status:** Accepted  
+**Scope:** Auto Advisor configuration
+
+The plugin requires an Advisor model configuration and does not silently fall back to the Executor model. The configured model need not be described as objectively stronger.
+
+---
+
+## D-006 — Use native V2 plugin options
+
+**Status:** Accepted  
+**Scope:** Auto Advisor configuration
+
+Configuration uses OpenCode V2 `plugins[].options`. No plugin-specific sidecar configuration file is introduced.
+
+---
+
+## D-007 — v1 Advisor consultations are fresh and tool-free
+
+**Status:** Accepted  
+**Scope:** Advisor behavior
+
+Every consultation is stateless, returns plain-text advice, and has no independent repository or network tools.
+
+---
+
+## D-008 — v1 Jev providers are TypeSafe AI and OpenCode Zen
+
+**Status:** Accepted  
+**Scope:** Experimental automatic routing
+
+v1 supports direct TypeSafe AI and OpenCode Zen only. Provider-specific Evaluation details remain isolated behind the Jev adapter.
+
+---
+
+## D-009 — Automatic consultation budget is configurable
+
+**Status:** Accepted  
+**Scope:** Automatic routing policy
+
+The initial default is one automatic consultation per user turn. Explicit `advisor()` calls do not consume the automatic budget.
+
+---
+
+## D-010 — Telemetry is opt-in except in observe mode
+
+**Status:** Accepted  
+**Scope:** Routing telemetry
+
+Telemetry is disabled by default. `observe` requires durable telemetry because its purpose is to collect routing evidence without changing Executor behavior.
+
+---
+
+## D-011 — Auto Advisor is V2-only and publishes on npm latest
+
+**Status:** Accepted  
+**Scope:** Package compatibility and release policy
+
+`@capybearista/opencode-auto-advisor` is an OpenCode V2-only package with no V1 line. Its npm distribution channel is `latest`, not `opencode` or `opencode2`. Release tooling must preserve host-version separation independently of dist-tag choice.

From 6a5876140c8d893175ea45d5bf1510e5472f9e24 Mon Sep 17 00:00:00 2001
From: Arjun Pramanik <capybearista@gmail.com>
Date: Fri, 25 Sep 2026 03:55:08 -0400
Subject: [PATCH 02/10] docs(auto-advisor): add 0001-dual-path-auto-advisor.md

---
 docs/decisions/0001-dual-path-auto-advisor.md | 83 +++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 docs/decisions/0001-dual-path-auto-advisor.md

diff --git a/docs/decisions/0001-dual-path-auto-advisor.md b/docs/decisions/0001-dual-path-auto-advisor.md
new file mode 100644
index 0000000..448551f
--- /dev/null
+++ b/docs/decisions/0001-dual-path-auto-advisor.md
@@ -0,0 +1,83 @@
+# ADR-0001: Use a dual-path Auto Advisor architecture
+
+## Status
+
+Accepted
+
+## Context
+
+A Claude Code-style Advisor is useful when an Executor recognizes that it needs independent judgment. That explicit pattern has a self-routing weakness: the same Executor that is uncertain or mistaken must recognize that consultation is warranted.
+
+A continuous parallel watchdog could independently intervene, but it adds persistent reviewer state, asynchronous races, duplicated investigation, stale advice, interruption semantics, and substantial orchestration complexity.
+
+The project needs independent routing without turning the Advisor into a continuously running second agent.
+
+## Decision
+
+Auto Advisor uses two consultation paths that converge on one shared Advisor service:
+
+```text
+                         ┌──────────────┐
+explicit advisor() ─────►│              │
+                         │ Advisor      │
+automatic route ────────►│ Service      │
+                         │              │
+                         └──────┬───────┘
+                                │
+                     fresh configured inference
+                                │
+                                ▼
+                            Executor
+```
+
+The explicit path is triggered by the Executor calling zero-argument `advisor()`.
+
+The automatic path evaluates the Executor state at safe primary model-dispatch boundaries and may consult the same Advisor before the next Executor inference proceeds.
+
+The Advisor service:
+
+- receives plugin-collected actual Executor context rather than an Executor-authored summary;
+- uses a configured model;
+- creates a fresh stateless inference for every consultation;
+- has no persistent private Advisor conversation;
+- has no independent tools in v1;
+- returns concise plain-text judgment.
+
+Automatic routing logic is kept outside the Advisor service.
+
+## Alternatives considered
+
+### Explicit-only Advisor
+
+This reproduces the useful Claude Advisor mechanism but leaves consultation entirely dependent on Executor self-awareness.
+
+Rejected as the complete product architecture because independent routing is a core project goal.
+
+### Persistent autonomous watchdog
+
+A background reviewer could observe the Executor continuously and push unsolicited guidance.
+
+Rejected because it creates substantially more lifecycle, synchronization, stale-context, cost, and interruption complexity than required. The project intentionally routes between Executor inferences instead of supervising token streams continuously.
+
+### Separate explicit and automatic Advisor implementations
+
+Separate services could tailor behavior to each trigger.
+
+Rejected because both paths are meant to request the same kind of independent judgment over the same evidence. Duplicating Advisor personalities or context logic would create drift.
+
+## Consequences
+
+- Explicit and automatic consultation share context capture and Advisor behavior.
+- Automatic routing can evolve or be replaced without changing the Advisor.
+- The design avoids mid-generation interruption.
+- The Executor can still override Advisor guidance when evidence warrants it.
+- Fresh consultations reduce anchoring from a persistent reviewer history.
+- Context fidelity becomes a critical validation requirement.
+
+## Supersedes
+
+None.
+
+## Superseded by
+
+None.

From a550ce47cbdb337fda2fe1222b859ab05af1e97f Mon Sep 17 00:00:00 2001
From: Arjun Pramanik <capybearista@gmail.com>
Date: Fri, 25 Sep 2026 03:55:10 -0400
Subject: [PATCH 03/10] docs(auto-advisor): add
 0002-experimental-automatic-routing.md

---
 .../0002-experimental-automatic-routing.md    | 71 +++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 docs/decisions/0002-experimental-automatic-routing.md

diff --git a/docs/decisions/0002-experimental-automatic-routing.md b/docs/decisions/0002-experimental-automatic-routing.md
new file mode 100644
index 0000000..ea48b76
--- /dev/null
+++ b/docs/decisions/0002-experimental-automatic-routing.md
@@ -0,0 +1,71 @@
+# ADR-0002: Treat automatic routing as experimental in v1
+
+## Status
+
+Accepted
+
+## Context
+
+OpenCode V2 provides a synchronous `session.context` hook immediately before provider dispatch, which is a suitable safe boundary for automatic routing.
+
+The initial routing implementation uses OpenCode's Evaluation/Jev capability. That API is published under an experimental surface whose contract is explicitly expected to evolve. Independently of API stability, the project does not yet have empirical evidence that Jev's routing precision justifies the latency and cost of evaluating materially new Executor dispatches.
+
+The plugin needs the automatic-routing architecture in v1 without presenting an unvalidated router as stable/default behavior.
+
+## Decision
+
+v1 includes automatic routing behind three modes:
+
+- `off` — no automatic routing; explicit `advisor()` remains available.
+- `observe` — Jev evaluates routing opportunities and records the assessment and hypothetical deterministic policy result, but does not invoke the Advisor or alter Executor context.
+- `active` — Jev evaluates routing opportunities and deterministic policy may trigger an automatic Advisor consultation.
+
+`off` is the default.
+
+Telemetry is required in `observe`.
+
+Automatic routing remains documented as experimental in v1.
+
+The stable domain depends on an `AdvisorRouter` abstraction and a normalized router assessment. OpenCode Evaluation types, System One types, confidence metadata, and provider-specific structures remain inside the Jev adapter.
+
+v1 Jev provider scope is limited to:
+
+- direct TypeSafe AI;
+- OpenCode Zen.
+
+Automatic consultation budgeting is configurable, initially defaulting to one automatic consultation per user turn.
+
+## Alternatives considered
+
+### Enable automatic routing by default
+
+Rejected because both the Evaluation API contract and routing quality are insufficiently validated.
+
+### Ship explicit Advisor first and add routing in a later product version
+
+Rejected because independent routing is a core product requirement and the surrounding architecture can be established safely now. The implementation may sequence explicit foundations before routing, but v1's product architecture contains both paths.
+
+### Build deterministic pre-routing heuristics instead of Jev
+
+Rejected as the primary approach because it would duplicate the judgment the routing model is intended to provide and introduce premature policy complexity. Deterministic policy still governs whether a model estimate causes a consultation.
+
+### Couple stable interfaces directly to OpenCode Evaluation types
+
+Rejected because the Evaluation contract is experimental and likely to change.
+
+## Consequences
+
+- v1 can collect routing evidence without changing Executor behavior.
+- Jev can be replaced later without rewriting the Advisor service.
+- Provider/API churn is concentrated in one adapter boundary.
+- `observe` introduces a clear calibration path before stronger stability claims.
+- Automatic routing still incurs extra inference latency/cost in `observe` and `active`.
+- The supported OpenCode/Evaluation range must be explicitly tested and revalidated.
+
+## Supersedes
+
+None.
+
+## Superseded by
+
+None.

From eaaf91ed660043ac0ff4df5a4a6f8fa98a6fb856 Mon Sep 17 00:00:00 2001
From: Arjun Pramanik <capybearista@gmail.com>
Date: Fri, 25 Sep 2026 03:55:12 -0400
Subject: [PATCH 04/10] docs(auto-advisor): add
 0003-automatic-advice-delivery.md

---
 .../0003-automatic-advice-delivery.md         | 77 +++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 docs/decisions/0003-automatic-advice-delivery.md

diff --git a/docs/decisions/0003-automatic-advice-delivery.md b/docs/decisions/0003-automatic-advice-delivery.md
new file mode 100644
index 0000000..897235e
--- /dev/null
+++ b/docs/decisions/0003-automatic-advice-delivery.md
@@ -0,0 +1,77 @@
+# ADR-0003: Deliver automatic advice as plugin-managed system context in v1
+
+## Status
+
+Accepted
+
+## Context
+
+Explicit `advisor()` consultation naturally produces a genuine tool call and tool result that persist in normal conversation history.
+
+Automatic routing is different: the Executor did not call `advisor()`. Fabricating a tool invocation would make the transcript claim an action the Executor never took.
+
+OpenCode V2 exposes `session.synthetic` to plugins, but synthetic messages are lowered to user-role model messages. Advisor guidance should not impersonate the user.
+
+OpenCode V2 also has durable session instruction-entry machinery that is semantically appropriate for privileged chronological updates, but the current Promise and Effect plugin contexts do not expose that API. Directly bypassing the supported plugin surface would couple v1 to an intentionally unexposed API.
+
+The public `session.context` hook can mutate the outgoing request with system-role context, but those mutations are request-local rather than native durable transcript entries.
+
+## Decision
+
+Explicit consultation uses the real tool-call/tool-result path.
+
+Automatic consultation in v1:
+
+1. generates advice before the waiting primary Executor request proceeds;
+2. stores the applicable automatic review in plugin-owned session/turn state;
+3. injects that advice as system-role context through `session.context`;
+4. reinjects it on relevant continuations during the same user turn;
+5. lets a newer automatic review supersede the prior active review;
+6. expires the active review on normal new user input.
+
+The plugin must not:
+
+- fabricate an `advisor()` call;
+- deliver Advisor advice with `session.synthetic`;
+- depend on the currently unexposed instruction-entry API.
+
+The design should keep advice delivery replaceable so that a future OpenCode version can use native durable instruction entries if they become part of the supported plugin API.
+
+## Alternatives considered
+
+### Fabricate an Advisor tool call/result pair
+
+Rejected because it falsely attributes the consultation decision to the Executor.
+
+### Use session.synthetic
+
+Rejected because OpenCode lowers synthetic messages to user-role context, which gives Advisor guidance the wrong semantic authority.
+
+### Call the hidden/experimental instruction-entry endpoint directly
+
+Rejected for v1 because normal plugins do not receive that capability through the supported Promise or Effect plugin context.
+
+### Inject advice only once
+
+Rejected because tool continuations cause later model requests in the same user turn; the Executor must continue to see the applicable review.
+
+### Reinject all historical automatic advice forever
+
+Rejected because it creates unbounded context growth and increases the risk of stale guidance.
+
+## Consequences
+
+- Automatic advice has appropriate system authority without falsifying transcript history.
+- The plugin owns the lifetime of active automatic advice.
+- Automatic advice is not natively persisted as an ordinary conversation message in v1.
+- Same-turn state/expiry behavior requires explicit tests.
+- Compaction does not require replaying all historical reviews; only the currently applicable review is reinjected.
+- A future native delivery mechanism can replace the v1 delivery implementation without changing Jev or AdvisorService.
+
+## Supersedes
+
+None.
+
+## Superseded by
+
+None.

From a358aeb1636ba294b3818a05130e1749c6761999 Mon Sep 17 00:00:00 2001
From: Arjun Pramanik <capybearista@gmail.com>
Date: Fri, 25 Sep 2026 03:56:35 -0400
Subject: [PATCH 05/10] docs(auto-advisor): add claude-code-advisor.md

---
 docs/research/claude-code-advisor.md | 126 +++++++++++++++++++++++++++
 1 file changed, 126 insertions(+)
 create mode 100644 docs/research/claude-code-advisor.md

diff --git a/docs/research/claude-code-advisor.md b/docs/research/claude-code-advisor.md
new file mode 100644
index 0000000..e48a597
--- /dev/null
+++ b/docs/research/claude-code-advisor.md
@@ -0,0 +1,126 @@
+# Claude Code Advisor research
+
+**Status:** current  
+**Last verified:** 2026-09-25  
+**Scope:** Claude Code / Claude Platform Advisor behavior used as the product reference for `opencode-auto-advisor`.
+
+## Question
+
+What behavior should the OpenCode Auto Advisor reproduce from Claude's Advisor, and which details are official versus community-recovered?
+
+## Sources
+
+### Authoritative
+
+- Anthropic Claude Platform Advisor tool documentation: https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool
+
+### Community reverse-engineering
+
+- Piebald-AI Claude Code system-prompt extraction repository: https://github.com/Piebald-AI/claude-code-system-prompts
+- Extracted Advisor tool instructions: https://github.com/Piebald-AI/claude-code-system-prompts/blob/main/system-prompts/system-prompt-advisor-tool-instructions.md
+- asgeirtj system prompt archive, Advisor material: https://github.com/asgeirtj/system_prompts_leaks/tree/main/Anthropic/claude-code/prompts
+- Community-recovered Advisor prompt file: https://github.com/asgeirtj/system_prompts_leaks/blob/main/Anthropic/claude-code/prompts/advisor-tool.md
+
+Community prompt captures are useful corroborating evidence but are not equivalent to Anthropic-published documentation. Exact private wording should therefore not be treated as an authoritative contract.
+
+## Findings
+
+### The explicit tool has no arguments
+
+Anthropic's documented Advisor server-tool call uses an empty input object. The Executor does not pass a question, context summary, or focus field.
+
+The consultation signal is the act of calling the tool; relevant uncertainty or intent already exists in the surrounding transcript.
+
+This supports an OpenCode surface of:
+
+```text
+advisor()
+```
+
+rather than an API such as `advisor({ question, context })`.
+
+### The Advisor receives the Executor's actual transcript/context
+
+Anthropic documents the Advisor as seeing the working conversation, including the system prompt, tool definitions, prior tool activity, and text already produced in the current turn.
+
+This is a key property, not an incidental implementation choice: the Executor is not asked to decide which evidence to summarize for the reviewer.
+
+The Auto Advisor should therefore make context collection a plugin responsibility.
+
+### Consultation is fresh and independent
+
+The Advisor is a fresh consultation rather than a long-running private reviewer conversation.
+
+The product implication is:
+
+- no persistent private Advisor session;
+- no accumulated private Advisor memory between calls;
+- every call evaluates the current evidence afresh.
+
+Earlier Advisor guidance may still appear in the parent transcript because the parent conversation persists.
+
+### The Advisor does not need its own tools
+
+Anthropic's documented Advisor performs judgment over the supplied transcript rather than independently exploring the repository.
+
+That differentiates it from a specialist subagent such as an Oracle that may investigate files/tools over multiple turns.
+
+v1 Auto Advisor therefore does not give the Advisor tools.
+
+### Advice returns as a consultation result
+
+For explicit consultation, Claude returns an Advisor tool result and the Executor continues with that result in context.
+
+The result is advice text rather than a required structured JSON decision object.
+
+This supports plain-text Advisor output in Auto Advisor.
+
+### Claude encourages consultation at judgment boundaries
+
+Official documentation and extracted Executor-facing instructions consistently encourage consultation around situations such as:
+
+- before committing to consequential approaches;
+- when stuck;
+- when changing direction;
+- before declaring substantial work complete.
+
+This should inform the Executor-facing tool description, but the OpenCode plugin does not need to reproduce Anthropic's exact private wording.
+
+### Community captures suggest a broad situational-review prompt
+
+The recovered Advisor prompt frames the reviewer as deciding what kind of situation the Executor is in, including patterns equivalent to:
+
+- starting out;
+- stuck;
+- reviewing work;
+- choosing between candidates.
+
+It emphasizes diagnosing the actual trajectory, respecting newer evidence over stale prior advice, avoiding repetition of already-tried approaches, and identifying whether concerns are actually blocking.
+
+This is consistent with the public product behavior and supports a broad second-opinion prompt rather than a narrow code-review persona.
+
+Because the exact Advisor system prompt is not officially published, Auto Advisor should preserve the behavioral intent rather than copy a purported private prompt verbatim.
+
+## Project conclusions
+
+The Auto Advisor explicit path should preserve these invariants:
+
+1. zero-argument `advisor()`;
+2. plugin-owned actual-context collection;
+3. fresh stateless Advisor inference;
+4. no Advisor tools in v1;
+5. plain-text independent guidance;
+6. genuine tool-result delivery for explicit consultation.
+
+Automatic routing is an OpenCode-specific extension beyond Claude's Executor-self-routed mechanism. It should invoke the same Advisor behavior rather than create a separate automatic-review persona.
+
+## Limitations
+
+- Anthropic can change Claude Code and the server-side Advisor implementation independently of public client releases.
+- Community-extracted prompts may be incomplete, version-specific, or obtained through methods that do not establish an official contract.
+- Exact prompt wording is intentionally not treated as a stable dependency.
+
+## Related decisions and plan
+
+- [ADR-0001](../decisions/0001-dual-path-auto-advisor.md)
+- [Auto Advisor plan](../plans/opencode-auto-advisor.md)

From aa711511acafe2f17ff50c4d97ed945fb560a4cd Mon Sep 17 00:00:00 2001
From: Arjun Pramanik <capybearista@gmail.com>
Date: Fri, 25 Sep 2026 03:56:37 -0400
Subject: [PATCH 06/10] docs(auto-advisor): add opencode-v2-advisor-runtime.md

---
 docs/research/opencode-v2-advisor-runtime.md | 160 +++++++++++++++++++
 1 file changed, 160 insertions(+)
 create mode 100644 docs/research/opencode-v2-advisor-runtime.md

diff --git a/docs/research/opencode-v2-advisor-runtime.md b/docs/research/opencode-v2-advisor-runtime.md
new file mode 100644
index 0000000..4b746e5
--- /dev/null
+++ b/docs/research/opencode-v2-advisor-runtime.md
@@ -0,0 +1,160 @@
+# OpenCode V2 Advisor runtime research
+
+**Status:** current  
+**Last verified:** 2026-09-25  
+**Scope:** OpenCode V2 plugin/runtime capabilities needed for explicit and automatic Advisor consultation.
+
+## Question
+
+Can a V2 plugin capture the necessary Executor context, invoke a fresh Advisor model, gate automatic consultation at a safe boundary, and deliver advice with correct model-role semantics?
+
+## Primary sources
+
+- OpenCode V2 repository, `v2` branch: https://github.com/anomalyco/opencode/tree/v2
+- Promise session API: https://github.com/anomalyco/opencode/blob/v2/packages/plugin/src/promise/session.ts
+- Promise plugin adapter: https://github.com/anomalyco/opencode/blob/v2/packages/plugin/src/promise/adapter.ts
+- Session request/context construction: https://github.com/anomalyco/opencode/blob/v2/packages/core/src/session/context.ts
+- Model-message lowering: https://github.com/anomalyco/opencode/blob/v2/packages/core/src/session/runner/to-llm-message.ts
+- Session message schema: https://github.com/anomalyco/opencode/blob/v2/packages/schema/src/session-message.ts
+- Session protocol group: https://github.com/anomalyco/opencode/blob/v2/packages/protocol/src/groups/session.ts
+- Session history/compaction behavior: https://github.com/anomalyco/opencode/blob/v2/packages/core/src/session/history.ts
+
+## Findings
+
+### `session.context` is the correct synchronous automatic-routing boundary
+
+The Promise V2 session API exposes a mutable context hook containing the outgoing model-facing state: session/model/agent information, system parts, messages, options, and tool definitions.
+
+The hook runs as part of request preparation before provider dispatch.
+
+Therefore automatic routing can synchronously gate the next Executor inference:
+
+```text
+prepare primary request
+        ↓
+session.context
+        ↓
+route / maybe consult
+        ↓
+provider dispatch
+```
+
+No token-stream watchdog or normal `session.interrupt()` flow is required.
+
+### Automatic routing should occur between Executor inferences
+
+A tool result naturally causes OpenCode to prepare another primary model request so the Executor can continue.
+
+That continuation boundary is where the plugin evaluates the updated state. The design does not attempt to stop an Executor halfway through an active model generation.
+
+### Promise tools have access to session/message identity
+
+Tool execution context includes the session and assistant-message identity needed to associate explicit consultation with the parent turn.
+
+Core session processing projects tool-call state before tool execution. This provides a practical route to recover the current assistant state around an explicit `advisor()` call.
+
+One narrow runtime question remains implementation validation: whether every provider closes/persists meaningful text or reasoning immediately adjacent to a tool call before the local tool starts. The product plan therefore requires a focused runtime test before adding streaming-delta capture.
+
+### `generate.text()` is a fresh selected-model primitive, but text-only
+
+The V2 plugin generation surface can target a configured model without creating a normal Executor Session step.
+
+It accepts a text prompt rather than arbitrary parent `system/messages` arrays.
+
+Therefore Auto Advisor cannot currently replay the parent request as provider-native structured messages while independently selecting the Advisor model through this public primitive.
+
+The v1 design serializes actual parent evidence into a canonical textual envelope. This preserves the important invariant that the Executor does not author the evidence summary.
+
+### Auxiliary Advisor generation does not require Session recursion
+
+The planned Advisor call uses the lower-level generation domain rather than `session.generate()`.
+
+That avoids creating another agent-loop Session dispatch from inside the primary `session.context` hook and therefore avoids the obvious routing-hook recursion path.
+
+Runtime validation should still assert that auxiliary Advisor/Evaluation calls do not trigger automatic routing unexpectedly.
+
+### `session.synthetic` is durable but has the wrong model authority
+
+V2 exposes `session.synthetic` to plugins.
+
+However, `to-llm-message.ts` lowers a synthetic session message to a model message with the `user` role.
+
+That makes it inappropriate for automatic Advisor guidance: the plugin must not make independent review text appear to be user-authored instruction.
+
+### Native system/session instruction updates exist
+
+V2 has session instruction-entry endpoints:
+
+- list;
+- put;
+- remove.
+
+The protocol describes them as durable instruction entries whose changes are announced at the next step boundary.
+
+This is semantically close to the desired long-term automatic-advice behavior and underlies chronological instruction-update behavior visible in the TUI.
+
+### Normal plugins cannot currently access instruction entries through `ctx.session`
+
+The full client/protocol contains the instruction-entry API, but both Promise and Effect plugin `SessionDomain` types deliberately expose a narrower subset.
+
+The Promise adapter also constructs `ctx.session` explicitly from that reduced set and omits instruction entries, confirming this is a runtime capability restriction rather than only missing TypeScript declarations.
+
+Therefore v1 should not depend on native instruction entries or bypass the supported plugin API to reach them.
+
+### `session.context` injection is request-local
+
+Mutating the outgoing context provides correct system-role authority for the current provider request, but it is not itself a new durable session transcript entry.
+
+v1 therefore needs plugin-owned active automatic-advice state and same-turn reinjection across relevant continuations.
+
+The active review expires on normal new user input or is superseded by a newer review.
+
+### Future native instruction persistence would complement, not necessarily replace, current-request injection
+
+Instruction-entry updates are announced at a later step boundary. An automatic review generated while the current `session.context` hook is already preparing a request may still need direct context injection for that waiting request.
+
+A future native implementation may combine:
+
+- immediate system injection for the current request;
+- durable instruction persistence for subsequent requests.
+
+## Project conclusions
+
+The supported v1 delivery architecture is:
+
+```text
+Explicit:
+Executor → advisor() → fresh Advisor → genuine tool result
+
+Automatic:
+primary session.context
+        → router
+        → optional fresh Advisor
+        → plugin-owned active review
+        → system-role request injection
+```
+
+Do not use:
+
+- `session.synthetic` for Advisor guidance;
+- fabricated tool calls;
+- currently unexposed session instruction-entry APIs.
+
+## Required runtime validations
+
+- explicit same-turn text/reasoning context fidelity;
+- real package-root V2 plugin loading;
+- no routing recursion from auxiliary inference;
+- correct same-turn automatic-advice lifetime;
+- fail-open automatic-routing behavior.
+
+## Limitations
+
+- V2 is moving quickly; source behavior must be revalidated against the exact supported release range selected during implementation planning.
+- The public plugin API may expose durable instruction entries later, which should trigger reconsideration of ADR-0003 without changing the higher-level Advisor architecture.
+
+## Related decisions and plan
+
+- [ADR-0001](../decisions/0001-dual-path-auto-advisor.md)
+- [ADR-0003](../decisions/0003-automatic-advice-delivery.md)
+- [Auto Advisor plan](../plans/opencode-auto-advisor.md)

From 3e02ddd0b9f185ef07743c6139f95f4013c3c4d3 Mon Sep 17 00:00:00 2001
From: Arjun Pramanik <capybearista@gmail.com>
Date: Fri, 25 Sep 2026 03:56:39 -0400
Subject: [PATCH 07/10] docs(auto-advisor): add opencode-v2-jev-evaluation.md

---
 docs/research/opencode-v2-jev-evaluation.md | 146 ++++++++++++++++++++
 1 file changed, 146 insertions(+)
 create mode 100644 docs/research/opencode-v2-jev-evaluation.md

diff --git a/docs/research/opencode-v2-jev-evaluation.md b/docs/research/opencode-v2-jev-evaluation.md
new file mode 100644
index 0000000..03650bc
--- /dev/null
+++ b/docs/research/opencode-v2-jev-evaluation.md
@@ -0,0 +1,146 @@
+# OpenCode V2 Jev / Evaluation research
+
+**Status:** current; revalidate before implementation  
+**Last verified:** 2026-09-25  
+**Scope:** OpenCode V2 experimental Evaluation/Jev capability as the initial automatic-consultation router.
+
+## Question
+
+Is OpenCode's Evaluation/Jev capability suitable as the first `AdvisorRouter`, and what stability/provider constraints should v1 adopt?
+
+## Sources
+
+### Upstream
+
+- OpenCode V2 repository: https://github.com/anomalyco/opencode/tree/v2
+- `@opencode/ai` README: https://github.com/anomalyco/opencode/blob/v2/packages/ai/README.md
+- Experimental Evaluation implementation: https://github.com/anomalyco/opencode/blob/v2/packages/ai/src/experimental/evaluation.ts
+- `@opencode/ai` package manifest: https://github.com/anomalyco/opencode/blob/v2/packages/ai/package.json
+- `@opencode/plugin` package manifest: https://github.com/anomalyco/opencode/blob/v2/packages/plugin/package.json
+
+### Related project research
+
+These documents in `capyBearista/opencode-config` were reviewed as additional context:
+
+- https://github.com/capyBearista/opencode-config/blob/main/docs/V2-2026.09.24-configuration-research.md
+- https://github.com/capyBearista/opencode-config/blob/main/docs/V2-2026.09.24-release-notes-and-capabilities.md
+
+## Findings
+
+### Evaluation is intentionally experimental
+
+The Evaluation contract is isolated under `@opencode/ai/experimental`, and upstream describes that isolation as intentional while the contract evolves.
+
+This is the primary stability reason automatic Jev routing should not be presented as stable/default in v1.
+
+### Evaluation is a natural fit for a routing adapter
+
+The project needs a small normalized decision surface such as:
+
+- consultation probability;
+- consequence;
+- reason/category.
+
+Evaluation-style boolean/score/choice judgments map naturally into that shape.
+
+The stable plugin architecture should not expose OpenCode Evaluation types directly. The adapter translates experimental/provider-specific output into the project's own `RouterAssessment`.
+
+### API stability is not the only unknown
+
+Even if the Evaluation API stopped changing, the project still needs evidence that Jev's routing quality justifies an extra inference before materially new Executor dispatches.
+
+That product-quality uncertainty motivates `observe` mode.
+
+### Observe mode enables counterfactual routing evaluation
+
+In `observe`:
+
+1. a routing opportunity is identified;
+2. Jev evaluates it;
+3. deterministic policy computes what it would have done;
+4. telemetry records the result;
+5. the Advisor is not invoked;
+6. Executor context is not changed.
+
+This produces evidence about routing behavior without changing task trajectories.
+
+### Provider scope should stay narrow in v1
+
+v1 supports:
+
+- direct TypeSafe AI;
+- OpenCode Zen.
+
+OpenRouter and other possible routes are excluded from v1 to keep the experimental authentication/provider surface bounded.
+
+### Provider-specific behavior belongs inside the adapter
+
+The stable routing layer should not depend on:
+
+- raw Evaluation result types;
+- System One model types;
+- raw provider confidence metadata;
+- provider-specific option structures;
+- Evaluation API naming that may change.
+
+Only normalized project-domain assessment leaves the adapter.
+
+### Compatibility needs an explicitly tested OpenCode range
+
+Because Evaluation and the V2 plugin system are evolving together, v1 should declare a tested compatible OpenCode V2 range rather than imply arbitrary V2 support.
+
+The exact range and dependency syntax are implementation-plan decisions that must be based on the versions actually exercised.
+
+## Project conclusions
+
+Automatic routing v1 uses the following posture:
+
+```text
+routing.mode = off | observe | active
+
+default = off
+
+off:
+  no Jev evaluation
+
+observe:
+  Jev evaluation
+  deterministic hypothetical policy
+  required durable telemetry
+  no Advisor call
+  no Executor-context mutation
+
+active:
+  Jev evaluation
+  deterministic policy
+  optional automatic Advisor consultation
+```
+
+Automatic routing remains experimental.
+
+The architecture should make future replacement with Laya or another classifier possible without changing AdvisorService.
+
+## Telemetry implications
+
+At minimum, observation data should retain enough normalized information to reconstruct:
+
+- opportunity/state fingerprint;
+- normalized routing state;
+- provider/router identity;
+- assessment;
+- deterministic policy result;
+- consultation ID if active;
+- later validation/failure signals where reasonably attributable.
+
+Full conversations and credentials should not be copied to telemetry by default.
+
+## Limitations
+
+- Evaluation API names, shapes, provider options, and metadata may change.
+- Routing-quality conclusions cannot be drawn from API design alone.
+- This document must be revalidated against the exact OpenCode version selected by the implementation orchestrator before Jev code is written.
+
+## Related decisions and plan
+
+- [ADR-0002](../decisions/0002-experimental-automatic-routing.md)
+- [Auto Advisor plan](../plans/opencode-auto-advisor.md)

From 7dc1091d7b0d1e39970fc20e719bc2af4704cc11 Mon Sep 17 00:00:00 2001
From: Arjun Pramanik <capybearista@gmail.com>
Date: Fri, 25 Sep 2026 03:57:34 -0400
Subject: [PATCH 08/10] docs(auto-advisor): add governing plan

---
 docs/plans/opencode-auto-advisor.md | 601 ++++++++++++++++++++++++++++
 1 file changed, 601 insertions(+)
 create mode 100644 docs/plans/opencode-auto-advisor.md

diff --git a/docs/plans/opencode-auto-advisor.md b/docs/plans/opencode-auto-advisor.md
new file mode 100644
index 0000000..4287af6
--- /dev/null
+++ b/docs/plans/opencode-auto-advisor.md
@@ -0,0 +1,601 @@
+# OpenCode Auto Advisor
+
+**Status:** Draft  
+**Tracking issue:** [#47](https://github.com/capyBearista/opencode-plugins/issues/47)  
+**Package:** `@capybearista/opencode-auto-advisor`
+
+## Goal
+
+Create an OpenCode V2 server plugin that provides a Claude Code-style independent Advisor through two consultation paths:
+
+1. **Explicit consultation** — the Executor deliberately calls zero-argument `advisor()`.
+2. **Automatic consultation** — an experimental routing layer evaluates the Executor state at safe primary model-dispatch boundaries and may consult the same Advisor before the next Executor inference proceeds.
+
+Both paths use the same fresh, stateless Advisor behavior and the same evidence model.
+
+## Problem
+
+Explicit Advisor tools are valuable but inherit a self-routing weakness: the Executor must recognize that consultation is warranted.
+
+A continuous autonomous watchdog could remove that dependency, but it introduces persistent reviewer state, asynchronous races, duplicated investigation, stale advice, interruption semantics, and substantially more lifecycle complexity than required.
+
+Auto Advisor therefore combines Executor self-awareness with independent between-inference routing.
+
+## Requirements
+
+### Explicit Advisor
+
+Expose:
+
+```text
+advisor()
+```
+
+The tool accepts no arguments.
+
+Calling it must:
+
+- pause normal Executor continuation like an ordinary tool call;
+- obtain the actual relevant Executor context through the consultation point;
+- invoke a freshly configured Advisor model;
+- return concise plain-text advice as the genuine tool result;
+- allow the Executor to continue with that result in normal conversation history.
+
+The Executor must not be required to summarize its context or formulate a question for the Advisor.
+
+### Advisor context
+
+The plugin owns evidence collection.
+
+Advisor context must be derived from the actual Executor working context rather than an Executor-authored summary.
+
+The canonical representation should preserve, where available:
+
+- system instructions;
+- user and assistant messages;
+- textual reasoning;
+- tool calls;
+- tool results;
+- the current assistant state through the consultation point;
+- useful file/media metadata when direct multimodal replay is unavailable.
+
+Because the current public fresh-generation primitive accepts a text prompt rather than arbitrary parent `system/messages` arrays, the context must be represented through a faithful canonical textual envelope.
+
+The plugin must not claim that the Advisor directly consumed media content when only metadata or textual representations were supplied.
+
+### Advisor behavior
+
+Every consultation is fresh and stateless.
+
+The Advisor:
+
+- uses the configured model;
+- has no persistent private conversation;
+- receives no independent repository or network tools in v1;
+- performs broad independent situational judgment rather than acting as a narrow code-review specialist;
+- returns plain text rather than a required structured schema.
+
+A user must configure an Advisor model. The plugin does not characterize the configured model as objectively stronger.
+
+### Shared Advisor service
+
+Explicit and automatic consultation converge on one conceptual Advisor service:
+
+```text
+                         ┌──────────────┐
+explicit advisor() ─────►│              │
+                         │ Advisor      │
+automatic route ────────►│ Service      │
+                         │              │
+                         └──────┬───────┘
+                                │
+                     fresh configured inference
+                                │
+                                ▼
+                            Executor
+```
+
+The Advisor service must not depend on Jev or automatic-routing policy.
+
+### Automatic routing boundary
+
+Automatic routing does not interrupt an Executor in the middle of model generation.
+
+It operates synchronously at a safe primary model-dispatch boundary:
+
+```text
+OpenCode prepares next Executor request
+                ↓
+          session.context
+                ↓
+        routing opportunity
+                ↓
+              Jev
+                ↓
+      deterministic policy
+          /           \
+        skip          consult
+                        ↓
+                    Advisor
+                        ↓
+              inject advice
+                        ↓
+             Executor request
+```
+
+The hook itself provides the pause. `session.interrupt()` is not the normal routing mechanism.
+
+### Automatic-routing modes
+
+Configuration exposes:
+
+```text
+off
+observe
+active
+```
+
+#### `off`
+
+- no Jev evaluation occurs;
+- explicit `advisor()` remains available.
+
+This is the default.
+
+#### `observe`
+
+- routing opportunities are evaluated;
+- Jev assessments and hypothetical deterministic policy decisions are recorded;
+- the Advisor is not invoked automatically;
+- Executor context is not changed.
+
+Durable telemetry is required in this mode.
+
+#### `active`
+
+- routing opportunities are evaluated;
+- deterministic policy may trigger an Advisor consultation;
+- resulting advice is supplied before the waiting Executor request proceeds.
+
+Automatic routing remains experimental in v1.
+
+### Routing opportunities
+
+The initial design evaluates materially new primary Executor dispatch states rather than introducing an elaborate deterministic pre-router heuristic system.
+
+Duplicate/equivalent routing states are suppressed using an appropriate state/context fingerprint.
+
+The implementation planner may refine the exact definition of “materially new,” but must avoid repeatedly evaluating unchanged state.
+
+### Router boundary
+
+The stable plugin domain depends on an Advisor-router abstraction rather than OpenCode's experimental Evaluation types.
+
+Conceptually:
+
+```ts
+interface AdvisorRouter {
+  evaluate(
+    state: AdvisorRoutingState,
+    signal?: AbortSignal
+  ): Promise<RouterAssessment>
+}
+
+interface RouterAssessment {
+  consultationProbability: number
+  consequence: number
+  reason: ConsultationReason | "none"
+  metadata?: Record<string, unknown>
+}
+```
+
+Exact internal naming may be refined during implementation planning.
+
+OpenCode Evaluation types, System One types, raw confidence structures, provider metadata, and other Jev-specific details remain inside the Jev adapter.
+
+### Jev support
+
+v1 supports Jev through:
+
+- direct TypeSafe AI;
+- OpenCode Zen.
+
+OpenRouter or other Jev routes are outside v1.
+
+Jev integration is experimental because the OpenCode Evaluation API is explicitly evolving.
+
+The implementation must declare and test a specific compatible OpenCode V2 range rather than assuming arbitrary V2 compatibility.
+
+### Routing policy
+
+Router estimates and application decisions are separate concerns.
+
+The routing model estimates whether consultation appears warranted. A deterministic policy decides whether the plugin actually consults.
+
+Thresholds are configurable. Initial exact threshold values are implementation/calibration details.
+
+### Automatic consultation budget
+
+Automatic consultation limits are configurable.
+
+The initial default is:
+
+```text
+1 automatic consultation per user turn
+```
+
+Explicit consultations do not consume this automatic budget.
+
+No elaborate cooldown/backlog machinery is required unless evidence later demonstrates a need.
+
+### Explicit advice delivery
+
+Explicit consultation uses the genuine OpenCode tool-call/tool-result flow.
+
+Its result persists according to normal session-history behavior.
+
+### Automatic advice delivery
+
+Automatic advice must not fabricate an Executor `advisor()` call.
+
+It must not use `session.synthetic`, because V2 lowers synthetic input to the model as user-role content.
+
+For v1:
+
+1. automatic advice is injected as system-role context through `session.context`;
+2. the applicable review is retained in plugin-owned state;
+3. the same review is reinjected on relevant continuations during the same user turn;
+4. a newer review supersedes an older active review;
+5. normal new user input expires the prior active review.
+
+OpenCode has native durable session instruction-entry machinery with more appropriate long-term semantics, but that API is currently not exposed through the supported Promise or Effect plugin context.
+
+v1 must not bypass the supported plugin API merely to gain native instruction persistence.
+
+The design should allow a later delivery implementation to use native durable instruction entries if OpenCode exposes them to plugins.
+
+### Failure behavior
+
+Automatic-routing infrastructure fails open.
+
+Failures in opportunity evaluation, Jev/provider access, policy plumbing, automatic Advisor invocation, or automatic advice delivery must not unnecessarily prevent Executor continuation.
+
+Failures must remain observable through appropriate diagnostics/telemetry.
+
+An explicit `advisor()` failure is different: because the Executor deliberately requested consultation, the tool result/error must make the failure visible to it.
+
+### Telemetry
+
+Telemetry is disabled by default.
+
+`observe` requires durable telemetry because observation without retained evaluation data defeats the mode's purpose.
+
+Telemetry should retain enough normalized information to evaluate routing quality and compare future routers without copying the full conversation by default.
+
+Relevant data includes conceptually:
+
+- routing opportunity;
+- normalized routing state;
+- state/context fingerprint;
+- router/provider;
+- router assessment;
+- deterministic policy decision;
+- trigger type;
+- consultation identifier when applicable;
+- Advisor model when applicable;
+- operational latency/cost when available;
+- later validation/failure signals when reasonably attributable.
+
+The exact durable schema/path is an implementation-planning detail.
+
+Secrets and credentials must never be written to telemetry.
+
+### Configuration
+
+Use OpenCode V2 native plugin configuration through `plugins[].options`.
+
+Do not introduce a plugin-specific sidecar configuration file.
+
+Credentials should use supported environment/file substitution or provider authentication rather than committed secrets.
+
+## Non-goals
+
+v1 does not aim to provide:
+
+- OpenCode V1 support;
+- a continuous OMP-style watchdog;
+- token-by-token or mid-generation interruption;
+- persistent private Advisor conversation state;
+- independent Advisor repository investigation;
+- Advisor tools;
+- Laya or a custom-trained routing model;
+- OpenRouter Jev support;
+- automatic routing enabled by default;
+- provider-native parent transcript replay when the public generation API cannot provide it;
+- fake tool calls for automatically generated advice;
+- user-role synthetic messages for Advisor guidance;
+- reliance on currently unexposed OpenCode instruction-entry APIs;
+- full-transcript telemetry by default;
+- replacement of `opencode-adversarial-review`.
+
+## Facts and constraints
+
+- `session.context` is the supported safe pre-provider mutation boundary for automatic routing.
+- Current fresh selected-model generation accepts a textual prompt, requiring faithful context serialization.
+- OpenCode Evaluation/Jev is experimental.
+- Native session instruction entries exist but are not exposed through the current plugin context.
+- `session.synthetic` is model-visible as user-role input and is therefore unsuitable for Advisor guidance.
+- Automatic routing adds inference latency/cost and must be measured before stronger stability claims.
+- The package is OpenCode V2-only and has no V1 line.
+- npm distribution channel is **`latest`**, not `opencode` or `opencode2`.
+- The monorepo release guard currently couples V2 release classification to the existing `opencode2` flow and must be generalized safely before release.
+
+## Assumptions requiring implementation validation
+
+### Explicit-call context fidelity
+
+Verify that all material assistant text/reasoning immediately preceding `advisor()` can be reconstructed when the tool executes.
+
+The focused runtime test must:
+
+1. make the Executor emit meaningful text/reasoning;
+2. make it call `advisor()`;
+3. inspect the captured Advisor context;
+4. assert that the immediately preceding material is recoverable.
+
+Do not add streaming-delta capture unless this demonstrates a real gap.
+
+### Jev routing quality
+
+The usefulness of Jev as an intervention router is not established empirically.
+
+`observe` exists to gather evidence without changing Executor behavior.
+
+### Provider compatibility
+
+Direct TypeSafe AI and OpenCode Zen behavior must be tested against the supported OpenCode V2 range.
+
+### Session/turn state
+
+Plugin-owned active advice and consultation budgeting must be reliably associated with the correct session and user turn.
+
+## Relevant research
+
+- [Claude Code Advisor research](../research/claude-code-advisor.md)
+- [OpenCode V2 Advisor runtime research](../research/opencode-v2-advisor-runtime.md)
+- [OpenCode V2 Jev / Evaluation research](../research/opencode-v2-jev-evaluation.md)
+
+## Relevant decisions
+
+- [ADR-0001 — Dual-path Auto Advisor architecture](../decisions/0001-dual-path-auto-advisor.md)
+- [ADR-0002 — Experimental automatic routing](../decisions/0002-experimental-automatic-routing.md)
+- [ADR-0003 — Automatic advice delivery](../decisions/0003-automatic-advice-delivery.md)
+- [Decision ledger](../DECISIONS.md)
+
+## Existing-system context
+
+The package belongs in the existing Bun/Turborepo monorepo and follows established V2 server-plugin conventions:
+
+- TypeScript strict mode;
+- `@opencode/plugin` Promise API;
+- `Plugin.define({ id, setup })`;
+- package-root `server.js`;
+- colocated package tests;
+- package-specific `AGENTS.md`;
+- MPL-2.0;
+- Changesets for releasable changes;
+- canonical root build/typecheck/lint/test validation;
+- runtime smoke verification against the actual OpenCode loading path.
+
+Auto Advisor is intentionally distinct from `opencode-adversarial-review`:
+
+```text
+Adversarial Review
+fresh reviewer
+intentionally clean context
+independent repository investigation
+adversarial code-review objective
+
+Auto Advisor
+fresh reviewer
+actual parent execution context
+no independent tools in v1
+broad trajectory/judgment objective
+```
+
+## Blocking prerequisites
+
+There is no unresolved product-level prerequisite preventing implementation planning.
+
+Before release, implementation must resolve and verify:
+
+- exact supported OpenCode V2 version/range;
+- explicit-call context-fidelity runtime behavior;
+- TypeSafe AI and Zen Evaluation compatibility;
+- actual package-root server-plugin loading;
+- safe release-policy support for a V2-born package published on `latest`.
+
+A validation failure that materially changes architecture, requirements, public interfaces, security/privacy behavior, or release strategy returns this plan to `Awaiting implementation approval`.
+
+## Proposed design
+
+### Explicit path
+
+```text
+Executor
+    ↓
+advisor()
+    ↓
+capture actual Executor context
+    ↓
+AdvisorService
+    ↓
+fresh configured model
+    ↓
+plain-text advice
+    ↓
+real tool result
+    ↓
+Executor continues
+```
+
+### Automatic path
+
+```text
+primary Executor dispatch
+          ↓
+    session.context
+          ↓
+ materially new state?
+      /          \
+    no            yes
+    │              ↓
+ continue      build routing state
+                   ↓
+             AdvisorRouter
+                   ↓
+                Jev
+                   ↓
+            RoutingPolicy
+              /       \
+            skip     consult
+             │          ↓
+             │     AdvisorService
+             │          ↓
+             │    active advice state
+             │          ↓
+             └──► system-role injection
+                        ↓
+                 Executor request
+```
+
+In `observe`, the consult branch is recorded as a hypothetical policy outcome but does not invoke the Advisor or modify Executor context.
+
+## Work decomposition
+
+The execution contracts are:
+
+1. [#48 — Establish V2 package and explicit Advisor path](https://github.com/capyBearista/opencode-plugins/issues/48)
+2. [#49 — Establish routing domain and mode control](https://github.com/capyBearista/opencode-plugins/issues/49)
+3. [#50 — Add Jev adapters and observe-mode telemetry](https://github.com/capyBearista/opencode-plugins/issues/50)
+4. [#51 — Add active automatic consultation and system-context delivery](https://github.com/capyBearista/opencode-plugins/issues/51)
+5. [#52 — Integrate release policy, documentation, and v1 readiness validation](https://github.com/capyBearista/opencode-plugins/issues/52)
+
+These are execution outcomes, not the final coding task graph. The coding orchestrator refines the implementation work graph after inspecting the current repository and capabilities available in its environment.
+
+## Validation strategy
+
+### Pure/domain validation
+
+Test:
+
+- configuration validation;
+- routing-mode behavior;
+- routing-policy decisions;
+- budget accounting;
+- fingerprint/deduplication;
+- active-advice expiry/supersession;
+- telemetry serialization;
+- provider-adapter normalization;
+- fail-open automatic behavior.
+
+### Explicit Advisor integration
+
+Verify:
+
+- `advisor()` has an empty input schema;
+- the Executor-visible description communicates intended use;
+- the configured Advisor model is used;
+- actual parent context is represented faithfully;
+- the tool returns plain-text advice;
+- consultation failures are visible;
+- preceding same-turn text/reasoning is captured.
+
+### Automatic-routing integration
+
+Verify:
+
+- Jev only runs at intended primary dispatch boundaries;
+- `off` performs no automatic routing;
+- `observe` cannot invoke Advisor or mutate Executor context;
+- `observe` requires telemetry;
+- `active` synchronously gates the waiting dispatch;
+- automatic failures allow Executor continuation;
+- automatic advice has system authority;
+- automatic advice is not represented as user input or a fake tool result;
+- applicable advice survives continuations in the same turn;
+- new user input expires prior active advice;
+- automatic budget is enforced;
+- auxiliary inference does not recursively trigger routing.
+
+### Provider validation
+
+Exercise:
+
+- direct TypeSafe AI;
+- OpenCode Zen.
+
+### Runtime validation
+
+Use a real supported OpenCode V2 installation and package-root server entrypoint.
+
+At minimum exercise:
+
+- explicit consultation;
+- `off`;
+- `observe`;
+- `active`;
+- a tool-result continuation;
+- a failing automatic-router/Advisor scenario;
+- configuration/authentication errors.
+
+### Release validation
+
+The release guard must recognize a V2-born package on npm `latest` without weakening existing frozen V1/V2 guarantees or allowing unsafe mixed V1/V2 batches.
+
+## Documentation impact
+
+Implementation is expected eventually to require:
+
+- package README;
+- package `AGENTS.md`;
+- root plugin/compatibility documentation;
+- V1/V2 compatibility documentation;
+- release-policy documentation;
+- root PR plugin checklist updates.
+
+Do not describe Auto Advisor as current repository architecture before it exists.
+
+## Acceptance criteria for v1
+
+v1 is ready when:
+
+- the V2 package loads through its real server entrypoint;
+- a configured zero-argument `advisor()` provides a fresh transcript-aware consultation;
+- explicit context fidelity is runtime verified;
+- `off`, `observe`, and `active` behave distinctly and correctly;
+- direct TypeSafe AI and Zen routing work against the declared supported V2 range;
+- `observe` produces usable telemetry without changing Executor behavior;
+- `active` can synchronously consult and inject system-role advice;
+- automatic failures fail open;
+- active automatic advice has bounded, correct turn lifetime;
+- repository quality gates and runtime smoke validation pass;
+- release tooling safely supports the V2-born `latest` policy;
+- user-facing docs accurately mark automatic routing as experimental.
+
+## Implementation handoff
+
+Before modifying implementation code, the coding orchestrator must:
+
+1. inspect repository instructions, this plan, relevant decisions, research, issues, current OpenCode APIs, and affected release tooling;
+2. inspect the agents, skills, tools, and capabilities actually available in its environment;
+3. refine the implementation work graph and validation strategy;
+4. resolve implementation-level open questions such as supported OpenCode versions and dependency pins;
+5. update this durable plan with material implementation-specific detail rather than leaving it only in chat history;
+6. set this plan to **Awaiting implementation approval**;
+7. present the refined plan to the user;
+8. stop before implementation.
+
+Implementation begins only after explicit user approval.
+
+If implementation discovery materially changes requirements, scope, architecture, accepted decisions, public interfaces, security/privacy behavior, release strategy, or acceptance criteria, update the durable artifacts, return the plan to `Awaiting implementation approval`, and request approval again.

From 812e8d251e540b2f2b0765b7edcf266dfa0758e9 Mon Sep 17 00:00:00 2001
From: Arjun Pramanik <capybearista@gmail.com>
Date: Fri, 25 Sep 2026 03:57:55 -0400
Subject: [PATCH 09/10] docs: index planning and decision artifacts

---
 docs/README.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/README.md b/docs/README.md
index 116d3a5..5e3d917 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -14,6 +14,11 @@ The root [README](../README.md) and package READMEs describe current installatio
 | [output-styles/claude-output-styles.md](./output-styles/claude-output-styles.md) | Upstream reference | Snapshot of Claude Code output-style docs. Background for the output-styles plugin, not a statement of this repo's behavior. |
 | [ram-monitor/post-mortem-v1.0.0.md](./ram-monitor/post-mortem-v1.0.0.md) | Package note | What broke and what fixed it during ram-monitor 1.0.0 stabilization. |
 | [ram-monitor/codex-comparison.md](./ram-monitor/codex-comparison.md) | Package note | Prompt-structure comparison between the official Codex plugin and this repo's review plugin. |
+| [DECISIONS.md](./DECISIONS.md) | Active | Durable project decisions. Small accepted decisions live in the ledger; larger architectural choices link to standalone ADRs under `decisions/`. |
+| [plans/opencode-auto-advisor.md](./plans/opencode-auto-advisor.md) | Draft plan | Governing product/technical plan for the proposed OpenCode Auto Advisor plugin. |
+| [research/claude-code-advisor.md](./research/claude-code-advisor.md) | Current research | Claude Advisor behavior, tool surface, persistence, and prompt evidence. |
+| [research/opencode-v2-advisor-runtime.md](./research/opencode-v2-advisor-runtime.md) | Current research | OpenCode V2 context, generation, tool timing, and automatic-advice delivery capabilities. |
+| [research/opencode-v2-jev-evaluation.md](./research/opencode-v2-jev-evaluation.md) | Revalidate before implementation | Experimental Evaluation/Jev routing capability and provider constraints. |
 
 ## Generated prompt sources
 
@@ -27,6 +32,18 @@ The V1 prompt-sync workflow stays on. There is no V2 prompt-inheritance port.
 
 Provenance notes ship with the skill where they exist. The Biome skill carries its own `LICENSE.txt` and changelog. Do not invent ownership or license claims for the rest.
 
+## Planning and durable project knowledge
+
+Non-trivial work may use:
+
+- `DECISIONS.md` plus `decisions/` for durable choices and ADR history;
+- `research/` for findings likely to matter during implementation or maintenance;
+- `plans/` for active non-trivial project plans.
+
+Plans describe intent and constraints rather than current implemented architecture. GitHub Issues remain the execution/status system. Research is not archived merely because a current task stops using it; mark it for revalidation or supersession when its facts or applicability change. ADRs normally remain in place and use status to record lifecycle.
+
+Completed or cancelled plans may later move to `archive/plans/` after current architecture, durable decisions, research, and unresolved execution work have been reconciled.
+
 ## Conventions
 
 Dated documents retain their scope banners and existing paths. Prefer links to current installation instructions rather than copying them; the V1 guide is the explicit compatibility reference for frozen releases. Update navigation and inbound links together if documents move.

From 8f360f0f246bcdc52c74933ab0c89f454d77ffff Mon Sep 17 00:00:00 2001
From: Arjun Pramanik <capybearista@gmail.com>
Date: Fri, 25 Sep 2026 03:58:13 -0400
Subject: [PATCH 10/10] docs(agents): add planning knowledge contract

---
 AGENTS.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 0079395..aabae8e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -17,6 +17,19 @@ Subdirectories contain specialized files that extend these rules.
 - **MUST** run `bun run typecheck && bun run lint && bun run test && bun run build` before opening a PR
 - **MUST NOT** commit secrets, API keys, or tokens
 
+### Planning and Durable Knowledge (MUST)
+
+- **MUST** inspect applicable active plans, accepted decisions/ADRs, relevant research, current architecture documentation, linked Issues, and package-local instructions before substantial implementation work.
+- **MUST NOT** silently contradict an accepted durable decision. If implementation requires a material change, update the governing plan/decision record and obtain any required approval before proceeding.
+- **MUST** keep non-trivial implementation planning in repository artifacts rather than only in chat history.
+- **MUST** honor plan approval gates. Do not begin implementation while a governing plan is `Draft`, `Awaiting implementation approval`, or `Blocked`.
+- **MUST** distinguish a required blocked prerequisite from consciously deferred scope; do not bypass blockers by relabeling them deferred.
+- **MUST** update `docs/DECISIONS.md` and any applicable ADR when a durable decision is accepted or superseded. ADRs normally stay in place and use status/links to preserve decision history.
+- **MUST** reconcile durable project knowledge before considering implementation complete: resulting architecture, decisions, research, documentation, acceptance criteria, blockers, and remaining Issues must match reality.
+- **MUST** update current architecture documentation when implementation materially changes system/module boundaries, persistent state, interfaces, runtime topology, or major integration relationships.
+- **MUST** treat artifacts under archive paths as historical context, not authoritative current state, unless verified against current code, decisions, architecture, and active plans.
+- **SHOULD** use `docs/plans/` for non-trivial active plans, `docs/research/` for reusable research, and `docs/decisions/` for standalone ADRs when no more specific established convention applies.
+
 ### Plugin Development (MUST)
 
 Scope: V1 packages. The two V2 ports use the Promise API instead; see the V2 boundary below.