From 2129dfbc0366c834ce6128b9b58e55cdcbb58c93 Mon Sep 17 00:00:00 2001 From: Chris Phillipson Date: Sun, 16 Aug 2026 13:47:24 -0700 Subject: [PATCH] docs: file the two upstream capability requests; drop the local drafts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The ADR-0031 §4 requests are now filed upstream: - agentic-qe provider-plugin: proffesor-for-testing/agentic-qe#628 - ruflo backend-registration: ruvnet/ruflo#3046 Both invite the maintainer to close-as-satisfied if current source already provides the surface. Removes docs/upstream-requests/ (the drafts served their purpose) and points the freeze checklist + ADR-0031 references at the filed issues instead of the local files. --- docs/HOST-ADAPTER-FREEZE-CHECKLIST.md | 8 ++- ...bility-graduation-and-upstream-requests.md | 8 ++- .../agentic-qe-provider-plugin.md | 72 ------------------- .../ruflo-backend-registration.md | 65 ----------------- 4 files changed, 11 insertions(+), 142 deletions(-) delete mode 100644 docs/upstream-requests/agentic-qe-provider-plugin.md delete mode 100644 docs/upstream-requests/ruflo-backend-registration.md diff --git a/docs/HOST-ADAPTER-FREEZE-CHECKLIST.md b/docs/HOST-ADAPTER-FREEZE-CHECKLIST.md index 5004312..a045666 100644 --- a/docs/HOST-ADAPTER-FREEZE-CHECKLIST.md +++ b/docs/HOST-ADAPTER-FREEZE-CHECKLIST.md @@ -45,7 +45,7 @@ while the contract is still experimental. - [ ] `activity-routing` passed - [ ] `primary-eligible` passed *(or consciously out of scope for this adapter)* - [ ] `session-driving` — passed **iff** the upstream ruflo backend-registration request - (`docs/upstream-requests/ruflo-backend-registration.md`) has shipped; otherwise + ([ruvnet/ruflo#3046](https://github.com/ruvnet/ruflo/issues/3046)) has shipped; otherwise legitimately `gated` and recorded via `ak host adapters gate`. - [ ] `statusline` — `gated` remains acceptable at freeze (its render path is a later wave); the freeze is of the **contract shape**, not of every tier passing. @@ -69,8 +69,10 @@ while the contract is still experimental. The freeze is of the **contract shape**, not of universal tier passage. These stay open by design and are recorded as gated, not as failures: -- `session-driving` until ruflo ships a backend-registration surface (upstream request drafted). -- An `aqeProvider` identity until agentic-qe ships a provider-plugin API (upstream request drafted). +- `session-driving` until ruflo ships a backend-registration surface (filed: + [ruvnet/ruflo#3046](https://github.com/ruvnet/ruflo/issues/3046)). +- An `aqeProvider` identity until agentic-qe ships a provider-plugin API (filed: + [proffesor-for-testing/agentic-qe#628](https://github.com/proffesor-for-testing/agentic-qe/issues/628)). - `statusline` runtime rendering (no `ak` render surface for a third-party TUI yet). - Grant *consumption* last-mile: selecting an external host as primary, and a `commandStatusline` runtime reader. diff --git a/docs/adr/0031-capability-graduation-and-upstream-requests.md b/docs/adr/0031-capability-graduation-and-upstream-requests.md index 9d0b908..d0e5cce 100644 --- a/docs/adr/0031-capability-graduation-and-upstream-requests.md +++ b/docs/adr/0031-capability-graduation-and-upstream-requests.md @@ -194,8 +194,12 @@ unbuilt. This table is the source of truth for what is real. `activity-routing` and `primary-eligible` tiers. - Upstream facts grounded in a source-cited research sweep: `agentic-qe@3.13.10` (`ALL_PROVIDER_TYPES`, the `createProvider` switch, the closed provider enum) and - `ruvnet/ruflo@45e65b5` (`ENABLE_*` backend model). Re-verify against upstream HEAD before filing an - actual capability request. + `ruvnet/ruflo@45e65b5` (`ENABLE_*` backend model). The two §4 capability requests have been filed — + the AQE provider-plugin request as + [proffesor-for-testing/agentic-qe#628](https://github.com/proffesor-for-testing/agentic-qe/issues/628) + and the ruflo backend-registration request as + [ruvnet/ruflo#3046](https://github.com/ruvnet/ruflo/issues/3046), each inviting the maintainer to + close-as-satisfied if the current source already provides the surface. - Companion explainer for consumers and implementers: [`docs/HOST-EXTENSIBILITY-EXPLAINER.html`](../HOST-EXTENSIBILITY-EXPLAINER.html); design dossier: [`docs/ADAPTER-CONTRACT-DOSSIER.html`](../ADAPTER-CONTRACT-DOSSIER.html). diff --git a/docs/upstream-requests/agentic-qe-provider-plugin.md b/docs/upstream-requests/agentic-qe-provider-plugin.md deleted file mode 100644 index 02c2ac2..0000000 --- a/docs/upstream-requests/agentic-qe-provider-plugin.md +++ /dev/null @@ -1,72 +0,0 @@ - - -# Feature request: a provider-plugin registration API for `AQE_LLM_PROVIDER` - -## Summary - -agentic-qe's LLM provider set is a closed, upstream-defined enumeration. A downstream -integrator (agentic-kit) can select any *existing* provider via `AQE_LLM_PROVIDER`, but -cannot introduce a *new* provider type without an upstream code change. We'd like a -documented registration surface so a host that a downstream tool supervises can be -recognized as its own provider identity, rather than only borrowing the model provider -underneath it. - -## Where this stands today (please re-verify against HEAD) - -Grounded against `agentic-qe@3.13.10` (as cited in agentic-kit's ADR-0031): - -- `ALL_PROVIDER_TYPES` is a fixed union of provider type strings. -- `createProvider` is a `switch` over those types; an unrecognized type has no arm. -- So the provider set is extended only by editing that enum + switch — there is no - runtime/plugin registration path. - -If any of this has changed on HEAD (a registration hook, an open provider map, a plugin -entrypoint), this request may already be satisfied — please close it as such. - -## The concrete ask - -A minimal, documented way for a downstream tool to register an additional provider type at -runtime, e.g.: - -- a `registerProvider(type, factory)` entrypoint (factory conforming to the same interface - `createProvider` returns), and inclusion of registered types in `ALL_PROVIDER_TYPES` - for validation; **or** -- a documented "external provider" adapter interface a downstream package can implement - and hand to the `HybridRouter` / `ProviderManager`. - -We are not asking to widen the *default* provider set — only for a sanctioned extension -point so `AQE_LLM_PROVIDER=` can resolve to a provider we supply, instead of us -either forking the enum or projecting our host onto an unrelated provider identity (which -would misrepresent which vendor served the work). - -## Why (the downstream context) - -agentic-kit admits external host adapters (declarative manifest + consented subprocess -hooks) and runs a tiered conformance kit against them. Quality still runs through the -*model provider underneath* a host, so QE is never blocked — but a host cannot earn an -**AQE-provider identity** of its own, because that identity is yours to define, not ours to -extend. agentic-kit deliberately refuses to fabricate one (projecting an unknown host into -your config would assert an identity you never declared you understood). This request is -the honest alternative: a real extension point, so the capability can light up when you -release it. - -## Non-goals - -- Not asking agentic-kit's hosts to be bundled into agentic-qe. -- Not asking to bypass any provider validation — registered providers should be validated - exactly like built-in ones. - -## References - -- agentic-kit ADR-0031 §4 (the upstream-request path) and ADR-0029 (the host-adapter - contract): the design that motivates this. -- `AQE_LLM_PROVIDER` / `HybridRouter` / `createProvider` / `ALL_PROVIDER_TYPES` in - agentic-qe (re-verify paths against HEAD). diff --git a/docs/upstream-requests/ruflo-backend-registration.md b/docs/upstream-requests/ruflo-backend-registration.md deleted file mode 100644 index c9f46e2..0000000 --- a/docs/upstream-requests/ruflo-backend-registration.md +++ /dev/null @@ -1,65 +0,0 @@ - - -# Feature request: a documented backend-registration surface for host CLIs - -## Summary - -ruflo's set of agent **backends** (the host CLIs that drive the loop) is enabled per-host -through fixed `ENABLE_*` flags. There is no documented way for a downstream tool to -register an *additional* backend, so a host CLI that a downstream integrator supervises -cannot become a ruflo-native backend without an upstream code change. We'd like a -documented registration surface for that. - -## Where this stands today (please re-verify against HEAD) - -Grounded against `ruvnet/ruflo@45e65b5` (as cited in agentic-kit's ADR-0031): - -- Backend enablement is per-host and fixed: `ENABLE_CLAUDE_CODE`, `ENABLE_CODEX`, - `ENABLE_GEMINI_MCP` (ADR-034 "Optional MCP Backends"). -- A new backend is added by defining a new `ENABLE_*` target inside ruflo — there is no - outside/plugin registration path. - -If HEAD already exposes a backend-registration API or a documented plugin entrypoint, this -request may already be satisfied — please close it as such. - -## The concrete ask - -A documented way to register an additional agent backend from outside the ruflo tree, e.g.: - -- a backend descriptor interface (how ruflo detects the CLI, launches an interactive / - oneshot session, and observes completion) that a downstream package can implement and - register, honored by the same loop the `ENABLE_*` backends drive; **or** -- a documented convention for an external backend entrypoint ruflo will discover and drive. - -The goal is that a host CLI can *drive a ruflo session* as a first-class backend, not only -run under a downstream tool's own supervision. - -## Why (the downstream context) - -agentic-kit admits external host adapters and certifies them with a tiered conformance kit. -The `session-driving` tier — "the host actually drives an interactive/oneshot session" — -is the one an external adapter cannot clear on its own, because being a ruflo-native -backend is defined inside ruflo, not registered from outside. agentic-kit's honest interim -is to run such a host through its *own* supervised execution (`ak run`), and to mark the -tier `gated` on this request rather than fake a pass. A documented backend-registration -surface upstream is what lets that tier genuinely light up. - -## Non-goals - -- Not asking to bundle agentic-kit's hosts into ruflo. -- Not asking to loosen the trust model — a registered backend should be subject to the same - enablement/consent posture as the built-in `ENABLE_*` backends. - -## References - -- agentic-kit ADR-0031 §4 (the upstream-request path) and ADR-0029 (the host-adapter - contract). -- ruflo ADR-034 "Optional MCP Backends" and the `ENABLE_CLAUDE_CODE` / `ENABLE_CODEX` / - `ENABLE_GEMINI_MCP` backend model (re-verify paths against HEAD).