* fix(#2615): document the effortSurface axis in the host-integration matrix #2481 added `effortSurface` as the ninth negotiated `hostIntegration` axis and wrote documentation-sourced values into 18 descriptors, but never touched `docs/reference/host-integration-capability-matrix.md`. The matrix that ADR-1239 designates the cited source of truth had zero occurrences of the axis: no entry in the axes legend, and no row in any of the per-runtime tables. `src/host-integration.cts` states "every value is documented or explicitly 'undocumented'" — for this axis that was false for every runtime. Adds the legend entry (the `argv` / `none` / `undocumented` vocabulary, plus why there is deliberately no config-file member) and an `effortSurface` row to all 19 per-runtime tables. Every citation is carried over from #2481's own commit message, where the values were sourced: - claude argv -- `claude --help` documents `--effort <level>` - opencode argv -- `opencode run --help` documents `--variant` - codex argv -- `model_reasoning_effort` is a config.toml key, not a dedicated flag, so the generic `-c key=value` override is the only argv route (still argv) - 15 hosts undocumented -- their docs state no reasoning setting kimi-code is the nineteenth section (added by #2603 after #2481) and is the one runtime with no declared value. Its row and a Documentation-gaps entry record why rather than inventing one: Kimi Code documents `/effort` (alias `/thinking`), but only as an INTERACTIVE slash command — `-m, --model` is the only model-adjacent argv. Neither vocabulary member is accurate (`none` would deny a mechanism the host has, `argv` would claim one it does not expose), so closing that gap needs a vocabulary decision, which is a negotiation change and not a documentation one. The absent value already degrades closed exactly as the sentinel does. The regression test derives its runtime list from the registry rather than hardcoding it, so a runtime added later fails until its matrix row exists — the ratchet whose absence let #2481 add an axis with nothing catching the missing docs. Closes #2615 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QT3ibz5qJuDuGqpTGRYVGf * docs(#2615): honest citations for the undocumented rows; fix the four stale 8-axis lists Two findings from the orthogonal review of the first commit. 1. The 15 `undocumented` rows shared byte-identical text — "searched the runtime's official docs (see Sources consulted above)" — which is weaker than this file's own convention ("no authoritative doc — searched: <url>") and, worse, implies a per-host targeted search that did not happen: each section's Sources-consulted list was gathered for OTHER axes and contains no CLI-reference or reasoning-effort source. The rows now say plainly what the finding is — an ABSENCE established by #2481's cross-host survey — and cite that survey rather than implying a URL was checked per host. 2. Four normative docs still described "the eight negotiated axes" and omitted effortSurface entirely. The worst of them is docs/how-to/add-or-update-a-host-integration.md — the maintainer's own guide for onboarding a host, whose Step 2 axis table would have a maintainer reproduce exactly the gap #2615 exists to close. Also fixed: docs/reference/host-integration-interface.md (which calls itself the normative reference and had no effortSurface row at all), docs/how-to/author-a-host-plugin.md, docs/registries/README.md ("**exactly** the eight … axes keys"), and CONTEXT.md's matching EoS-registry sentence. Deliberately NOT changed, because they are historical records rather than current contract: docs/whats-new-1.7.0.md and docs/FEATURES.md's 1.7.0 entry (effortSurface shipped in 1.8.0 via #2481 — rewriting them would falsify the release history), ADR-1239's pre-amendment body (already superseded by its own "Amendment (2026-07-21): effortSurface axis (#2481)"), and ADR-1016's "original eight axes", which refers to a different axis set entirely. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QT3ibz5qJuDuGqpTGRYVGf * chore(#2615): backfill changeset PR number (#2698) --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
@@ -2,7 +2,7 @@
|
||||
|
||||
This guide is for GSD maintainers adding a new host CLI, or updating an existing host's
|
||||
host-integration axes (ADR-1239 Phase A). It covers the **documentation-sourcing rule**, the
|
||||
eight `runtime.hostIntegration` axes, the `undocumented` sentinel, and how to validate.
|
||||
nine `runtime.hostIntegration` axes, the `undocumented` sentinel, and how to validate.
|
||||
|
||||
The governing rule for this whole process: **every axis value must come from the host's own
|
||||
authoritative documentation. Never infer, guess, or assume.** Where the docs do not state an axis,
|
||||
@@ -22,7 +22,7 @@ In order of preference:
|
||||
Capture the exact source (Context7 library id + query, or the doc URL) and a short verbatim quote
|
||||
for each value you determine. You will paste these into the matrix in step 4.
|
||||
|
||||
## 2. Determine each of the eight axes from the docs
|
||||
## 2. Determine each of the nine axes from the docs
|
||||
|
||||
Read the docs and map them to the closed vocabulary. Do not pick a value unless a source states it.
|
||||
|
||||
@@ -36,6 +36,7 @@ Read the docs and map them to the closed vocabulary. Do not pick a value unless
|
||||
| `stateIO` | `filesystem`, `sandboxed-storage` (web IDE, no arbitrary FS), or `session-log-append`. |
|
||||
| `transport` | `mcp` (native MCP support) vs. `native-extension` (MCP needs a community extension). |
|
||||
| `runtime` | The plugin/extension runtime: `node`, `bun`, `sandboxed-web`, `python`, `go`, `rust`, `electron`, `other`. |
|
||||
| `effortSurface` | How reasoning effort reaches the host: `argv` (a flag on the host's own invocation) or `none` (no reasoning-effort mechanism). Added by #2481. There is deliberately **no** config-file member — do not invent one; use `undocumented` when the host's docs state no reasoning setting. |
|
||||
|
||||
## 3. Write the `runtime.hostIntegration` block
|
||||
|
||||
|
||||
@@ -27,8 +27,8 @@ from your axes):
|
||||
|
||||
## 2. Declare your host's integration axes
|
||||
|
||||
Declare the eight negotiated axes (`embeddingMode`, `commandSurface`, `dispatch`,
|
||||
`modelMode`, `hookBus`, `stateIO`, `transport`, `runtime`) from your host's
|
||||
Declare the nine negotiated axes (`embeddingMode`, `commandSurface`, `dispatch`,
|
||||
`modelMode`, `hookBus`, `stateIO`, `transport`, `runtime`, `effortSurface`) from your host's
|
||||
**authoritative documentation** — never infer. Where the docs are silent, use the
|
||||
`undocumented` sentinel (the SDK degrades it fail-closed). See
|
||||
`docs/reference/host-integration-interface.md` for the closed vocabulary.
|
||||
|
||||
Reference in New Issue
Block a user