diff --git a/CONTEXT.md b/CONTEXT.md index 6f6c8be02..c7f40e77f 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -206,7 +206,7 @@ Generated central manifest projecting all co-located Capability declarations int ADR-857 phase 3b seam that merges capability-declared config slices into the `loadConfig` return value. Implemented in `src/federated-config.cts` → `gsd-core/bin/lib/federated-config.cjs`. Exports `mergeFederatedConfig({ configSchema, isCentralKey, userConfig }) → { values, validKeys, warnings }`. Rules: central-schema keys are skipped with a `pending-migration` warning; malformed slices are skipped with a warning (never throws); valid federated keys (absent from the central schema) resolve to the user-supplied value (if type-matches) or the slice default. Object writes are guarded against prototype pollution with inline literal `__proto__`/`constructor`/`prototype` key checks. ADR-857 phase 6 made the channel live for migrated Capability keys: `config-schema.cjs` exposes `isCentralConfigKey()` for central ownership and `isValidConfigKey()` accepts central + runtime + dynamic + Capability-owned registry keys. `loadConfig` exposes `_setFederatedRegistryForTests`/`_resetFederatedRegistryForTests` seams for injecting a synthetic registry in tests. ### Capability Registry Overlay -Runtime seam (`gsd-core/bin/lib/capability-loader.cjs`, ADR-1244 D2) that composes the frozen first-party Capability Registry (`capability-registry.cjs`) with a validated installed overlay of third-party capability manifests discovered at load time. Install roots are global (`$GSD_HOME/.gsd/capabilities//capability.json`, where `GSD_HOME` defaults to `~`) and project (`/.gsd/capabilities//capability.json`). Primary interface: `loadRegistry({ includeInstalled }) → registry` — when `includeInstalled` is true the overlay is merged via the canonical `buildRegistry` so all derived views (bySkill, byAgent, byLoopPoint, configKeys) cover first-party and overlay entries identically. First-party always wins: any overlay entry whose id, owned skill/agent stem, or federated config key collides with first-party, or whose id uses a reserved `gsd-`/`gsd-core-`/`anthropic-` prefix, is rejected at load time. Load-time re-gate: an overlay failing schema validation or whose `engines.gsd` semver range does not satisfy the running GSD version is skipped with a warning and never crashes the load loop. Per-hook-kind policy: a skipped capability that declared a `gate`-kind hook fails CLOSED (the loop resolver injects a blocking gate); skipped `step` or `contribution` capabilities skip open. A capability dir whose co-located ledger entry carries an in-flight `_pending` intent (a crashed/uncommitted install or upgrade, ADR-1244 Phase 4) is skipped OPEN (never activated until reconciliation commits or rolls it back). #1459 user-owned consent gate: a PROJECT-scope overlay is activated (declarative surfaces AND command dispatch) ONLY when the user-owned Capability Consent Store holds a record for `(realpath(projectRoot), id)` whose stored `contentHash` equals the bundle content hash the loader RECOMPUTES at load (`bundleContentHash(capDir)` over the whole on-disk bundle) — NOT the repo-plantable ledger integrity nor the executable-only disclosure signature — otherwise the cap is DISCOVERED-BUT-INACTIVE (a warning carrying `kind:'unconsented'`, no surfaces, empty commandRoots), so a forged/cloned in-repo project ledger or any post-consent tamper no longer activates anything; GLOBAL scope (under the user's own home) is trusted without a record, and the global-vs-project root dedup/escalation is realpath-keyed so a symlinked `GSD_HOME` aliasing the project root cannot bypass the gate (finding 1). The consent lookup is wrapped to fail CLOSED (inactive); both the per-scope ledger AND the `capability.json` manifest are read via the shared bounded `readSmallRegularFile` (a repo-planted FIFO/oversized ledger or manifest can no longer hang or OOM the loader — finding 2). The loader reuses the ledger's shared `isValidLedgerEntry` for committed-entry parity. Consumers wired to the overlay-aware registry: `config-loader.cjs`, `config-schema.cjs`, `capability-state.cjs`, `loop-resolver.cjs`. +Runtime seam (`gsd-core/bin/lib/capability-loader.cjs`, ADR-1244 D2) that composes the frozen first-party Capability Registry (`capability-registry.cjs`) with a validated installed overlay of third-party capability manifests discovered at load time. Install roots are global (`$GSD_HOME/.gsd/capabilities//capability.json`, where `GSD_HOME` defaults to `~`) and project (`/.gsd/capabilities//capability.json`). Primary interface: `loadRegistry({ includeInstalled }) → registry` — when `includeInstalled` is true the overlay is merged via the canonical `buildRegistry` so all derived views (bySkill, byAgent, byLoopPoint, configKeys) cover first-party and overlay entries identically. First-party always wins: any overlay entry whose id, owned skill/agent stem, or federated config key collides with first-party, or whose id uses a reserved `gsd-`/`gsd-core-`/`anthropic-` prefix, is rejected at load time. Load-time re-gate: an overlay failing schema validation or whose `engines.gsd` semver range does not satisfy the running GSD version is skipped with a warning and never crashes the load loop. Per-hook-kind policy: a skipped capability that declared a `gate`-kind hook now fails OPEN (#2009) — the loop resolver injects no gate and instead emits a loud warning naming the load-failure reason and the exact `gsd capability remove ` remediation, and the loop proceeds (the loader still records `_overlay.blockedGates`; only the consequence changed from block to warn); skipped `step` or `contribution` capabilities skip open. A capability dir whose co-located ledger entry carries an in-flight `_pending` intent (a crashed/uncommitted install or upgrade, ADR-1244 Phase 4) is skipped OPEN (never activated until reconciliation commits or rolls it back). #1459 user-owned consent gate: a PROJECT-scope overlay is activated (declarative surfaces AND command dispatch) ONLY when the user-owned Capability Consent Store holds a record for `(realpath(projectRoot), id)` whose stored `contentHash` equals the bundle content hash the loader RECOMPUTES at load (`bundleContentHash(capDir)` over the whole on-disk bundle) — NOT the repo-plantable ledger integrity nor the executable-only disclosure signature — otherwise the cap is DISCOVERED-BUT-INACTIVE (a warning carrying `kind:'unconsented'`, no surfaces, empty commandRoots), so a forged/cloned in-repo project ledger or any post-consent tamper no longer activates anything; GLOBAL scope (under the user's own home) is trusted without a record, and the global-vs-project root dedup/escalation is realpath-keyed so a symlinked `GSD_HOME` aliasing the project root cannot bypass the gate (finding 1). The consent lookup is wrapped to fail CLOSED (inactive); both the per-scope ledger AND the `capability.json` manifest are read via the shared bounded `readSmallRegularFile` (a repo-planted FIFO/oversized ledger or manifest can no longer hang or OOM the loader — finding 2). The loader reuses the ledger's shared `isValidLedgerEntry` for committed-entry parity. Consumers wired to the overlay-aware registry: `config-loader.cjs`, `config-schema.cjs`, `capability-state.cjs`, `loop-resolver.cjs`. ### Community Capability Registry Human-facing discoverability catalog (`docs/registries/capability-registry.md`, generated from `docs/registries/capabilities.json`; issue #2182) listing third-party Feature Capabilities registered by a docs PR so a solo developer can find one before installing it. Distinct from **Capability Registry** (the generated runtime manifest compiled from first-party `capability.json` declarations, ADR-894) and **Capability Registry Overlay** (the runtime seam that merges an installed third-party manifest into that generated registry at load time, ADR-1244 D2): this registry is a static document rendered by `scripts/gen-registry.cjs`, not a runtime data structure or loader. Each entry enumerates the capability's Loop Extension Points and hook kinds so a reader can judge blast radius before running `gsd capability install`, and declares its `engines.gsd` range. Inclusion is an explicit non-endorsement — a maintainer merged a link, nothing more — per `docs/registries/README.md`. diff --git a/README.md b/README.md index 9f5f08857..827703331 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,8 @@ New here? Follow [Your first project](docs/tutorials/your-first-project.md) for ## Documentation +**What's new in 1.7.0** → [docs/whats-new-1.7.0.md](docs/whats-new-1.7.0.md) + **Tutorials** — learning by doing: - [Your first project](docs/tutorials/your-first-project.md) - [Onboarding an existing codebase](docs/tutorials/onboarding-an-existing-codebase.md) diff --git a/docs/FEATURES.md b/docs/FEATURES.md index 9b7540314..a2ee406bc 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -171,6 +171,17 @@ - [MemPalace Memory Capability](#145-mempalace-memory-capability) - [Spec-Phase Prohibition Probe](#146-spec-phase-prohibition-probe) - [Capability Management Command](#147-capability-management-command) + - [Smart Entry Launcher](#148-smart-entry-launcher) +- [v1.7.0 Features](#v170-features) + - [Embeddable Orchestration System (Host-Integration Interface)](#149-embeddable-orchestration-system-host-integration-interface) + - [Discoverability Registries](#150-discoverability-registries) + - [Companion MCP Server](#151-companion-mcp-server) + - [Statusline Token Count & Git Segment](#152-statusline-token-count--git-segment) + - [Model Catalog Advances](#153-model-catalog-advances) + - [Claude Orchestration Capability (BETA)](#154-claude-orchestration-capability-beta) + - [External-Job Capability](#155-external-job-capability) + - [API-Coverage Gate](#156-api-coverage-gate) + - [State Rebuild & Configurable Graph Path](#157-state-rebuild--configurable-graph-path) --- @@ -3256,3 +3267,89 @@ The load-bearing wire is the `plan-phase` lift into `must_haves.prohibitions`, s **Reference:** [Smart Entry Design](superpowers/specs/2026-06-27-gsd-smart-entry-design.md) --- + +## v1.7.0 Features + +> These are features new to **@opengsd/gsd-core 1.7.0** (the current release line: 1.0.0 → 1.2.0 → … → 1.6.1 → 1.7.0). The preceding `v1.27`–`v1.43.0` sections use the retired get-shit-done-cc / get-shit-done-redux feature numbering and are not gsd-core releases — see [Legacy Release Notes](RELEASE-NOTES-LEGACY.md). + +### 149. Embeddable Orchestration System (Host-Integration Interface) + +**Purpose:** Express every host integration against one public, versioned contract (ADR-1239 Phase A, #1690) instead of bespoke per-host wiring, so onboarding a new host becomes additive descriptor work. + +**Behavior:** The interface exposes six interface points (`command`, `dispatch`, `model`, `hooks`, `state`, `artifact`), eight negotiated axes, and a `PROTOCOL_VERSION` handshake that negotiates down to `min(host, engine)`. In 1.7.0, 14 runtimes were migrated onto the interface via imperative adapters (OpenCode #2087, Cursor #2089, Cline #2090, Hermes #2091, Qwen #2092, Kilo #2093, Trae #2094, Kimi #2095, Antigravity #2096, Augment #2097), a declarative adapter (Codex #2088), plus full lifecycle-hook wiring for CodeBuddy (#2098), GitHub Copilot (#2099), and Windsurf (#2100). Descriptors gained an `extensionEvents` vocabulary (#1946), and `/gsd:surface` now reproduces a runtime's agent output byte-for-byte from the installer's descriptors (#1575). + +**New runtimes:** ZCode (Z.ai — Agentic Development Environment for GLM-5.2, #1925), pi (`npx @opengsd/gsd-core --pi`, #2102), and a repo-local VS Code extension driven through the adapter (#2103). The retired Gemini CLI now redirects to Antigravity CLI, its official successor (#1928). + +**Reference:** [The Embeddable Orchestration System](explanation/embeddable-orchestration-system.md) · [Host-Integration Interface](reference/host-integration-interface.md) · [Interface versioning policy](explanation/interface-versioning-policy.md) + +--- + +### 150. Discoverability Registries + +**Purpose:** Two non-endorsing catalogs for third-party extensions (#2182). + +**Behavior:** The **Community Capability Registry** (#2188) lists third-party Feature Capabilities installed with `gsd capability install`; the **EoS Registry** (#2193) lists third-party host integrations built on the ADR-1239 interface. Every entry embeds a live release badge and links to a GitHub Discussion. Registration is a documentation PR, regenerated with `npm run gen:registry`. + +**Reference:** [GSD Registries](registries/README.md) + +--- + +### 151. Companion MCP Server + +**Command:** `gsd-mcp-server` + +**Purpose:** A companion MCP server exposing GSD over stdio JSON-RPC 2.0, covering interface points 1 and 5 (#1681). + +**Behavior:** OpenCode installs auto-register it as `mcp.gsd` (#1682). OpenCode also gained the `opencode-subset` hook dialect plus `session.idle` handling (#1682) and now runs GSD's lifecycle safety hooks — prompt-injection guard, read-before-edit guard, and injection scanner (#1923). + +--- + +### 152. Statusline Token Count & Git Segment + +**Purpose:** Opt-in statusline additions surfacing more session context. + +**Behavior:** An absolute token count on the context meter (#2161) and a git branch + working-state segment (#2163), both opt-in. A companion opt-in **compact GSD-state format** condenses the GSD state segment (#2162). + +**Configuration:** `statusline.*` + +--- + +### 153. Model Catalog Advances + +**Purpose:** Refresh the default model tiers and how models are surfaced. + +**Behavior:** Codex/OpenAI defaults advance to the **GPT-5.6 family (Sol / Terra / Luna)** (#2122); the verbose `(1M context)` model suffix collapses to a compact `(1M)` badge (#2160). GSD warns when model config changes without re-running the installer on static-frontmatter runtimes such as Codex and OpenCode (#1688). + +**Reference:** [Configuration](CONFIGURATION.md) · [Configure model profiles](how-to/configure-model-profiles.md) + +--- + +### 154. Claude Orchestration Capability (BETA) + +**Purpose:** A default-off, BETA, Claude-only capability that adopts Claude Code's Workflow tool for parallel sub-agent orchestration (#1143). + +**Reference:** [The Claude orchestration capability](explanation/claude-orchestration-capability.md) + +--- + +### 155. External-Job Capability + +**Purpose:** A default-off capability that externalizes long-running compute as asynchronous external jobs, e.g. SLURM submission (#1165). + +**Configuration:** `external_job.submit_timeout_ms`, `external_job.poll_timeout_ms`, `external_job.artifact_dir` (#1164) + +--- + +### 156. API-Coverage Gate + +**Command:** `/gsd:verify-work` + +**Purpose:** A phase that integrates an external API, SDK, or service can no longer seal verification without a decided coverage matrix (#1562). + +--- + +### 157. State Rebuild & Configurable Graph Path + +**Behavior:** A new `gsd-tools state rebuild` subcommand re-derives `STATE.md` from source (#1830). The new `graphify.graph_path` setting makes the knowledge-graph location configurable, so a single umbrella graph can serve several projects (#1825). + +**Configuration:** `graphify.graph_path` diff --git a/docs/README.md b/docs/README.md index c78509ffa..4d1d1f5ba 100644 --- a/docs/README.md +++ b/docs/README.md @@ -74,6 +74,7 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) - [The capability trust model](explanation/capability-trust-model.md) — why third-party capabilities are gated by consent + integrity + reversibility, not a sandbox - [How overlay capabilities compose](explanation/capability-overlay-model.md) — why first-party always wins and how the loader resolves precedence, conflicts, and fail-open load-failure warnings - [Architecture](ARCHITECTURE.md) — system architecture, agent model, and data flow +- [The Embeddable Orchestration System](explanation/embeddable-orchestration-system.md) — one public, versioned contract for embedding GSD across many hosts - [Discuss modes](workflow-discuss-mode.md) — assumptions mode vs interview mode for `/gsd-discuss-phase` - [Context monitoring](context-monitor.md) — context window monitoring hook architecture - [Issue-driven orchestration](issue-driven-orchestration.md) — recipe for driving GSD from a tracker issue using existing primitives @@ -82,5 +83,6 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) ## Related +- [What's new in 1.7.0](whats-new-1.7.0.md) — curated highlights of the 1.7.0 release - [Root README](../README.md) — landing page, quickstart, and documentation overview - [Changelog](../CHANGELOG.md) — release history diff --git a/docs/explanation/embeddable-orchestration-system.md b/docs/explanation/embeddable-orchestration-system.md new file mode 100644 index 000000000..a3d9e23dc --- /dev/null +++ b/docs/explanation/embeddable-orchestration-system.md @@ -0,0 +1,183 @@ +# The Embeddable Orchestration System (EoS) + +> **Explanation** — This document describes *why* GSD is built around one +> versioned interface for embedding inside many different host applications, +> and *how* the interface points, negotiated axes, and adapter shapes fit +> together. It is not a how-to; for field-level detail see the +> [Host-Integration Interface reference](../reference/host-integration-interface.md). +> For the compatibility rules that interface itself follows, see +> [Interface versioning and deprecation policy](interface-versioning-policy.md). + +--- + +## The problem it solves + +GSD is a filesystem-native orchestration engine, not a standalone +application. Almost all of the useful work it does — running a loop, +dispatching an agent, resolving a model, persisting state — happens *inside* +some other program: a CLI, an IDE, or an agentic desktop app. Each of those +hosts has its own command surface, its own hook system, its own idea of how a +model call gets routed, and its own storage model. There is no shared +substrate a priori. + +Before 1.7.0, every host integration was wired bespoke: a runtime-specific +adapter that reached into GSD's internals however it needed to, and exposed +whatever surface that host happened to support. That does not scale. Each new +host is a fresh bespoke integration to write and maintain, drift between +hosts accumulates silently over time, and no third party can build a host +integration without reverse-engineering GSD's internals from source. + +The **Embeddable Orchestration System (EoS)** is the answer: one public, versioned +contract — the ADR-1239 Host-Integration Interface — that every host +integration is expressed against, first-party and third-party alike (Phase A, +#1690). A host does not reach into GSD's internals; it declares which +interface points it binds and which values it supports for each negotiated +axis, and the engine tells it, deterministically, what it gets. + +## The contract: interface points, negotiated axes, and a version handshake + +The interface has three moving parts. + +**Six interface points** are the places a host can bind to GSD: `command` +(how a user invokes a GSD command), `dispatch` (how that invocation reaches +the orchestration loop), `model` (how model calls are routed), `hooks` (how +lifecycle events fire), `state` (how `.planning/` state is read and +written), and `artifact` (how generated files are produced). A host does not +have to bind all six — degradation per point is graceful and explicit (see +`degradationFor` in the reference). + +**Eight negotiated axes** describe *how* a given host binds those points, not +*whether* it does. `embeddingMode`, `commandSurface`, `dispatch`, +`modelMode`, `hookBus`, `stateIO`, `transport`, and `runtime` form a closed +vocabulary — a host declares a value from a documented set for each axis (or +the `undocumented` sentinel), and the engine negotiates the resulting +capability set. The full value tables live in the +[reference](../reference/host-integration-interface.md#the-eight-negotiated-axes); +what matters conceptually is that these axes describe the *shape* of a host, +not its identity — a terminal CLI and a VS Code extension are simply +different points in the same eight-dimensional space, not different kinds of +thing the engine has to special-case. + +**A `PROTOCOL_VERSION` handshake** ties the two together over time. A host +declares the interface version it targets; the engine negotiates down to +`min(host, engine)` rather than refusing to talk. A host newer than the +running engine gets a warning, not a crash — its declared axes beyond the +engine's version are simply not trusted. What counts as an additive change +versus a version-bumping breaking one, and how long a deprecated value stays +usable, is the subject of its own document: +[Interface versioning and deprecation policy](interface-versioning-policy.md). + +Underpinning all of it is the `undocumented` sentinel: the permanent, +fail-closed fallback for an axis a host says nothing about. GSD never +*guesses* a host's capability from context — a host that omits an axis gets +the safe default for that axis, never an assumed one. + +## Two adapter shapes: imperative and declarative + +The single most useful mental model for a given host integration is which of +two adapter shapes it uses, set by the `embeddingMode` axis. + +**Imperative** hosts can run GSD's own shell preamble or programmatic +dispatch directly at invocation time (`embeddingMode: imperative`). The host +hands control to GSD's runtime launcher and GSD does the rest, live, on every +invocation. Most CLI-style and IDE-embedded hosts work this way — OpenCode, +Cursor, Cline, Hermes, Qwen, Kilo, Trae, Kimi, Antigravity, and Augment are +all imperative integrations. + +**Declarative** hosts cannot run arbitrary code at dispatch time. They +consume static, generated artifacts — frontmatter, config, or another format +baked at install time — and interpret them through their own, fixed dispatch +mechanism (`embeddingMode: declarative`). Codex is the current declarative +host. + +The consequence of that split is concrete, not academic: a declarative +host's model configuration is fixed at install time, because there is no +live dispatch step at which GSD could re-resolve it. If the model +configuration changes after install, a declarative host is silently stale +until the next reinstall — which is why GSD warns when a declarative host's +model configuration changes without a matching reinstall (#1688). An +imperative host has no equivalent gap, because it re-runs GSD's dispatch +logic on every invocation. + +Three **host-capability profiles** — `programmatic-cli`, `declarative-cli`, +and `ide` — give the axis combinations for the reference cases GSD actually +targets: a baseline imperative CLI, a baseline declarative CLI, and a +baseline IDE (active model mode, engine-owned hook bus, sandboxed storage). +See `PROFILE_BASELINES` in the reference for the exact axis values each +profile fixes. + +## What 1.7.0 delivered on top of the contract + +1.7.0 both published the interface (Phase A, #1690) and put it to work at +scale in the same cycle. Fourteen runtimes moved onto the public interface via adapters +(#2087–#2100) — existing bespoke integrations were rewritten to express +themselves as EoS descriptors rather than as ad hoc code. + +Three new hosts joined over the same window, each exercising a different +part of the interface: ZCode (#1925), pi (#2102), and a VS Code extension +driven entirely through the adapter layer (#2103). Gemini CLI was retired in +favor of its successor, Antigravity, which shares its underlying +infrastructure (#1928). + +A companion `gsd-mcp-server` (#1681) gives hosts that prefer an MCP +transport a way to reach interface points 1 and 5 (`command` and `state`) +without implementing the shell-preamble dispatch path themselves — a second +transport onto the same contract, not a second contract. + +The clearest evidence that the contract is doing its job: because every host +integration is now expressed as data — a descriptor, not bespoke code — +`/gsd:surface` can reproduce a given runtime's generated agent output +byte-for-byte from the same descriptors the installer itself consumes +(#1575). Runtime output can no longer drift from what the installer +produces, because there is only one source of truth for it. + +## Where EoS ends and Capabilities begin + +EoS is easy to conflate with GSD's other extensibility axis, Capabilities +(ADR-857, ADR-1244), because both are commonly described as "third parties +extending GSD." They answer different questions, and the distinction matters +for anyone building against either surface. + +**EoS is about *where* GSD runs** — which host application embeds the +orchestration engine, and how that host's command surface, model routing, +hook bus, and storage bind to the engine. **Capabilities are about *what* +GSD does** — feature plug-ins that attach at GSD's Loop Extension Points +inside the loop that is already running. A host integration and a capability +are orthogonal axes: the same capability behaves identically regardless of +which host is running the loop, and the same host runs any composed set of +capabilities without knowing anything about them. + +Each has its own non-endorsing discoverability registry (#2182): the **EoS +Registry** lists third-party host integrations, and the **Community +Capability Registry** lists third-party capabilities. Both share one entry +schema shape, one non-endorsement stance, and one submission process — see +[GSD Registries](../registries/README.md) for the full specification of +both. + +## Why a published interface — and what it costs + +Publishing a stable, versioned interface is a deliberate trade. The moment +an external host depends on `PROTOCOL_VERSION` 1's axis vocabulary, that +vocabulary becomes a long-term compatibility commitment — Hyrum's Law +applies in full: whatever a host observably depends on becomes part of the +contract, whether or not it was meant to be. That is the cost, and it is why +the [versioning policy](interface-versioning-policy.md) exists as a +separate, disciplined document rather than an informal understanding. + +The benefit is the reason 1.7.0's fourteen-runtime migration and three new +hosts were tractable at all: a new host is additive descriptor work against +a published contract, not a fork of GSD's engine internals. A third-party +host author can build and test an integration against the documented axis +vocabulary without waiting on, or coordinating with, the core team — the +same posture the EoS Registry's non-endorsement stance formalizes for +discoverability. The interface is what makes "many hosts, one engine" a +scalable design rather than a maintenance burden that grows linearly with +every new host. + +## See also + +- [Reference: the Host-Integration Interface](../reference/host-integration-interface.md) +- [Interface versioning and deprecation policy](interface-versioning-policy.md) +- [GSD Registries](../registries/README.md) +- [How overlay capabilities compose](capability-overlay-model.md) +- [What's new in 1.7.0](../whats-new-1.7.0.md) diff --git a/docs/whats-new-1.7.0.md b/docs/whats-new-1.7.0.md new file mode 100644 index 000000000..c30f9ae2f --- /dev/null +++ b/docs/whats-new-1.7.0.md @@ -0,0 +1,102 @@ +# What's new in GSD Core 1.7.0 + +1.7.0 is the largest surface-expansion release to date since 1.6.1: 32 new features, 44 changes, 100 fixes, and 4 security hardenings. The per-command and per-agent reference (`COMMANDS.md`, `AGENTS.md`, `INVENTORY.md`) is kept current continuously; this page is the thematic tour of what changed and why. For the full per-fragment record, see [`CHANGELOG.md`](../CHANGELOG.md). + +--- + +## Embeddable Orchestration System (EoS): one contract, many hosts + +1.7.0 promotes GSD's host integration onto a single **public, versioned Host-Integration Interface** (ADR-1239 Phase A, #1690): six interface points (command, dispatch, model, hooks, state, artifact), eight negotiated axes, and a `PROTOCOL_VERSION` handshake. Descriptors gained an `extensionEvents` vocabulary (#1946). + +**14 runtimes now driven through that public interface** instead of bespoke wiring — via *imperative* adapters (OpenCode #2087, Cursor #2089, Cline #2090, Hermes #2091, Qwen #2092, Kilo #2093, Trae #2094, Kimi #2095, Antigravity #2096, Augment #2097) and a *declarative* adapter (Codex #2088), plus full lifecycle-hook wiring for CodeBuddy (#2098), GitHub Copilot (#2099), and Windsurf (#2100). Per-host upgrades landed alongside: Qwen projects GSD's specialist agents as native subagents; Kilo gains native hooks, active-model routing, and named subagent dispatch; Trae carries SOLO stage metadata; Antigravity and Augment register native MCP companions. + +**New installable runtimes:** ZCode (Z.ai — a desktop Agentic Development Environment for GLM-5.2, #1925), pi (`npx @opengsd/gsd-core --pi`, #2102), and a repo-local VS Code extension (#1966), now driven through the EoS adapter (#2103). + +**Gemini CLI removed** (#1928): Google discontinued Gemini CLI on 2026-06-18, so `--gemini` now prints a deprecation notice pointing to Antigravity CLI, the official successor and already a first-class GSD runtime. + +`/gsd:surface` and `--materialize` now produce byte-identical agent output to a fresh install for descriptor-driven runtimes (#1575). + +Read more: [Embeddable Orchestration System](explanation/embeddable-orchestration-system.md) · [Host-Integration Interface reference](reference/host-integration-interface.md) · [Interface versioning policy](explanation/interface-versioning-policy.md) · [Install on your runtime](how-to/install-on-your-runtime.md). + +--- + +## Discoverability registries + +Two new **non-endorsing** discoverability catalogs (#2182): the **Community Capability Registry** (#2188) for third-party Feature Capabilities installed with `gsd capability install`, and the **EoS Registry** (#2193) for third-party host integrations built on the ADR-1239 interface. Each entry embeds a live release badge and links to a GitHub Discussion. Submitting an entry is a documentation PR (`npm run gen:registry`). + +See [GSD Registries](registries/README.md). + +--- + +## Companion MCP server + +New **`gsd-mcp-server`** companion MCP server — a stdio JSON-RPC 2.0 server covering interface points 1 and 5 (#1681). OpenCode installs now auto-register it as `mcp.gsd` (#1682). OpenCode also gained the `opencode-subset` hook dialect and `session.idle` handling (#1682), and now runs GSD's lifecycle safety hooks — prompt-injection guard, read-before-edit guard, and injection scanner (#1923). + +--- + +## Model catalog advances + +- Codex / OpenAI defaults advance to the **GPT-5.6 family** (Sol / Terra / Luna) (#2122). +- The verbose `(1M context)` model suffix is collapsed to a compact `(1M)` badge (#2160). +- GSD now warns when model config changed without re-running the installer on static-frontmatter runtimes such as Codex and OpenCode (#1688). + +See [Configuration — model profiles](CONFIGURATION.md) and [Configure model profiles](how-to/configure-model-profiles.md). + +--- + +## Statusline & compact state + +- Opt-in **absolute token count** on the statusline context meter via new `statusline.*` config (#2161). +- Opt-in **git branch + working-state segment** in the statusline (#2163). +- Opt-in **compact GSD-state format** for the statusline (#2162). + +--- + +## Capabilities framework + +- A default-off, BETA, Claude-only **Claude orchestration capability** that adopts Claude Code's Workflow tool (#1143) — see the [explanation](explanation/claude-orchestration-capability.md). +- A default-off **external-job capability** to externalize long-running compute as async jobs (SLURM submission) (#1165), configured via `external_job.submit_timeout_ms` / `poll_timeout_ms` / `artifact_dir` (#1164). +- Third-party capability gates now fire through a generic **`command-exit-zero`** predicate (#2008); a capability that fails to load now fails **open** with a loud warning instead of blocking the whole project (#2009). + +--- + +## Planning, verification & workflow + +- The **API-coverage gate** (#1562): a phase that integrates an external API/SDK/service cannot seal `/gsd:verify-work` without a decided coverage matrix. +- `plan-phase` now authors edge and prohibition predicates into `PLAN.md` `must_have` (#1154), and the **honest verifier** abstains (`human_needed`) on non-inferable `backstop` truths instead of confidently false-passing them (#1154). +- A plural/optional/chosen **assumption-delta checkpoint** during planning re-asks identity-model questions when cardinality changes (#1561). +- `/gsd-ui-phase` gains a **UI state-coverage probe** (#1979); `/gsd-review` supports **custom reviewer instances** (#1517). +- New `gsd-tools state rebuild` re-derives STATE from source (#1830); `graphify.graph_path` makes the knowledge-graph location configurable so one umbrella graph can serve several projects (#1825). +- GSD subagents now self-load configured `agent_skills` regardless of orchestrator bash (#1866); GSD warns when a stale global CLI shadows your project-local install (#1754). + +--- + +## Security hardening + +| Area | Change | +|---|---| +| Human-gated checkpoints | `gate="blocking-human"` checkpoints are no longer auto-approved by the execute-phase orchestrator; the package-legitimacy gate escalates them for human vetting (#2107). | +| Parser DoS | Phase/roadmap/plan markdown parsing hardened against quadratic-time (ReDoS) CPU exhaustion (#2128). | +| Install confinement | Installer writes are confined to the declared config home — crafted/absolute paths, path-separator agent names, and pre-existing escaping symlinks are refused before any write (#1725). | +| Descriptor confinement | The installer rejects any runtime-descriptor `destSubpath` that would write or delete outside the user's config home — path traversal, the config root itself, NUL bytes, escaping symlinks (ADR-1239 Phase B, #1706). | + +--- + +## Fixes at a glance + +100 fixes landed in this release, clustered around a handful of recurring themes rather than listed individually: + +- **Markdown table & phase/roadmap/state integrity** — edits confined to their own section, milestone-grouped ROADMAP progress tables read by column name, foreign-prefixed IDs no longer collapse to numeric phases (#2056, #2104, #2137, #2253). +- **Windows & cross-platform** — PowerShell hooks (#2236), Linuxbrew node path (#2185), CRLF-safe STATE parsing (#2253), Windows path-quoting and a `find.exe` storm (#2020, #1746). +- **Cross-AI reviewers** — Antigravity (#2073, #2176), OpenCode (#1936), and Codex (#1709) reviewers no longer silently return empty or blind reviews. +- **Capabilities & install** — third-party capability skills now surface after install (#2054), `capability state` / `loop render-hooks` accept `--runtime` (#2003), the installer host-version gate accepts real `engines.gsd` (#1938). +- **Config & state** — `config-set null` now clears the key (#2058), custom STATE.md frontmatter keys are preserved across mutations (#2202). +- **Ship, verify & milestone lifecycle** — `/gsd-ship` now pushes its STATE note (#2138), verify-work preserves state across gap-closure (#1921), `milestone complete` no longer closes out of order (#2111) and honors `--dry-run` (#2118). + +See [`CHANGELOG.md`](../CHANGELOG.md) for the complete, itemized list. + +--- + +## See also + +- [Feature reference](FEATURES.md) · [Embeddable Orchestration System](explanation/embeddable-orchestration-system.md) · [GSD Registries](registries/README.md) · [Full changelog](../CHANGELOG.md) · [docs index](README.md)